The PRD requires that the system integrates with existing Git workflows, that files remain human-readable, and that there are no database dependencies. We need a simple, robust way to store the documentation content that honors these constraints.

The file system will be treated as the single source of truth. The server will not have its own persistent state. All content and structure information is derived directly from the .adoc and .md files within the project directory.

The quality goal PERF-1 requires API calls to respond in under 2 seconds. Reading and parsing text files from disk on every request would be too slow for large projects, as identified in the runtime analysis.

On startup, the server will perform a one-time scan of the entire project directory. It will parse all documentation files and build an "In-Memory Structure Index". This index will hold metadata about each document, including section names, hierarchical paths, and the start/end line numbers for each section in its source file. Read requests will consult this index to find the exact byte range to read from a file.

A programming language and web framework are needed to build the MCP API Server. The choice must align with the need for rapid development, strong text-processing capabilities, and high performance for an I/O-bound application.

The backend will be implemented in Python. The FastAPI framework will be used to build the web server and API endpoints.

The quality goal REL-1 (Atomic Writes) is critical to prevent file corruption during update operations. A failure (e.g., disk full, application crash) during a file write could leave a document in an unrecoverable, partially-written state.

The File System Handler component will implement atomic writes using a backup-and-replace strategy: 1. Create a backup of the original file (e.g., doc.adoc → doc.adoc.bak). 2. Write all intended changes to a new temporary file (e.g., doc.adoc.tmp). 3. If the write is successful, atomically rename/move the temporary file to replace the original file. 4. Delete the backup file. 5. If any step fails, restore the original file from the backup and delete the temporary file.

A core feature is the ability to map a hierarchical path (e.g., chapter-1.section-2) to a precise location in a source file. This is complicated by AsciiDoc’s include::[] directive, as content from multiple files is logically part of one document. Existing parsers often flatten the document, losing this critical source-map information.

A custom document parser will be developed. This parser will be responsible for: 1. Parsing the AsciiDoc/Markdown syntax. 2. Recognizing and recursively resolving include::[] directives. 3. Building an Abstract Syntax Tree (AST) that retains the original file path and line numbers for every single element of the document.

The initial implementation of mcp_server.py grew to 916 lines, violating the project’s CLAUDE.md best practice of keeping files under 500 lines. The file contained three distinct responsibilities:

This monolithic structure made the codebase difficult to navigate, test, and maintain. Each component had different testing requirements and change frequencies.

Split mcp_server.py into four focused modules using the Extract-and-Delegate pattern:

The main server class receives instances of all modules and delegates calls to them, maintaining a clean separation of concerns.

Dependency Injection Pattern:

Each module receives the server instance, allowing access to shared state (sections, parser, editor) without circular dependencies.

The web_server.py file contained a large embedded HTML template string (~300 lines) for the web interface. This resulted in:

Extract the HTML template to a separate file: src/templates/web_interface.html

The template is loaded at runtime using Python’s standard library:

The project initially lacked a comprehensive test infrastructure. As the codebase grew to ~750 lines across multiple modules, the risk of regressions increased significantly. A robust testing framework was needed to:

Adopt pytest as the testing framework with the following tools:

Core Framework: - pytest: Modern Python testing framework with fixture support - pytest-cov: Code coverage measurement and reporting - pytest-html: HTML test report generation

Testing Approach: - Unit tests for individual modules (test_document_parser.py, test_document_api.py, etc.) - Integration tests for component interaction - Fixture-based test setup for reusable test environments - Coverage target: >80% for core modules

Directory Structure:

After implementing comprehensive test suites:

Test Statistics: - 123 tests total - 121 passing (98.4% success rate) - ~1,400 lines of test code

The project initially implemented the MCP (Model Context Protocol) manually using custom JSON-RPC 2.0 message handling in src/mcp/protocol_handler.py. This 282-line module contained:

This approach created several problems:

The project’s architecture principle states: "Nutze für MCP-Server immer fastMCP" (Always use fastMCP for MCP servers), recognizing that mature libraries reduce risk compared to custom implementations.

Migrate to the official MCP SDK (mcp[cli]>=1.0.0) which includes FastMCP 1.0 as from mcp.server.fastmcp import FastMCP.

Implementation approach: - Replace manual stdin/stdout JSON-RPC loop with mcp.run() - Convert 10 tool handlers to @mcp.tool() decorators - Delete src/mcp/protocol_handler.py entirely (282 lines) - Use type hints for automatic schema generation - Keep DocumentAPI business logic unchanged (out of scope)

