docs: add specification and implementation plan for direct database access feature
This feature (002-direct-db-access) enables scripts to query schedule data directly via SQL after loading XER files through MCP. Key additions: - spec.md: Feature specification with 3 user stories - plan.md: Implementation plan with constitution check - research.md: Technology decisions (SQLite file, WAL mode, atomic writes) - data-model.md: DatabaseInfo, SchemaInfo, TableInfo entities - contracts/mcp-tools.json: Extended load_xer schema, new get_database_info tool - quickstart.md: Usage examples for direct database access - tasks.md: 16 implementation tasks across 6 phases
This commit is contained in:
108
specs/002-direct-db-access/plan.md
Normal file
108
specs/002-direct-db-access/plan.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Implementation Plan: Direct Database Access for Scripts
|
||||
|
||||
**Branch**: `002-direct-db-access` | **Date**: 2026-01-08 | **Spec**: [spec.md](./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)
|
||||
|
||||
```text
|
||||
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)
|
||||
|
||||
```text
|
||||
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.
|
||||
Reference in New Issue
Block a user