Bill/xer-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add milestone_type field to distinguish start/finish milestones

Browse Source 
Add milestone_type field to milestone queries that indicates whether
a milestone is a start milestone ('start') or finish milestone ('finish').

Changes:
- Add milestone_type column to activities table schema
- Parse milestone_type from XER TASK table (MS_Start/MS_Finish)
- Include milestone_type in list_milestones response
- Update contract tests for milestone_type field
- Update specs, contracts, and documentation

The milestone_type is determined by:
1. Explicit milestone_type field in XER (MS_Start -> 'start', MS_Finish -> 'finish')
2. Derived from task_type (TT_Mile -> 'start', TT_FinMile -> 'finish')
This commit is contained in:
Bill Ballou
2026-01-08 12:18:34 -05:00
parent bf2f85813e
commit a7b6b76db8
13 changed files with 345 additions and 198 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
specs/001-schedule-tools/plan.md
View File

@@ -1,47 +1,38 @@
# Implementation Plan: Add Driving Flag to Relationships
# Implementation Plan: Project Schedule Tools
**Branch**: `001-schedule-tools` | **Date**: 2026-01-06 | **Spec**: [spec.md](./spec.md)
**Branch**: `001-schedule-tools` | **Date**: 2026-01-08 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-schedule-tools/spec.md`
## Summary
Extend the existing XER MCP Server implementation to include the "driving" flag in all relationship query responses. This requires updating the database schema, XER parser, and query functions to extract and return the driving relationship indicator from Primavera P6 schedule data.
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 (MCP SDK), sqlite3 (stdlib)
**Storage**: SQLite in-memory database
**Testing**: pytest, pytest-asyncio
**Target Platform**: Linux server (local MCP server)
**Project Type**: single
**Performance Goals**: Query response < 1 second, load < 5 seconds for 10k activities
**Constraints**: Single-user operation, in-memory storage for loaded XER data
**Scale/Scope**: Files up to 50,000 activities
**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 | Status | Evidence/Notes |
|-----------|--------|----------------|
| I. Test-First Development | ✅ PASS | TDD required - write failing tests first for driving flag in relationship responses |
| II. Extensibility Architecture | ✅ PASS | Current design already separates parser → db → query → tool layers |
| III. MCP Protocol Compliance | ✅ PASS | Tool schemas already JSON Schema compliant; no schema changes needed |
| IV. XER Format Fidelity | ✅ PASS | Must parse `driving_flag` from TASKPRED table in XER files |
| V. Semantic Versioning | ✅ PASS | Adding new field to response is backward-compatible (MINOR) |
| 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 |
**Pre-design Status**: All gates PASS
**Post-design Status** (re-evaluated after Phase 1):
| Principle | Status | Evidence/Notes |
|-----------|--------|----------------|
| I. Test-First Development | ✅ PASS | Tests will verify: (1) early dates parsed from TASK, (2) driving computed correctly, (3) driving included in all relationship responses |
| II. Extensibility Architecture | ✅ PASS | Driving computation is isolated in query layer; no changes to parser or model structure |
| III. MCP Protocol Compliance | ✅ PASS | Response schema updated in contracts/mcp-tools.json |
| IV. XER Format Fidelity | ✅ PASS | Research confirmed: driving is computed from schedule dates (matching P6 behavior), not stored in XER |
| V. Semantic Versioning | ✅ PASS | Adding `driving` field is backward-compatible (MINOR version bump)
**Gate Result**: PASS - All constitution principles satisfied. Proceed to Phase 0.
## Project Structure
@@ -49,53 +40,116 @@ Extend the existing XER MCP Server implementation to include the "driving" flag
```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
└── tasks.md # Phase 2 output (/speckit.tasks)
├── 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/
│ ├── models/
│ │ └── relationship.py # Add driving field to dataclass
│ ├── parser/
│ │ └── table_handlers/
│ │ └── taskpred.py # Parse driving_flag from XER
│ ├── db/
│ │ ├── schema.py # Add driving column to relationships table
│ │ ├── loader.py # Store driving flag when loading
│ │ └── queries.py # Return driving in relationship queries
│ └── tools/
│ ├── list_relationships.py # Response already uses query result
│ ├── get_predecessors.py # Response already uses query result
│ └── get_successors.py # Response already uses query result
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/
├── contract/
│ ├── test_list_relationships.py # Verify driving flag in response
│ ├── test_get_predecessors.py # Verify driving flag in response
│ └── test_get_successors.py # Verify driving flag in response
├── integration/
│ └── test_xer_parsing.py # Verify driving flag parsed from XER
└── unit/
├── test_table_handlers.py # Test TASKPRED handler parses driving
└── test_db_queries.py # Test queries return driving flag
├── __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 (existing). No new directories needed.
**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
> No constitution violations. Implementation is a focused enhancement to existing architecture.
> **Fill ONLY if Constitution Check has violations that must be justified**
| Item | Assessment |
|------|------------|
| Scope | Small - single field addition across 4 layers |
| Risk | Low - additive change, no behavior modification |
| Testing | Contract tests + unit tests for each layer |
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.