# 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) and lag values
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 and lag values
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 (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, 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 milestone activities with their target dates
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
- **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
- **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), 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

## 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)