# XER MCP Server

An MCP (Model Context Protocol) server for parsing Primavera P6 XER files and exposing schedule data to AI assistants.

## Features

- Parse Primavera P6 XER export files
- Query activities, relationships, milestones, and critical path
- Pagination support with configurable limits
- Multi-project file support
- In-memory SQLite database for fast queries

## Installation

Requires Python 3.12+

```bash
# Clone the repository
git clone https://git.prettyhefty.com/Bill/xer-mcp.git
cd xer-mcp

# Install with uv
uv sync

# Or install with pip
pip install -e .
```

## Configuration

### Claude Desktop

Add to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json` on Linux, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "xer-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/xer-mcp", "python", "-m", "xer_mcp"]
    }
  }
}
```

### Other MCP Clients

Run the server directly:

```bash
uv run python -m xer_mcp
```

The server communicates via stdio using the MCP protocol.

## Available Tools

### load_xer

Load a Primavera P6 XER file for querying.

**Parameters:**
- `file_path` (required): Absolute path to the XER file
- `project_id` (optional): Project ID to select (required for multi-project files)

**Example:**
```json
{
  "file_path": "/path/to/schedule.xer"
}
```

### list_activities

List activities with optional filtering and pagination.

**Parameters:**
- `start_date` (optional): Filter activities starting on or after (YYYY-MM-DD)
- `end_date` (optional): Filter activities ending on or before (YYYY-MM-DD)
- `wbs_id` (optional): Filter by WBS element ID
- `activity_type` (optional): Filter by type (TT_Task, TT_Mile, TT_LOE, TT_WBS, TT_Rsrc)
- `limit` (optional): Maximum results (default: 100, max: 1000)
- `offset` (optional): Number of results to skip (default: 0)

**Returns:** List of activities with pagination metadata

### get_activity

Get detailed information for a specific activity.

**Parameters:**
- `activity_id` (required): The task_id of the activity

**Returns:** Activity details including WBS name and relationship counts

### list_relationships

List all activity relationships (dependencies) with pagination.

**Parameters:**
- `limit` (optional): Maximum results (default: 100, max: 1000)
- `offset` (optional): Number of results to skip (default: 0)

**Returns:** List of relationships with predecessor/successor info

### get_predecessors

Get predecessor activities for a given activity.

**Parameters:**
- `activity_id` (required): The task_id of the activity

**Returns:** List of predecessor activities with relationship type and lag

### get_successors

Get successor activities for a given activity.

**Parameters:**
- `activity_id` (required): The task_id of the activity

**Returns:** List of successor activities with relationship type and lag

### get_project_summary

Get a summary of the loaded project.

**Parameters:** None

**Returns:**
- `project_name`: Name of the project
- `plan_start_date`: Planned start date
- `plan_end_date`: Planned end date
- `activity_count`: Total number of activities
- `milestone_count`: Number of milestones
- `critical_activity_count`: Number of activities on critical path

### list_milestones

List all milestone activities in the project.

**Parameters:** None

**Returns:** List of milestone activities with dates and status

### get_critical_path

Get all activities on the critical path.

**Parameters:** None

**Returns:** List of critical path activities ordered by start date

## Usage Example

1. First, load an XER file:
   ```
   Use the load_xer tool with file_path: "/path/to/my-schedule.xer"
   ```

2. Get a project overview:
   ```
   Use the get_project_summary tool
   ```

3. List upcoming milestones:
   ```
   Use the list_milestones tool
   ```

4. View critical path:
   ```
   Use the get_critical_path tool
   ```

5. Query specific activities:
   ```
   Use list_activities with start_date: "2026-01-01" and end_date: "2026-03-31"
   ```

## Error Handling

All query tools return a `NO_FILE_LOADED` error if called before loading an XER file:

```json
{
  "error": {
    "code": "NO_FILE_LOADED",
    "message": "No XER file is loaded. Use the load_xer tool first."
  }
}
```

## Relationship Types

The server supports all P6 relationship types:
- **FS** (Finish-to-Start): Successor starts after predecessor finishes
- **SS** (Start-to-Start): Successor starts when predecessor starts
- **FF** (Finish-to-Finish): Successor finishes when predecessor finishes
- **SF** (Start-to-Finish): Successor finishes when predecessor starts

## Development

```bash
# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=xer_mcp

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/
```

## License

MIT