xer-mcp/specs/002-direct-db-access/plan.md

Implementation Plan: Direct Database Access for Scripts

Branch: 002-direct-db-access | Date: 2026-01-08 | Spec: spec.md Input: Feature specification from /specs/002-direct-db-access/spec.md

Summary

Extend the XER MCP Server to support persistent SQLite database files instead of only in-memory databases. The existing load_xer tool will gain an optional parameter to write to a file-based database, and the response will include the database path and schema information. A new get_database_info tool will allow retrieval of database connection details without reloading. This enables scripts to query schedule data directly via SQL, reducing LLM workload for large data processing.

Technical Context

Language/Version: Python 3.14 Primary Dependencies: mcp>=1.0.0 (MCP SDK), sqlite3 (stdlib) Storage: SQLite database file (persistent) in addition to existing in-memory option 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 (extending existing structure) Performance Goals: Database file creation <1 second; query response <100ms for 10,000+ activities Constraints: File must be accessible by external scripts; atomic writes to prevent corruption Scale/Scope: 2 MCP tools modified/added; extends existing database layer

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	Contract tests for modified load_xer and new get_database_info tool
II. Extensibility Architecture	Core parsing separate from MCP transport; pluggable handlers	✅ PASS	Extends existing DatabaseManager; no changes to parser or handlers
III. MCP Protocol Compliance	Complete JSON schemas; MCP error format; compliant transport	✅ PASS	New tool definitions include JSON schemas; error responses follow MCP format
IV. XER Format Fidelity	No data loss; preserve precision; handle all standard tables	✅ PASS	Same data written to file-based DB as in-memory; no parsing changes
V. Semantic Versioning	SemVer for releases; breaking changes documented	✅ PASS	Minor version bump (0.2.0); backward compatible - existing behavior unchanged
Technical Standards	Python 3.14; type hints; ruff formatting	✅ PASS	Follows existing codebase patterns

Gate Result: PASS - All constitution principles satisfied. Proceed to Phase 0.

Project Structure

Documentation (this feature)

specs/002-direct-db-access/
├── 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)

src/xer_mcp/
├── db/
│   ├── __init__.py          # Modify DatabaseManager for file-based DB support
│   ├── schema.py            # No changes needed
│   ├── loader.py            # No changes needed
│   └── queries.py           # Add schema introspection query
└── tools/
    ├── load_xer.py          # Modify to support db_path parameter and return schema
    └── get_database_info.py # NEW: Return database path and schema info

tests/
├── contract/
│   ├── test_load_xer.py     # Add tests for persistent database functionality
│   └── test_get_database_info.py  # NEW: Contract tests for schema retrieval
└── unit/
    └── test_db_manager.py   # NEW: Unit tests for file-based database operations

Structure Decision: Extends existing single project structure. Minimal changes to existing modules; adds one new tool file and modifies DatabaseManager to support both in-memory and file-based databases.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

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 for load_xer db_path parameter; contract tests for get_database_info tool
II. Extensibility Architecture	✅ PASS	DatabaseManager extended without breaking existing interface; new tool follows existing patterns
III. MCP Protocol Compliance	✅ PASS	Tool schemas defined in contracts/mcp-tools.json; error responses use existing MCP error format
IV. XER Format Fidelity	✅ PASS	No changes to parsing; same data fidelity in file-based DB as in-memory
V. Semantic Versioning	✅ PASS	Version 0.2.0; new feature, backward compatible
Technical Standards	✅ PASS	Type hints; ruff formatting; pytest async tests

Post-Design Gate Result: PASS - Design artifacts align with constitution. Ready for task generation.

Generated Artifacts

Artifact	Path	Description
Research	specs/002-direct-db-access/research.md	SQLite file vs in-memory, atomic writes, schema introspection
Data Model	specs/002-direct-db-access/data-model.md	DatabaseInfo entity, SchemaInfo structure
Contracts	specs/002-direct-db-access/contracts/mcp-tools.json	Updated load_xer schema, new get_database_info schema
Quickstart	specs/002-direct-db-access/quickstart.md	Usage examples for direct database access
Agent Context	CLAUDE.md	No updates needed (same technologies)

Next Steps

Run /speckit.tasks to generate implementation tasks from this plan.