# Implementation Plan: Project Schedule Tools

**Branch**: `001-schedule-tools` | **Date**: 2026-01-08 | **Spec**: [spec.md](./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)

```text
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)

```text
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.