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

Feature Specification: Project Schedule Tools

Feature Branch: 001-schedule-tools Created: 2026-01-06 Status: Draft Input: User description: "MCP tools to query activities, relationships, and schedules from XER data"

User Scenarios & Testing (mandatory)

User Story 1 - Load XER File (Priority: P1)

As an AI assistant user, I want to load an XER file into the MCP server so that I can query its schedule data.

Why this priority: This is a prerequisite for all other functionality - no queries are possible without first loading data.

Independent Test: Can be tested by providing a file path and verifying the file is successfully parsed and available for queries.

Acceptance Scenarios:

1. Given a valid XER file path with a single project, When I request to load the file, Then the file is parsed, the project is auto-selected, and a success confirmation is returned with basic file info (project name, activity count)
2. Given a valid XER file path with multiple projects, When I request to load the file without specifying a project, Then I receive a list of available projects and a prompt to select one
3. Given a valid XER file path with multiple projects, When I request to load the file with a specific project ID, Then that project is selected and loaded
4. Given an invalid file path, When I request to load the file, Then I receive a clear error message indicating the file was not found
5. Given a corrupted or invalid XER file, When I request to load the file, Then I receive a clear error message describing the parsing failure
6. Given a file is already loaded, When I load a new file, Then the previous data is replaced with the new file's data

---

User Story 2 - Query Project Activities (Priority: P1)

As an AI assistant user, I want to query activities from a loaded XER file so that I can understand what work is planned in the project schedule.

Why this priority: Activities are the fundamental building blocks of any P6 schedule. Without the ability to query activities, no other schedule analysis is possible.

Independent Test: Can be fully tested by loading an XER file and querying for activities. Delivers immediate value by exposing schedule data to AI assistants.

Acceptance Scenarios:

1. Given an XER file is loaded, When I request all activities, Then I receive a list of activities with their names, IDs, and dates (limited to 100 by default)
2. Given an XER file is loaded, When I request activities filtered by date range, Then I receive only activities that fall within that range (limited to 100 by default)
3. Given an XER file is loaded, When I request a specific activity by ID, Then I receive the complete details for that activity
4. Given no XER file is loaded, When I request activities, Then I receive a clear error message indicating no file is loaded
5. Given an XER file with more than 100 activities, When I request activities without specifying a limit, Then I receive the first 100 activities plus pagination metadata (total count, has_more flag)
6. Given an XER file is loaded, When I request activities with offset and limit parameters, Then I receive the specified page of results

---

User Story 3 - Query Activity Relationships (Priority: P2)

As an AI assistant user, I want to query the relationships (dependencies) between activities so that I can understand the logical sequence of work and identify critical paths.

Why this priority: Relationships define the logical flow of work and are essential for schedule analysis, but require activities to be queryable first.

Independent Test: Can be tested by loading an XER file and querying predecessor/successor relationships for any activity.

Acceptance Scenarios:

1. Given an XER file is loaded, When I request predecessors for an activity, Then I receive a list of predecessor activities with their relationship types (FS, SS, FF, SF), lag values, and driving flag
2. Given an XER file is loaded, When I request successors for an activity, Then I receive a list of successor activities with their relationship types, lag values, and driving flag
3. Given an activity has no predecessors, When I request its predecessors, Then I receive an empty list (not an error)
4. Given an XER file is loaded, When I request all relationships, Then I receive the dependency network with relationship types, lag values, and driving flags (limited to 100 by default) with pagination metadata
5. Given an XER file is loaded, When I request relationships with offset and limit parameters, Then I receive the specified page of results
6. Given no XER file is loaded, When I request relationships or predecessors/successors, Then I receive a clear error message indicating no file is loaded

---

User Story 4 - Query Project Summary (Priority: P3)

As an AI assistant user, I want to get a high-level summary of the project schedule so that I can quickly understand project scope, timeline, and key milestones.

Why this priority: Provides valuable context for AI analysis but depends on activity and relationship data being accessible first.

Independent Test: Can be tested by loading an XER file and requesting project summary information.

Acceptance Scenarios:

1. Given an XER file is loaded, When I request the project summary, Then I receive project name, data date, start date, finish date, and total activity count
2. Given an XER file with milestones, When I request milestones, Then I receive a list of all milestone activities (both Start Milestones and Finish Milestones) with their target dates and milestone type
3. Given an XER file is loaded, When I request the critical path, Then I receive the sequence of activities that determine the project end date
4. Given no XER file is loaded, When I request project summary, milestones, or critical path, Then I receive a clear error message indicating no file is loaded

---

Edge Cases

