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

Implementation Plan: Project Schedule Tools

Branch: 001-schedule-tools | Date: 2026-01-06 | Spec: spec.md Input: Feature specification from /specs/001-schedule-tools/spec.md

Summary

Build an MCP server that parses Primavera P6 XER files and exposes schedule data (activities, relationships, project summaries) through MCP tools. The server uses stdio transport, loads XER data into SQLite for efficient querying, and implements pagination to prevent context overflow for AI assistants.

Technical Context

Language/Version: Python 3.14 Package Manager: uv Primary Dependencies: mcp (MCP SDK), sqlite3 (stdlib) Storage: SQLite (in-memory or file-based per session) Testing: pytest with pytest-asyncio for async MCP handlers Target Platform: Linux/macOS/Windows (cross-platform CLI) Transport: stdio (standard input/output) Project Type: Single project Performance Goals: Load 10,000 activities in <5 seconds; query response <1 second Constraints: Default 100-item pagination limit; single-user operation Scale/Scope: Files up to 50,000 activities

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Principle	Requirement	Status	Notes
I. Test-First Development	TDD mandatory; tests fail before implementation	✅ PASS	Plan includes contract tests for MCP tools, integration tests for XER parsing
II. Extensibility Architecture	Pluggable handlers; separated concerns	✅ PASS	XER parser separated from MCP layer; table handlers pluggable
III. MCP Protocol Compliance	Complete JSON schemas; proper error format	✅ PASS	All tools will have full schemas; errors follow MCP format
IV. XER Format Fidelity	No data loss; preserve precision	✅ PASS	SQLite preserves all parsed data; unknown tables stored
V. Semantic Versioning	SemVer for releases	✅ PASS	Will use 0.1.0 for initial release

Technical Standards Compliance:

• Python 3.14 ✅
• Type hints throughout ✅
• Formatting via ruff ✅
• Dependencies pinned in pyproject.toml ✅
• Console logging ✅

Project Structure

Documentation (this feature)

specs/001-schedule-tools/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output (MCP tool schemas)
└── tasks.md             # Phase 2 output (/speckit.tasks command)

Source Code (repository root)

src/
├── xer_mcp/
│   ├── __init__.py
│   ├── server.py           # MCP server entry point (stdio)
│   ├── tools/              # MCP tool implementations
│   │   ├── __init__.py
│   │   ├── load_xer.py
│   │   ├── list_activities.py
│   │   ├── get_activity.py
│   │   ├── list_relationships.py
│   │   ├── get_predecessors.py
│   │   ├── get_successors.py
│   │   ├── get_project_summary.py
│   │   ├── list_milestones.py
│   │   └── get_critical_path.py
│   ├── parser/             # XER file parsing
│   │   ├── __init__.py
│   │   ├── xer_parser.py   # Main parser
│   │   └── table_handlers/ # Pluggable table handlers
│   │       ├── __init__.py
│   │       ├── base.py     # Abstract base class
│   │       ├── project.py
│   │       ├── task.py
│   │       ├── taskpred.py
│   │       ├── projwbs.py
│   │       └── calendar.py
│   ├── db/                 # SQLite database layer
│   │   ├── __init__.py
│   │   ├── schema.py       # Table definitions
│   │   ├── loader.py       # Load parsed data into SQLite
│   │   └── queries.py      # Query functions with pagination
│   └── models/             # Data models (dataclasses)
│       ├── __init__.py
│       ├── project.py
│       ├── activity.py
│       ├── relationship.py
│       └── pagination.py

tests/
├── conftest.py             # Shared fixtures (sample XER files)
├── contract/               # MCP tool contract tests
│   ├── test_load_xer.py
│   ├── test_list_activities.py
│   ├── test_get_activity.py
│   ├── test_list_relationships.py
│   ├── test_get_predecessors.py
│   ├── test_get_successors.py
│   ├── test_get_project_summary.py
│   ├── test_list_milestones.py
│   └── test_get_critical_path.py
├── integration/            # End-to-end XER parsing tests
│   ├── test_xer_parsing.py
│   ├── test_multi_project.py
│   └── test_edge_cases.py
└── unit/                   # Unit tests for parser, db, models
    ├── test_parser.py
    ├── test_table_handlers.py
    ├── test_db_queries.py
    └── test_models.py

pyproject.toml              # Project config with uv

Structure Decision: Single project structure with clear separation between MCP tools, XER parsing, and SQLite database layers. The parser/table_handlers/ directory enables extensibility for future XER table types.

Complexity Tracking

No constitution violations requiring justification. Design follows all principles.