docs: add implementation plan and clarify no-file-loaded errors
Plan artifacts: - plan.md: Technical context, constitution check, project structure - research.md: XER format, MCP SDK, SQLite schema decisions - data-model.md: Entity definitions and database schema - contracts/mcp-tools.json: MCP tool schemas (9 tools) - quickstart.md: Usage guide with examples - CLAUDE.md: Agent context file Spec updates: - Add FR-015: NO_FILE_LOADED error requirement - Add acceptance scenarios for no-file-loaded errors to US3, US4
This commit is contained in:
270
specs/001-schedule-tools/quickstart.md
Normal file
270
specs/001-schedule-tools/quickstart.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# Quickstart: XER MCP Server
|
||||
|
||||
This guide shows how to set up and use the XER MCP Server for querying Primavera P6 schedule data.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.14+
|
||||
- uv package manager
|
||||
- An XER file exported from Primavera P6
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repo-url>
|
||||
cd xer-mcp
|
||||
|
||||
# Install dependencies with uv
|
||||
uv sync
|
||||
|
||||
# Verify installation
|
||||
uv run python -m xer_mcp --help
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Add the server to your MCP client configuration (e.g., Claude Desktop):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"xer-mcp": {
|
||||
"command": "uv",
|
||||
"args": ["run", "python", "-m", "xer_mcp"],
|
||||
"cwd": "/path/to/xer-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### 1. Load an XER File
|
||||
|
||||
```
|
||||
Use the load_xer tool with file_path="/path/to/schedule.xer"
|
||||
```
|
||||
|
||||
**Response** (single project):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"project": {
|
||||
"proj_id": "P001",
|
||||
"proj_short_name": "Construction Phase 1",
|
||||
"plan_start_date": "2026-01-15T00:00:00",
|
||||
"plan_end_date": "2026-06-30T00:00:00"
|
||||
},
|
||||
"activity_count": 450,
|
||||
"relationship_count": 520
|
||||
}
|
||||
```
|
||||
|
||||
**Response** (multi-project, no selection):
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"available_projects": [
|
||||
{"proj_id": "P001", "proj_short_name": "Phase 1"},
|
||||
{"proj_id": "P002", "proj_short_name": "Phase 2"}
|
||||
],
|
||||
"message": "Multiple projects found. Please specify project_id."
|
||||
}
|
||||
```
|
||||
|
||||
### 2. List Activities
|
||||
|
||||
```
|
||||
Use the list_activities tool
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"activities": [
|
||||
{
|
||||
"task_id": "A1000",
|
||||
"task_code": "A1000",
|
||||
"task_name": "Site Preparation",
|
||||
"task_type": "TT_Task",
|
||||
"target_start_date": "2026-01-15T08:00:00",
|
||||
"target_end_date": "2026-01-22T17:00:00",
|
||||
"status_code": "TK_NotStart",
|
||||
"driving_path_flag": true
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total_count": 450,
|
||||
"offset": 0,
|
||||
"limit": 100,
|
||||
"has_more": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Filter Activities by Date Range
|
||||
|
||||
```
|
||||
Use the list_activities tool with start_date="2026-02-01" and end_date="2026-02-28"
|
||||
```
|
||||
|
||||
### 4. Get Activity Details
|
||||
|
||||
```
|
||||
Use the get_activity tool with activity_id="A1000"
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"task_id": "A1000",
|
||||
"task_code": "A1000",
|
||||
"task_name": "Site Preparation",
|
||||
"task_type": "TT_Task",
|
||||
"wbs_id": "WBS001",
|
||||
"wbs_name": "Pre-Construction",
|
||||
"target_start_date": "2026-01-15T08:00:00",
|
||||
"target_end_date": "2026-01-22T17:00:00",
|
||||
"act_start_date": null,
|
||||
"act_end_date": null,
|
||||
"total_float_hr_cnt": 0,
|
||||
"status_code": "TK_NotStart",
|
||||
"driving_path_flag": true,
|
||||
"predecessor_count": 0,
|
||||
"successor_count": 5
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Query Predecessors/Successors
|
||||
|
||||
```
|
||||
Use the get_predecessors tool with activity_id="A1050"
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"activity_id": "A1050",
|
||||
"predecessors": [
|
||||
{
|
||||
"task_id": "A1000",
|
||||
"task_code": "A1000",
|
||||
"task_name": "Site Preparation",
|
||||
"relationship_type": "FS",
|
||||
"lag_hr_cnt": 0
|
||||
},
|
||||
{
|
||||
"task_id": "A1010",
|
||||
"task_code": "A1010",
|
||||
"task_name": "Permits Approved",
|
||||
"relationship_type": "FS",
|
||||
"lag_hr_cnt": 8
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Get Project Summary
|
||||
|
||||
```
|
||||
Use the get_project_summary tool
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"project": {
|
||||
"proj_id": "P001",
|
||||
"proj_short_name": "Construction Phase 1",
|
||||
"plan_start_date": "2026-01-15T00:00:00",
|
||||
"plan_end_date": "2026-06-30T00:00:00"
|
||||
},
|
||||
"activity_count": 450,
|
||||
"milestone_count": 25,
|
||||
"relationship_count": 520,
|
||||
"wbs_element_count": 30,
|
||||
"critical_activity_count": 85
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Get Critical Path
|
||||
|
||||
```
|
||||
Use the get_critical_path tool
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"critical_activities": [
|
||||
{
|
||||
"task_id": "A1000",
|
||||
"task_code": "A1000",
|
||||
"task_name": "Site Preparation",
|
||||
"task_type": "TT_Task",
|
||||
"target_start_date": "2026-01-15T08:00:00",
|
||||
"target_end_date": "2026-01-22T17:00:00"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total_count": 85,
|
||||
"offset": 0,
|
||||
"limit": 100,
|
||||
"has_more": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 8. List Milestones
|
||||
|
||||
```
|
||||
Use the list_milestones tool
|
||||
```
|
||||
|
||||
## Pagination
|
||||
|
||||
All list operations support pagination:
|
||||
|
||||
```
|
||||
Use the list_activities tool with limit=50 and offset=100
|
||||
```
|
||||
|
||||
This returns activities 101-150 (0-indexed).
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Meaning | Solution |
|
||||
|-------|---------|----------|
|
||||
| FILE_NOT_FOUND | XER file path doesn't exist | Check file path |
|
||||
| PARSE_ERROR | XER file is malformed | Verify file is valid P6 export |
|
||||
| NO_FILE_LOADED | Query before load_xer | Call load_xer first |
|
||||
| PROJECT_SELECTION_REQUIRED | Multi-project file | Specify project_id in load_xer |
|
||||
| ACTIVITY_NOT_FOUND | Invalid activity_id | Check activity exists |
|
||||
|
||||
## Relationship Types
|
||||
|
||||
| Code | Name | Meaning |
|
||||
|------|------|---------|
|
||||
| FS | Finish-to-Start | B starts after A finishes |
|
||||
| SS | Start-to-Start | B starts after A starts |
|
||||
| FF | Finish-to-Finish | B finishes after A finishes |
|
||||
| SF | Start-to-Finish | B finishes after A starts |
|
||||
|
||||
## Activity Types
|
||||
|
||||
| Code | Name | Description |
|
||||
|------|------|-------------|
|
||||
| TT_Task | Task | Normal work activity with duration |
|
||||
| TT_Mile | Milestone | Zero-duration marker |
|
||||
| TT_LOE | Level of Effort | Duration spans linked activities |
|
||||
| TT_WBS | WBS Summary | Summary of child activities |
|
||||
| TT_Rsrc | Resource Dependent | Duration from resource assignment |
|
||||
|
||||
## Tips for AI Assistants
|
||||
|
||||
1. **Start with summary**: Call `get_project_summary` first to understand scope
|
||||
2. **Use pagination**: Large schedules may have thousands of activities
|
||||
3. **Filter early**: Use date ranges and WBS filters to reduce results
|
||||
4. **Check critical path**: `get_critical_path` identifies schedule-driving work
|
||||
5. **Follow relationships**: Use `get_predecessors`/`get_successors` to trace dependencies
|
||||
Reference in New Issue
Block a user