xer-mcp/specs/001-schedule-tools/quickstart.md

# 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