# Implementation Plan: Project Schedule Tools

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

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

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