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

Implementation Plan: Project Schedule Tools

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

Summary

Build an MCP server that provides 9 tools for querying Primavera P6 XER schedule data. The server parses XER files into an in-memory SQLite database and exposes tools for loading files, querying activities, relationships, milestones, critical path, and project summary. Uses Python 3.14 with the MCP SDK and follows TDD practices per the project constitution.

Technical Context

Language/Version: Python 3.14 Primary Dependencies: mcp>=1.0.0 (MCP SDK), sqlite3 (stdlib) Storage: In-memory SQLite database (populated from XER files at runtime) Testing: pytest>=8.0.0, pytest-asyncio>=0.24.0 Target Platform: Local server (Linux/macOS/Windows with file system access) Project Type: Single project Performance Goals: Load + query XER files ≤5 seconds for 10,000 activities; query response <1 second Constraints: Memory sufficient for 50,000 activities; single-user operation Scale/Scope: MCP server with 9 tools; handles typical P6 project 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	Contract tests for all 9 MCP tools; integration tests for XER parsing
II. Extensibility Architecture	Core parsing separate from MCP transport; pluggable handlers	✅ PASS	Table handlers are pluggable (parser/table_handlers/); tools are modular (tools/)
III. MCP Protocol Compliance	Complete JSON schemas; MCP error format; compliant transport	✅ PASS	Using official MCP SDK; tool definitions include JSON schemas
IV. XER Format Fidelity	No data loss; preserve precision; handle all standard tables	✅ PASS	Parsing TASK, TASKPRED, PROJECT, PROJWBS, CALENDAR; dates preserve precision
V. Semantic Versioning	SemVer for releases; breaking changes documented	✅ PASS	Version 0.1.0; initial development phase
Technical Standards	Python 3.14; type hints; ruff formatting	✅ PASS	pyproject.toml configured for Python 3.14, ruff, pytest

Gate Result: PASS - All constitution principles satisfied. Proceed to Phase 0.

Project Structure

Documentation (this feature)

specs/001-schedule-tools/
├── spec.md              # Feature specification
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

src/xer_mcp/
├── __init__.py
├── __main__.py              # Entry point
├── server.py                # MCP server setup and tool registration
├── errors.py                # Error types
├── models/                  # Data models (dataclasses)
│   ├── __init__.py
│   ├── project.py
│   ├── activity.py
│   ├── relationship.py
│   ├── wbs.py
│   ├── calendar.py
│   └── pagination.py
├── parser/                  # XER file parsing
│   ├── __init__.py
│   ├── xer_parser.py        # Main parser
│   └── table_handlers/      # Pluggable table handlers
│       ├── __init__.py
│       ├── base.py
│       ├── project.py
│       ├── task.py
│       ├── taskpred.py
│       ├── projwbs.py
│       └── calendar.py
├── db/                      # SQLite database layer
│   ├── __init__.py
│   ├── schema.py            # Table definitions
│   ├── loader.py            # Data loading
│   └── queries.py           # Query functions
└── 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

tests/
├── __init__.py
├── conftest.py              # Shared fixtures
├── contract/                # MCP tool contract tests
│   ├── __init__.py
│   ├── 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/             # XER parsing integration tests
│   ├── __init__.py
│   └── test_xer_parsing.py
└── unit/                    # Unit tests
    ├── __init__.py
    ├── test_parser.py
    ├── test_table_handlers.py
    └── test_db_queries.py

Structure Decision: Single project structure with domain-specific organization: models/ for data structures, parser/ for XER file handling with pluggable table handlers, db/ for SQLite storage layer, and tools/ for MCP tool implementations. Tests follow contract/integration/unit hierarchy per constitution requirements.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

No violations. All constitution principles satisfied.

Post-Design Constitution Re-Check

Re-evaluation after Phase 1 design artifacts are complete.

Principle	Status	Verification
I. Test-First Development	✅ PASS	Contract tests defined in tests/contract/ for all 9 tools; integration tests in tests/integration/
II. Extensibility Architecture	✅ PASS	Table handlers pluggable via registry pattern; tools are modular functions; schema separates concerns
III. MCP Protocol Compliance	✅ PASS	contracts/mcp-tools.json defines complete JSON schemas for all tools with input/output schemas
IV. XER Format Fidelity	✅ PASS	Data model preserves all date precision; handles all 5 standard tables; driving flag computed accurately
V. Semantic Versioning	✅ PASS	Version 0.1.0 in contract schema; following SemVer
Technical Standards	✅ PASS	Type hints throughout models; ruff configured; pytest async mode enabled

Post-Design Gate Result: PASS - Design artifacts align with constitution. Ready for task generation.

Generated Artifacts

Artifact	Path	Description
Research	specs/001-schedule-tools/research.md	Technology decisions, XER format analysis, driving flag computation
Data Model	specs/001-schedule-tools/data-model.md	Entity definitions, SQLite schema, validation rules
Contracts	specs/001-schedule-tools/contracts/mcp-tools.json	MCP tool JSON schemas (input/output)
Quickstart	specs/001-schedule-tools/quickstart.md	Usage guide with examples
Agent Context	CLAUDE.md	Updated with Python 3.14, MCP SDK, SQLite

Next Steps

Run /speckit.tasks to generate implementation tasks from this plan.