Pro: * Protocol Compliance Guaranteed: Official SDK maintained by Anthropic ensures MCP specification adherence * Automatic Schema Generation: Type hints (e.g., def get_section(path: str) → dict) auto-generate JSON schemas * Less Boilerplate: Reduced from 282 lines (protocol_handler.py) + manual schemas to ~80 lines of decorator-based tools * Better Maintainability: Protocol updates handled by SDK dependency updates, not manual code changes * Improved Developer Experience: Decorator syntax (@mcp.tool()) more Pythonic than manual routing

Con: * External Dependency: Added mcp>=1.0.0 dependency (16 transitive dependencies) * SDK Learning Curve: Team must learn FastMCP patterns (mitigated by similarity to FastAPI) * Less Control: Some edge cases may require SDK updates rather than immediate fixes

Neutral: * Testing Changes: Removed 2 test files (test_protocol_handler.py, test_webserver_startup.py) testing deleted code * Coverage Impact: 70% coverage (down from 82%) due to tool wrapper functions not directly testable via unit tests

Code Reduction: - Deleted: 282 lines (protocol_handler.py) + 445 lines (tests) = 727 lines - Added: 89 lines (tool decorators in mcp_server.py) - Net reduction: -638 lines (88% reduction in MCP-related code)

Migration: - 10 MCP tools successfully migrated: * Read tools: get_section, get_metadata, get_sections, get_dependencies, validate_structure, refresh_index, get_structure, search_content * Write tools: update_section, insert_section - Webserver start hook moved from initialize handler to MCPDocumentationServer.init() - All delegation methods retained for backward compatibility

Testing: - 81 core tests passing (document_parser: 100%, document_api: 86%, mcp_server: 67%) - No regressions in business logic (DocumentAPI unchanged)

Commits: - b8a644e: feat: Migrate from manual MCP protocol to FastMCP SDK - 515e6f1: test: Remove obsolete protocol_handler tests and update imports

1. Status Quo (Keep Manual Implementation) - Rejected: Technical debt would compound as MCP evolves - Risk: Protocol drift, maintenance burden increases over time

2. FastMCP 2.0 (Separate Framework) - Description: pip install fastmcp - enterprise features (auth, deployment, OpenAPI) - Rejected: Too complex for project needs, unnecessary features - Comparison: Official SDK provides sufficient functionality without enterprise overhead

3. Other MCP SDKs (Node.js, Go) - Rejected: Would require rewriting entire Python codebase - Not evaluated: Python ecosystem alignment more important than alternative language features

The project needed to decide whether to adopt Behavior-Driven Development (BDD) testing practices for the existing pytest-based test suite (19 files, 4,287 lines of test code). The evaluation included:

Key constraint identified during collaborative decision process: Requirement for inline BDD approach where Gherkin syntax and test implementation exist in the same file, avoiding separate .feature files.

Adopt Pure Docstring BDD approach for new tests and gradual conversion of existing tests. This approach combines:

Example Implementation:

Pro: * Stakeholder-readable: Business context clear in test docstrings * Zero Dependencies: Works with existing pytest infrastructure * Single File Approach: Meets user requirement for inline BDD * Gradual Adoption: Can convert tests incrementally during refactoring * Better Documentation: Tests become self-documenting specifications * Improved Onboarding: New contributors understand business context faster

Con: * Longer Files: More verbose docstrings increase file length * Discipline Required: Team must maintain consistent BDD formatting * Learning Curve: Developers need to understand Gherkin syntax

Neutral: * Same Number of Files: No additional .feature files to maintain * Pytest Compatibility: All existing tooling (coverage, markers, fixtures) continues to work

Gradual Adoption: 1. New Tests: Write in Pure Docstring BDD format immediately 2. Refactoring Priority: Convert existing tests when making changes 3. Focus Areas: Integration tests benefit most from business context 4. Style Guide: Create consistent formatting standards

Quality Measures: - BDD docstring style guide for consistency - Examples and templates for common test patterns - Integration with existing pytest markers (unit, integration, web, parser)

1. Traditional BDD with pytest-bdd - Description: Separate .feature files with step definitions - Rejected: User requirement for single-file approach not met - Concerns: 2.5x more code, maintenance overhead, separate file synchronization

2. Behave Framework - Description: Standalone BDD runner with pure Gherkin philosophy - Rejected: Would abandon existing pytest infrastructure - Concerns: Complete test suite migration required, learning curve

3. Status Quo (No BDD) - Description: Continue with current pytest/unittest approach - Rejected: User preference for BDD approach with business context - Concerns: Tests remain technically focused, lacking stakeholder readability

4. Comments-Only BDD - Description: Add Given/When/Then comments without docstring context - Rejected: Lacks feature/scenario business context in docstrings - Missing: User story mapping and acceptance criteria clarity