# SCHEMA.md
**Date:** 2025-10-08
**Schema Version:** 1.0.0
## Overview
This document defines all data schemas, formats, and validation rules for the docs-mcp server. It provides comprehensive documentation of template file structures, MCP tool interfaces, response formats, file naming conventions, directory organization, and validation constraints.
**Project Context:**
- **README Summary:** docs-mcp provides AI assistants with structured documentation generation through POWER framework templates and prompt engineering frameworks
- **Architecture Summary:** File-based MCP server using stdio transport with async I/O and read-only template access
- **API Summary:** Three MCP tools (list_templates, get_template, list_frameworks) provide template discovery and retrieval
- **Components Summary:** Stateless MCP tools with file system discovery, graceful error handling, and read-only access patterns
---
## Template File Format Schema
### POWER Framework Template Structure
All documentation templates follow the POWER (Purpose, Output, Work, Examples, Requirements) framework structure.
**File Format:** Plain text (`.txt`)
**Encoding:** UTF-8
**Location:** `templates/power/`
**Schema Definition:**
```yaml
template_file:
framework: string # Must be "POWER"
purpose: string # Document objective and intent
output: string # Required format, headers, footers
work: string # Analysis steps and process
examples: string # Concrete usage samples
requirements: string # Mandatory elements checklist
save_as: string # Default output filename (e.g., "README.md")
store_as: string # Storage reference name (e.g., "readme_summary")
```
**Example Template Structure:**
```
framework: POWER
purpose: Generate README.md as the discovery entry document.
output: Must follow required header/footer with [Date] and [Version]. Document overview, installation, usage, and troubleshooting.
work: Scan project structure, analyze main entry points, document features and configuration.
examples:
- README with installation steps
- README with API usage examples
- README with troubleshooting section
requirements: Must include overview, prerequisites, installation, usage examples, and AI integration footer.
save_as: README.md
store_as: readme_summary
```
**Field Specifications:**
| Field | Type | Required | Format | Constraints |
|-------|------|----------|--------|-------------|
| framework | string | Yes | Fixed value | Must be "POWER" |
| purpose | string | Yes | Free text | Single sentence, ends with period |
| output | string | Yes | Multi-line | Must specify header/footer requirements |
| work | string | Yes | Free text | Describes analysis steps |
| examples | string | Yes | Bulleted list | At least 1 example, use "-" prefix |
| requirements | string | Yes | Free text | Must list mandatory elements |
| save_as | string | Yes | Filename | Valid filename with extension |
| store_as | string | Yes | Identifier | Snake_case, alphanumeric + underscore |
**Validation Rules:**
1. File must be valid UTF-8 text
2. All required fields must be present
3. Fields must appear in order: framework, purpose, output, work, examples, requirements, save_as, store_as
4. No field may be empty
5. File size must be < 50KB
---
## MCP Tool Input/Output Schemas
### JSON Schema Definitions
All MCP tools follow standardized JSON Schema for input validation and output formatting.
#### 1. list_templates Tool
**Input Schema:**
```json
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
```
**Input Parameters:** None
**Output Schema:**
```json
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["text"]
},
"text": {
"type": "string",
"pattern": "^Available POWER Framework Templates:\\n\\n(\\d+\\. \\w+\\n)+\\nTotal: \\d+ templates$"
}
},
"required": ["type", "text"]
},
"minItems": 1,
"maxItems": 1
}
```
**Output Format:**
```
Available POWER Framework Templates:
1. api
2. architecture
3. components
4. readme
5. schema
Total: 5 templates
```
**Output Constraints:**
- Always returns exactly 1 TextContent object in array
- Template names are sorted alphabetically
- Template names are lowercase
- Total count matches number of listed templates
---
#### 2. get_template Tool
**Input Schema:**
```json
{
"type": "object",
"properties": {
"template_name": {
"type": "string",
"description": "Name of template: readme, architecture, api, components, or schema",
"enum": ["readme", "architecture", "api", "components", "schema"]
}
},
"required": ["template_name"],
"additionalProperties": false
}
```
**Input Parameters:**
| Parameter | Type | Required | Valid Values | Description |
|-----------|------|----------|--------------|-------------|
| template_name | string | Yes | readme, architecture, api, components, schema | Template identifier |
**Input Validation:**
- `template_name` must be one of the enum values
- `template_name` is case-sensitive (lowercase only)
- Additional properties are not allowed
**Output Schema (Success):**
```json
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["text"]
},
"text": {
"type": "string",
"pattern": "^=== [A-Z]+ Template ===\\n\\nframework: POWER\\n"
}
},
"required": ["type", "text"]
},
"minItems": 1,
"maxItems": 1
}
```
**Output Schema (Error):**
```json
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["text"]
},
"text": {
"type": "string",
"pattern": "^(Template '[^']+' not found|Error reading template:)"
}
},
"required": ["type", "text"]
},
"minItems": 1,
"maxItems": 1
}
```
**Output Format (Success):**
```
=== README Template ===
framework: POWER
purpose: Generate README.md as the discovery entry document.
output: Must follow required header/footer with [Date] and [Version]...
[Full template content]
```
**Output Format (Error):**
```
Template 'invalid' not found. Available: readme, architecture, api, components, schema
```
**Output Constraints:**
- Always returns exactly 1 TextContent object in array
- Header format: `=== {UPPERCASE_NAME} Template ===\n\n`
- Template content follows POWER framework structure
- Error messages provide available template names
---
#### 3. list_frameworks Tool
**Input Schema:**
```json
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
```
**Input Parameters:** None
**Output Schema:**
```json
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["text"]
},
"text": {
"type": "string",
"pattern": "^Available Framework Documentation:\\n\\n(\\d+\\. [^\\n]+ \\([\\d,]+ bytes\\)\\n)+\\nTotal: \\d+ framework docs$"
}
},
"required": ["type", "text"]
},
"minItems": 1,
"maxItems": 1
}
```
**Output Format:**
```
Available Framework Documentation:
1. COSTAR.md (2,156 bytes)
2. CRISPE.md (1,842 bytes)
3. FiveS.md (1,734 bytes)
4. POWER.md (2,401 bytes)
Total: 4 framework docs
```
**Output Constraints:**
- Always returns exactly 1 TextContent object in array
- Framework files are sorted alphabetically
- File sizes displayed with comma separators (e.g., "2,156")
- Total count matches number of listed frameworks
---
## TextContent Response Format
### MCP TextContent Object Schema
All tool responses use the MCP `TextContent` type for consistent output formatting.
**Type Definition:**
```python
from mcp.types import TextContent
TextContent(
type: str, # Always "text"
text: str # Response content
)
```
**JSON Representation:**
```json
{
"type": "text",
"text": "Response content here"
}
```
**Schema:**
```json
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "text",
"description": "Content type identifier"
},
"text": {
"type": "string",
"description": "Response payload",
"minLength": 1
}
},
"required": ["type", "text"],
"additionalProperties": false
}
```
**Validation Rules:**
1. `type` field must always be "text"
2. `text` field must not be empty
3. `text` field must be valid UTF-8 string
4. No additional fields allowed
5. Both fields are required
**Response Array Format:**
```python
# All tools return list[TextContent]
return [TextContent(type="text", text="content")]
```
**Error Response Format:**
```python
# Errors also use TextContent
return [TextContent(type="text", text="Error: description")]
```
---
## File Naming Conventions
### Template Files
**Location:** `templates/power/`
**Pattern:** `{template_name}.txt`
**Naming Rules:**
1. Lowercase alphanumeric characters only
2. No spaces or special characters
3. Extension must be `.txt`
4. Name must match enum value in get_template tool
**Valid Template Names:**
- `readme.txt`
- `architecture.txt`
- `api.txt`
- `components.txt`
- `schema.txt`
**Invalid Names:**
- `README.txt` (uppercase)
- `readme-template.txt` (hyphen)
- `read me.txt` (space)
- `readme.md` (wrong extension)
**Enum Validation:**
```python
# server.py:46
"enum": ["readme", "architecture", "api", "components", "schema"]
```
### Framework Documentation Files
**Location:** `frameworks/`
**Pattern:** `{FRAMEWORK_NAME}.md`
**Naming Rules:**
1. Alphanumeric characters allowed
2. Case-sensitive (usually uppercase)
3. Extension must be `.md`
4. No restrictions on character case
**Valid Framework Names:**
- `POWER.md`
- `COSTAR.md`
- `FiveS.md`
- `CRISPE.md`
- `CustomFramework.md`
**Discovery Pattern:**
```python
# Glob pattern: *.md
for file in FRAMEWORKS_DIR.glob("*.md"):
frameworks.append(file.name)
```
---
## Directory Structure Schema
### File System Layout
**Root Directory:** `{SERVER_DIR}/` (location of server.py)
**Complete Structure:**
```
docs-mcp/ # SERVER_DIR
├── server.py # Main server implementation
├── README.md # Project documentation
├── ARCHITECTURE.md # Architecture documentation
├── COMPONENTS.md # Component documentation
├── SCHEMA.md # This file
├── templates/ # Templates root
│ └── power/ # POWER framework templates
│ ├── readme.txt # README template
│ ├── architecture.txt # Architecture template
│ ├── api.txt # API template
│ ├── components.txt # Components template
│ └── schema.txt # Schema template
└── frameworks/ # Framework documentation
├── POWER.md # POWER framework
├── COSTAR.md # COSTAR framework
├── FiveS.md # Five S framework
└── CRISPE.md # CRISPE framework
```
### Path Resolution Schema
**Module-level Path Constants:**
```python
# server.py:16-18
SERVER_DIR = Path(__file__).parent # Absolute path to server directory
TEMPLATES_DIR = SERVER_DIR / "templates" / "power" # Template directory
FRAMEWORKS_DIR = SERVER_DIR / "frameworks" # Framework directory
```
**Path Schema:**
```yaml
paths:
server_dir:
type: Path
resolution: Path(__file__).parent
description: "Absolute path to server.py parent directory"
templates_dir:
type: Path
resolution: SERVER_DIR / "templates" / "power"
description: "POWER framework template storage"
frameworks_dir:
type: Path
resolution: SERVER_DIR / "frameworks"
description: "Framework documentation storage"
```
**Directory Requirements:**
1. `templates/power/` must exist for list_templates and get_template
2. `frameworks/` should exist for list_frameworks (gracefully handles missing)
3. All directories use forward slash path separator internally (pathlib)
4. Paths are resolved relative to server.py location
---
## Validation Rules
### Template File Validation
**Validation Checklist:**
1. **File Existence:**
```python
# server.py:92
if not template_file.exists():
return error_message
```
2. **Template Name Validation:**
```python
# Validated against enum in input schema
"enum": ["readme", "architecture", "api", "components", "schema"]
```
3. **File Readability:**
```python
# server.py:98-99
try:
with open(template_file, 'r', encoding='utf-8') as f:
content = f.read()
except Exception as e:
return error_message
```
4. **Content Format:**
- Must start with "framework: POWER"
- Must contain all required fields
- Must be valid UTF-8
**Validation Flow:**
```
Input: template_name
↓
Check: Is template_name in enum?
↓ Yes
Construct: template_file = TEMPLATES_DIR / f"{template_name}.txt"
↓
Check: Does template_file exist?
↓ Yes
Read: content = file.read()
↓
Check: Is content valid UTF-8?
↓ Yes
Return: TextContent with template content
```
### Input Parameter Validation
**JSON Schema Validation:**
All input parameters are validated against JSON Schema before tool execution.
**Validation Rules:**
1. **Type checking:** Parameters must match declared type (string, number, boolean, etc.)
2. **Required fields:** All required parameters must be present
3. **Enum validation:** String parameters with enum must match one of the allowed values
4. **Additional properties:** No extra parameters allowed (additionalProperties: false)
**Example Validation (get_template):**
```python
# Input schema enforces:
{
"template_name": {
"type": "string", # Must be string
"enum": ["readme", "architecture", "api", "components", "schema"] # Must be in enum
}
}
# Required: ["template_name"] # Must be present
# additionalProperties: false # No extra params
```
**Validation Errors:**
- Missing required parameter → MCP SDK returns error
- Invalid type → MCP SDK returns error
- Invalid enum value → MCP SDK returns error
- Extra parameters → MCP SDK returns error
### Output Format Validation
**Response Constraints:**
1. **Return Type:**
```python
# All tools must return list[TextContent]
def call_tool() -> list[TextContent]:
return [TextContent(type="text", text=result)]
```
2. **Array Length:**
- Must return exactly 1 TextContent object
- Empty arrays not allowed
- Multiple TextContent objects not used
3. **TextContent Validation:**
```python
# Required fields
TextContent(
type="text", # Must be "text"
text=str # Must be non-empty string
)
```
4. **Error Response Validation:**
```python
# Errors also return TextContent
except Exception as e:
return [TextContent(
type="text",
text=f"Error: {str(e)}" # Error prefix for clarity
)]
```
### File System Validation
**Directory Existence Checks:**
```python
# list_templates (server.py:71)
if TEMPLATES_DIR.exists():
# Proceed with listing
# list_frameworks (server.py:109)
if FRAMEWORKS_DIR.exists():
# Proceed with listing
```
**File Discovery Validation:**
```python
# Template discovery (server.py:72)
for file in TEMPLATES_DIR.glob("*.txt"):
# Only .txt files included
# Framework discovery (server.py:110)
for file in FRAMEWORKS_DIR.glob("*.md"):
# Only .md files included
```
**File Access Validation:**
- Read-only access enforced
- UTF-8 encoding assumed
- Exceptions caught and returned as error messages
---
## Data Relationships
### Template Name to File Path Mapping
**Schema:**
```yaml
template_mapping:
readme: templates/power/readme.txt
architecture: templates/power/architecture.txt
api: templates/power/api.txt
components: templates/power/components.txt
schema: templates/power/schema.txt
```
**Relationship Rules:**
1. Template name (enum value) maps to filename: `{name}.txt`
2. All templates stored in same directory: `templates/power/`
3. Enum values must exactly match file stems (filename without extension)
4. Case-sensitive mapping (lowercase only)
**Mapping Implementation:**
```python
# server.py:89
template_file = TEMPLATES_DIR / f"{template_name}.txt"
```
### Template Cross-References
**Reference Schema:**
```yaml
template_references:
readme:
references: []
architecture:
references: [readme]
placeholders: ["{{readme_summary}}"]
api:
references: [readme, architecture]
placeholders: ["{{readme_summary}}", "{{architecture_summary}}"]
components:
references: [readme, architecture, api]
placeholders: ["{{readme_summary}}", "{{architecture_summary}}", "{{api_summary}}"]
schema:
references: [readme, architecture, api, components]
placeholders: ["{{readme_summary}}", "{{architecture_summary}}", "{{api_summary}}", "{{components_summary}}"]
```
**Dependency Graph:**
```
readme (no dependencies)
↓
architecture (depends on readme)
↓
api (depends on readme, architecture)
↓
components (depends on readme, architecture, api)
↓
schema (depends on readme, architecture, api, components)
```
**Placeholder Format:**
- Pattern: `{{document_type}}_summary`
- Used for cross-referencing previous documentation
- Not automatically resolved (manual substitution required)
---
## Error Response Schema
### Error Message Format
**Standard Error Response:**
```json
{
"type": "text",
"text": "Error: {error_description}"
}
```
**Error Categories:**
#### 1. Template Not Found
```
Template '{template_name}' not found. Available: readme, architecture, api, components, schema
```
**Schema:**
```yaml
error_template_not_found:
pattern: "Template '{name}' not found. Available: {list}"
template_name: string
available_list: comma-separated string
```
#### 2. File Read Error
```
Error reading template: {exception_message}
```
**Schema:**
```yaml
error_file_read:
pattern: "Error reading template: {message}"
exception_message: string
```
#### 3. Directory Listing Error
```
Error listing templates: {exception_message}
Error listing frameworks: {exception_message}
```
**Schema:**
```yaml
error_directory_listing:
pattern: "Error listing {type}: {message}"
type: enum["templates", "frameworks"]
exception_message: string
```
#### 4. No Results Found
```
No templates found in templates/power/
No framework documentation found
```
**Schema:**
```yaml
error_no_results:
templates: "No templates found in templates/power/"
frameworks: "No framework documentation found"
```
**Error Handling Pattern:**
```python
try:
# Attempt operation
result = perform_operation()
return [TextContent(type="text", text=result)]
except Exception as e:
# Catch all errors, never crash
return [TextContent(type="text", text=f"Error: {str(e)}")]
```
---
## Schema Versioning
### Version Format
**Schema Version:** `{major}.{minor}.{patch}`
**Current Version:** 1.0.0
**Version Components:**
- **Major:** Breaking changes to schema structure
- **Minor:** Backward-compatible additions
- **Patch:** Documentation fixes, clarifications
**Version History:**
- **1.0.0** (2025-10-08): Initial schema documentation
### Compatibility Rules
**Backward Compatibility:**
1. Template file format must remain compatible
2. MCP tool input schemas must not break existing clients
3. Output format changes must be additive only
4. Enum values cannot be removed (only added)
**Breaking Changes (require major version bump):**
- Removing template enum values
- Changing required fields in templates
- Modifying TextContent response structure
- Changing file naming conventions
**Compatible Changes (minor version bump):**
- Adding new template enum values
- Adding optional fields to templates
- Adding new MCP tools
- Enhancing error messages
---
**AI Integration Notes**
This schema documentation is optimized for AI assistant integration. Key usage patterns:
1. **Template Validation:** Use schemas to validate template files before processing
2. **Input Construction:** Reference JSON schemas to construct valid tool inputs
3. **Output Parsing:** Use output schemas to parse and validate tool responses
4. **Error Handling:** Match error patterns to provide helpful feedback
5. **File Discovery:** Follow naming conventions to locate templates and frameworks
For AI assistants: Use this schema reference to:
- Validate template files conform to POWER framework structure
- Construct valid MCP tool requests with proper parameters
- Parse tool responses according to defined formats
- Handle errors gracefully using documented error patterns
- Understand relationships between templates for cross-referencing
**🤖 This SCHEMA document was generated using the docs-mcp schema template**
---
**Maintained by:** willh
**Last updated:** 2025-10-08
**Related documents:** README.md, ARCHITECTURE.md, API.md (future), COMPONENTS.md
