# ARCHITECTURE.md
**Date:** 2025-10-08
**Version:** 1.0.0
## System Overview
docs-mcp is a Model Context Protocol (MCP) server designed to provide AI assistants with structured access to documentation templates and prompt engineering frameworks. The system follows a simple, file-based architecture that prioritizes reliability, maintainability, and ease of integration.
**Project Overview Reference:** docs-mcp provides AI assistants with structured documentation generation capabilities through POWER framework templates (README, Architecture, API, Components, Schema) and prompt engineering framework documentation (POWER, COSTAR, Five S, CRISPE).
## System Topology
```
┌─────────────────────────────────────────────────────────────────┐
│ MCP Client Layer │
│ (Claude Desktop, Claude Code CLI, or other MCP-compatible AI) │
└────────────────────────┬────────────────────────────────────────┘
│ stdio transport
│ JSON-RPC messages
▼
┌─────────────────────────────────────────────────────────────────┐
│ docs-mcp Server (server.py) │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ MCP Server Framework │ │
│ │ - Tool registration (@app.list_tools) │ │
│ │ - Tool execution (@app.call_tool) │ │
│ │ - Async I/O handling (asyncio) │ │
│ └───────────────────┬───────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────▼───────────────────────────────────────┐ │
│ │ Business Logic Layer │ │
│ │ - list_templates: Scan and list template files │ │
│ │ - get_template: Read and return template content │ │
│ │ - list_frameworks: Scan and list framework docs │ │
│ └───────────────────┬───────────────────────────────────────┘ │
│ │ │
└──────────────────────┼───────────────────────────────────────────┘
│ file system access
▼
┌─────────────────────────────────────────────────────────────────┐
│ File System Storage │
│ ┌──────────────────────┐ ┌──────────────────────────────┐ │
│ │ templates/power/ │ │ frameworks/ │ │
│ │ ├── readme.txt │ │ ├── POWER.md │ │
│ │ ├── architecture.txt│ │ ├── COSTAR.md │ │
│ │ ├── api.txt │ │ ├── FiveS.md │ │
│ │ ├── components.txt │ │ └── CRISPE.md │ │
│ │ └── schema.txt │ │ │ │
│ └──────────────────────┘ └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## Module Boundaries
### 1. Server Core (server.py)
**Responsibility:** MCP protocol implementation, tool registration, and coordination
**Key Components:**
- `Server("docs-mcp")`: MCP server instance (line 21)
- `list_tools()`: Tool discovery endpoint (lines 24-61)
- `call_tool()`: Tool execution dispatcher (lines 64-128)
- `main()`: stdio transport initialization (lines 131-138)
**Dependencies:**
- `mcp.server`: MCP SDK core
- `mcp.types`: Type definitions (Tool, TextContent)
- `mcp.server.stdio`: stdio transport layer
- `asyncio`: Async runtime
- `pathlib`: File system path handling
**Boundaries:**
- Input: JSON-RPC messages via stdio
- Output: Structured TextContent responses
- Does NOT: Modify files, execute code, or make network calls
### 2. Template Storage (templates/power/)
**Responsibility:** Store POWER framework documentation templates
**Structure:**
```
templates/power/
├── readme.txt # README generation template
├── architecture.txt # Architecture documentation template
├── api.txt # API documentation template
├── components.txt # Component documentation template
└── schema.txt # Schema documentation template
```
**Format:** Plain text files with POWER framework structure:
- `framework`: POWER
- `purpose`: Document objective
- `output`: Required format
- `work`: Process steps
- `examples`: Usage samples
- `requirements`: Mandatory elements
- `save_as`: Default filename
- `store_as`: Reference name
**Boundaries:**
- Read-only access
- UTF-8 encoded text files
- No dynamic generation or modification
### 3. Framework Documentation (frameworks/)
**Responsibility:** Store prompt engineering framework reference docs
**Structure:**
```
frameworks/
├── POWER.md # POWER framework documentation
├── COSTAR.md # COSTAR framework documentation
├── FiveS.md # Five S framework documentation
└── CRISPE.md # CRISPE framework documentation
```
**Format:** Markdown documentation files
**Boundaries:**
- Read-only access
- Reference documentation only
- No execution or interpretation
## Technology Stack
### Core Technologies
| Component | Technology | Version | Rationale |
|-----------|-----------|---------|-----------|
| Runtime | Python | 3.10+ | MCP SDK requirement, async/await support, type hints |
| Protocol | MCP SDK | Latest | Official Anthropic protocol for AI tool integration |
| Transport | stdio | Built-in | Standard MCP transport, simple and reliable |
| Async | asyncio | stdlib | Native Python async support, no external deps |
| File I/O | pathlib | stdlib | Modern, cross-platform path handling |
### Design Decisions
**1. File-based storage over database**
- **Rationale:** Templates are static, version-controlled content
- **Benefits:** Simple, no DB overhead, easy to edit and review
- **Trade-offs:** Not suitable for dynamic or user-generated content
**2. stdio transport over HTTP**
- **Rationale:** MCP standard for local AI assistant integration
- **Benefits:** No network config, secure local-only access
- **Trade-offs:** Not suitable for remote or multi-user scenarios
**3. Synchronous file I/O in async handlers**
- **Rationale:** Template files are small (<10KB), read infrequently
- **Benefits:** Simpler code, adequate performance
- **Trade-offs:** Could block event loop if files were large
**4. Plain text templates over structured formats**
- **Rationale:** Human-readable, easy to edit, version control friendly
- **Benefits:** No parsing overhead, flexible format
- **Trade-offs:** No schema validation
## Data Flow
### Tool Execution Flow
```
1. Client Request
├─ MCP Client sends JSON-RPC request
└─ stdio transport receives message
2. Server Processing
├─ MCP SDK deserializes request
├─ Routes to @app.call_tool handler
└─ Identifies tool: list_templates | get_template | list_frameworks
3. Business Logic
├─ list_templates:
│ ├─ Resolve TEMPLATES_DIR path (line 17)
│ ├─ Glob for *.txt files (line 72)
│ ├─ Extract .stem (filename without extension)
│ └─ Format as numbered list (lines 76-79)
│
├─ get_template:
│ ├─ Validate template_name in enum (line 46)
│ ├─ Construct path: TEMPLATES_DIR / f"{template_name}.txt" (line 89)
│ ├─ Check file existence (line 92)
│ ├─ Read file content (UTF-8) (lines 98-99)
│ └─ Format with header (line 101)
│
└─ list_frameworks:
├─ Resolve FRAMEWORKS_DIR path (line 18)
├─ Glob for *.md files (line 110)
├─ Get file sizes via stat() (line 117)
└─ Format as numbered list with sizes (line 118)
4. Response Generation
├─ Wrap result in TextContent object
├─ MCP SDK serializes to JSON-RPC response
└─ stdio transport sends to client
5. Error Handling (if applicable)
├─ Catch exceptions at tool level (lines 84, 103, 124)
├─ Return TextContent with error message
└─ Never crash server on tool errors
```
### File Access Pattern
```
Server Initialization:
├─ SERVER_DIR = Path(__file__).parent (line 16)
├─ TEMPLATES_DIR = SERVER_DIR / "templates" / "power" (line 17)
└─ FRAMEWORKS_DIR = SERVER_DIR / "frameworks" (line 18)
Runtime Access:
├─ Read-only file system access
├─ No caching (files read on demand)
├─ UTF-8 encoding assumed (line 98)
└─ Graceful error handling for missing files
```
## Concurrency Model
**Async Event Loop:**
- Single-threaded asyncio event loop
- stdio_server() handles transport I/O asynchronously (line 133)
- Tool handlers are async functions but perform synchronous I/O
- No concurrent requests to same tool (MCP model)
**Thread Safety:**
- Not required (single-threaded)
- File reads are atomic at OS level
- No shared mutable state
## Security Considerations
**File System Access:**
- Server only reads from predefined directories (lines 17-18)
- No path traversal (uses pathlib, validates template names via enum)
- No write operations
- No command execution
**Input Validation:**
- Template names restricted to enum: ["readme", "architecture", "api", "components", "schema"] (line 46)
- Invalid names return error, don't crash server (lines 92-96)
- No user-provided file paths
**Transport Security:**
- stdio transport is local-only
- No network exposure
- Inherits parent process permissions
## Design Rationale
### Why POWER Framework?
**Problem:** AI assistants need structured guidance to generate consistent, comprehensive documentation.
**Solution:** POWER framework provides clear, actionable template structure:
- **Purpose:** Focuses intent
- **Output:** Defines deliverable format
- **Work:** Specifies analysis process
- **Examples:** Provides concrete patterns
- **Requirements:** Ensures completeness
**Benefits:**
1. **Consistency:** All documentation follows same structure
2. **Completeness:** Requirements section ensures nothing is missed
3. **AI-friendly:** Clear instructions, examples, and format specifications
4. **Human-readable:** Easy to review and modify templates
5. **Extensible:** New templates follow same pattern
### Why MCP Protocol?
**Problem:** AI assistants need standardized way to access external tools and data.
**Solution:** Model Context Protocol (MCP) provides:
- Standard JSON-RPC interface
- Tool discovery and schema validation
- Type-safe communication
- Multiple transport options
**Benefits:**
1. **Interoperability:** Works with any MCP-compatible client
2. **Type safety:** Input/output schemas prevent errors
3. **Discoverability:** Clients can enumerate available tools
4. **Maintainability:** Standard protocol, well-documented
### File-based Architecture
**Alternative considered:** Database storage (SQLite, PostgreSQL)
**Decision:** File-based storage
**Rationale:**
1. **Version control:** Templates tracked in git
2. **Simplicity:** No DB setup, migrations, or backups
3. **Performance:** Adequate for small, static content
4. **Transparency:** Anyone can inspect/edit templates
5. **Deployment:** No DB dependencies or configuration
## Extension Points
### Adding New Templates
1. Create template file: `templates/power/{name}.txt`
2. Update enum in `server.py:46`:
```python
"enum": ["readme", "architecture", "api", "components", "schema", "newname"]
```
3. Restart server
4. Template automatically available via `get_template(template_name="newname")`
### Adding New Frameworks
1. Create markdown file: `frameworks/{FRAMEWORK_NAME}.md`
2. No code changes required
3. Restart server
4. Framework automatically listed via `list_frameworks()`
### Adding New Tools
1. Add Tool definition to `list_tools()` return list (lines 27-60)
2. Add handler branch to `call_tool()` function (lines 68-126)
3. Implement business logic
4. Return `TextContent` with results or errors
---
**AI Integration Notes**
This architecture is optimized for AI assistant consumption. Key design patterns:
- **Stateless operations:** Each tool call is independent
- **Structured output:** Consistent TextContent format
- **Error recovery:** Errors return messages, never crash
- **Self-documenting:** Tool schemas describe inputs/outputs
- **Read-only:** No side effects, safe for speculative execution
For AI assistants: Use the architecture understanding to:
1. Predict tool behavior without execution
2. Compose multi-step workflows
3. Handle errors gracefully
4. Suggest improvements or extensions
**🤖 This ARCHITECTURE document was generated using the docs-mcp architecture template**
---
**Maintained by:** willh
**Last updated:** 2025-10-08
**Related documents:** README.md, API.md (future), COMPONENTS.md (future)
