docs: add README with installation and usage instructions
This commit is contained in:
220
README.md
Normal file
220
README.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user