• What happens when an XER file contains no activities? Return empty results with a clear indication that the file has no schedule data.
• What happens when activity IDs are duplicated in the XER file? Use the last occurrence and log a warning.
• What happens when relationship references point to non-existent activities? Skip invalid relationships and include them in a warnings list.
• What happens when date fields are missing or malformed? Use null values for missing dates and report parsing warnings.
• What happens when the XER file uses an unsupported version format? Attempt best-effort parsing and report version compatibility warnings.

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST parse standard Primavera P6 XER file format and extract schedule data
• FR-002: System MUST expose an MCP tool to load an XER file from a specified file path
• FR-003: System MUST expose an MCP tool to list all activities with filtering options (by date range, by WBS, by activity type)
• FR-004: System MUST expose an MCP tool to retrieve detailed information for a specific activity by ID
• FR-005: System MUST expose an MCP tool to query predecessor and successor relationships for any activity, including relationship type, lag value, and driving flag
• FR-006: System MUST expose an MCP tool to retrieve project summary information (name, data date, plan dates, activity count)
• FR-007: System MUST expose an MCP tool to list milestone activities, including both Start Milestones (TT_Mile with task_type='TT_Mile' and milestone_type='start') and Finish Milestones (task_type='TT_Mile' and milestone_type='finish')
• FR-008: System MUST expose an MCP tool to identify the critical path
• FR-009: System MUST return structured data that AI assistants can process and present to users
• FR-010: System MUST provide clear, actionable error messages when operations fail
• FR-011: System MUST preserve all date/time precision from the original XER file
• FR-012: System MUST handle XER files with multiple projects by requiring explicit project selection; single-project files auto-select the only project
• FR-013: System MUST implement pagination for list queries with a default limit of 100 items, supporting offset and limit parameters
• FR-014: System MUST return pagination metadata (total_count, has_more, offset, limit) with all paginated responses
• FR-015: System MUST return an informative error (NO_FILE_LOADED) when any query tool is invoked before an XER file has been successfully loaded

Key Entities

• Project: The top-level container representing a P6 project with name, ID, start/finish dates, and calendar assignments
• Activity: A unit of work with ID, name, type (task/milestone/LOE), milestone_type (start/finish for milestones, null otherwise), planned dates, actual dates, duration, and status
• Relationship: A dependency link between two activities with type (FS/SS/FF/SF), lag value, and driving flag
• WBS (Work Breakdown Structure): Hierarchical organization of activities with ID, name, parent reference, and level
• Calendar: Work schedule definition that determines working days and hours for activities (internal use only; not exposed as queryable entity)
• Resource: Labor, equipment, or material assigned to activities (exposed for future resource analysis features)

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can load and query an XER file within 5 seconds for files up to 10,000 activities
• SC-002: Users can retrieve activity details in under 1 second after file is loaded
• SC-003: All standard XER table types used in schedule analysis are correctly parsed (TASK, TASKPRED, PROJECT, PROJWBS, CALENDAR)
• SC-004: 100% of valid relationship types (FS, SS, FF, SF) are correctly identified and queryable
• SC-005: Users receive actionable error messages that identify the specific issue when operations fail
• SC-006: Critical path identification uses P6's stored critical flags, ensuring exact match with P6's own critical path
• SC-007: AI assistants can successfully integrate with the MCP server and execute all exposed tools

Clarifications

Session 2026-01-06

• Q: What should be the default result limit for activity/relationship queries? → A: 100 items default limit per query
• Q: How should critical path be determined? → A: Use P6's stored critical flags from XER data
• Q: How should multi-project XER files be handled? → A: Require explicit project selection if multiple exist
• Q: Should calendar data be exposed as queryable? → A: Internal use only (not exposed as queryable)
• Q: What happens when any query tool is called without a file loaded? → A: Return informative error indicating no XER file is loaded; applies to all tools except load_xer
• Q: Should project summary include the data date? → A: Yes, include the data date (schedule "as-of" date) in project summary response
• Q: Should relationship queries return the driving flag? → A: Yes, include the driving property in all relationship responses (predecessors, successors, list relationships)
• Q: Which milestone types should be included in milestone queries? → A: Include both Start Milestones and Finish Milestones

Assumptions

• XER files follow the standard Primavera P6 export format (tab-delimited with %T headers)
• The MCP server runs locally and has file system access to read XER files
• Users have valid XER files exported from P6 (versions 6.0 through current)
• Single-user operation - no concurrent access handling required for MVP
• Memory is sufficient to hold parsed schedule data for typical project sizes (up to 50,000 activities)