Bill Ballou
0170eb7fef
Feature spec for MCP tools to query XER schedule data: - 4 user stories (load file, query activities, relationships, summary) - 14 functional requirements including pagination (100 item default) - Clarifications: P6 critical flags, multi-project selection, internal calendars
10 KiB
10 KiB
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:
- 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)
- 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
- 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
- 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
- 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
- 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:
- 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)
- 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)
- Given an XER file is loaded, When I request a specific activity by ID, Then I receive the complete details for that activity
- Given no XER file is loaded, When I request activities, Then I receive a clear error message indicating no file is loaded
- 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)
- 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:
- 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) and lag values
- 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 and lag values
- Given an activity has no predecessors, When I request its predecessors, Then I receive an empty list (not an error)
- Given an XER file is loaded, When I request all relationships, Then I receive the dependency network (limited to 100 by default) with pagination metadata
- Given an XER file is loaded, When I request relationships with offset and limit parameters, Then I receive the specified page of results
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:
- Given an XER file is loaded, When I request the project summary, Then I receive project name, start date, finish date, and total activity count
- Given an XER file with milestones, When I request milestones, Then I receive a list of milestone activities with their target dates
- 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
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
- FR-006: System MUST expose an MCP tool to retrieve project summary information (name, dates, activity count)
- FR-007: System MUST expose an MCP tool to list milestone activities
- 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
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), 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)
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)