docs-mcp

Version: 1.0.5 Date: 2025-10-09 Maintainer: willh

---

Overview

docs-mcp is a Model Context Protocol (MCP) server that provides AI assistants with professional documentation generation capabilities and structured changelog management. It offers 7 specialized tools built on the POWER framework (Purpose, Output, Work, Examples, Requirements) for creating consistent, high-quality project documentation.

What It Does

• Documentation Generation: Create professional README, ARCHITECTURE, API, COMPONENTS, SCHEMA, and USER-GUIDE documents
• Changelog Management: Maintain structured, schema-validated changelogs with agent-friendly tooling
• Agentic Workflows: Enable AI agents to self-document their changes using the update_changelog meta-tool

Key Features

✅ 7 MCP Tools - Complete toolkit for documentation and changelog management ✅ POWER Framework - Structured templates ensure comprehensive documentation ✅ Changelog Trilogy - Read, write, and instruct pattern for changelog management ✅ Agentic Self-Documentation - Agents can autonomously document their own changes ✅ Schema Validation - JSON schema ensures changelog data integrity ✅ Multi-Project Support - Generic design works with any project

Security & Quality (v1.0.4-1.0.5)

🔒 SEC-001: Path traversal vulnerability fixed - All paths canonicalized with .resolve() 🔒 SEC-002: JSON schema validation - Automatic validation on all changelog operations 🔒 SEC-003: README routing corrected - README.md correctly saves to project root 📦 DEP-001: Added jsonschema dependency - Enables robust data validation

---

Prerequisites

Before using docs-mcp, ensure you have:

• Python 3.10+ - Required for MCP server
• MCP-compatible AI client - Claude Code CLI, Cursor, Windsurf, or VS Code with MCP support
• pip package manager - For installing Python dependencies

Verify Requirements

# Check Python version
python --version
# Should show: Python 3.10.x or higher

# Check MCP capability
claude mcp list

---

Installation

Quick Install (Claude Code)

# Add docs-mcp as a user-scoped MCP server
claude mcp add docs-mcp --scope user python "C:\Users\willh\.mcp-servers\docs-mcp\server.py"

Expected Output:

✓ docs-mcp added successfully

Manual Installation (Other IDEs)

For Cursor: Edit C:\Users\<username>\.cursor\mcp.json:

{
  "mcpServers": {
    "docs-mcp": {
      "command": "python",
      "args": ["C:\\Users\\willh\\.mcp-servers\\docs-mcp\\server.py"]
    }
  }
}

For Windsurf/VS Code: Similar configuration in IDE-specific MCP config file.

Verify Installation

claude mcp list

Expected Output:

docs-mcp: python C:\Users\willh\.mcp-servers\docs-mcp\server.py - ✓ Connected

---

Available Tools

Documentation Generation Tools (4)

Tool	Purpose	Required Parameters
list_templates	List available POWER templates	None
get_template	Get template content	template_name
generate_foundation_docs	Generate all 6 foundation docs	project_path
generate_individual_doc	Generate single document	project_path, template_name

Changelog Management Tools (3)

Tool	Purpose	Pattern	Required Parameters
get_changelog	Query changelog history	READ	project_path
add_changelog_entry	Add changelog entry	WRITE	project_path, version, change_type, severity, title, description, files, reason, impact
update_changelog	Agentic workflow guide	INSTRUCT	project_path, version

---

Quick Start

Generate Documentation for Your Project

# Ask Claude Code to generate all docs
"Generate foundation documentation for my project at C:\path\to\my-project"

This creates 6 documents:

• README.md → my-project/README.md (project root)
• ARCHITECTURE.md → my-project/coderef/foundation-docs/
• API.md → my-project/coderef/foundation-docs/
• COMPONENTS.md → my-project/coderef/foundation-docs/
• SCHEMA.md → my-project/coderef/foundation-docs/
• USER-GUIDE.md → my-project/coderef/foundation-docs/

Maintain a Changelog

Basic Workflow:

# 1. Make code changes
# 2. Ask agent to document them
"Use update_changelog to document my changes for version 1.0.3"

# Agent will:
# - Analyze changes autonomously
# - Determine change type and severity
# - Call add_changelog_entry with details
# - Update CHANGELOG.json

Manual Entry:

# Add specific changelog entry
add_changelog_entry(
    project_path="C:/path/to/project",
    version="1.0.3",
    change_type="feature",
    severity="major",
    title="Added new feature X",
    description="Implemented X with capabilities Y and Z",
    files=["server.py", "lib/feature.py"],
    reason="Users requested ability to...",
    impact="Users can now...",
    contributors=["your_name"]
)

---

Usage Examples

Example 1: Generate Project Documentation

# List available templates
list_templates()
# Returns: readme, architecture, api, components, schema, user-guide

# Generate all foundation documents
generate_foundation_docs(project_path="C:/Users/willh/my-project")

# Or generate just one document
generate_individual_doc(
    project_path="C:/Users/willh/my-project",
    template_name="api"
)

Example 2: Query Changelog History

# Get full changelog
get_changelog(project_path="C:/Users/willh/my-project")

# Get specific version
get_changelog(
    project_path="C:/Users/willh/my-project",
    version="1.0.2"
)

# Get all breaking changes
get_changelog(
    project_path="C:/Users/willh/my-project",
    breaking_only=true
)

# Filter by type
get_changelog(
    project_path="C:/Users/willh/my-project",
    change_type="feature"
)

Example 3: Agentic Self-Documentation

# Agent calls update_changelog
update_changelog(
    project_path="C:/Users/willh/my-project",
    version="1.0.3"
)

# Tool returns 3-step instructions:
# STEP 1: Analyze Your Changes
# STEP 2: Determine Change Details
# STEP 3: Call add_changelog_entry

# Agent analyzes context autonomously
# Agent executes add_changelog_entry(...)
# Changelog updated!

---

Project Structure

docs-mcp/
├── server.py                    # Main MCP server (7 tools)
├── generators/
│   ├── base_generator.py        # Base template generator
│   ├── foundation_generator.py  # Multi-doc generator
│   └── changelog_generator.py   # Changelog CRUD operations
├── templates/
│   └── power/                   # POWER framework templates
│       ├── readme.txt
│       ├── architecture.txt
│       ├── api.txt
│       ├── components.txt
│       ├── schema.txt
│       └── user-guide.txt
├── coderef/
│   ├── changelog/               # Changelog system
│   │   ├── CHANGELOG.json      # Structured changelog data
│   │   └── schema.json         # JSON schema validation
│   ├── foundation-docs/         # Generated documentation
│   └── quickref.md             # Quick reference guide
├── user-guide.md               # Comprehensive user guide
└── MCP-SETUP-GUIDE.md          # MCP server setup guide

---

Troubleshooting

Issue: "No such tool available: mcp__docs-mcp__*"

Symptom: MCP tools not found after adding server

Cause: MCP server not restarted or not properly registered

Resolution:

# 1. Verify server is registered
claude mcp list

# 2. If not listed, re-add
claude mcp add docs-mcp --scope user python "C:\Users\willh\.mcp-servers\docs-mcp\server.py"

# 3. Restart Claude Code or IDE

---

Issue: "Invalid project path"

Symptom: Error when calling tools with project_path parameter

Cause: Using relative path instead of absolute path

Resolution:

# ❌ Wrong: Relative path
generate_foundation_docs(project_path="./my-project")

# ✅ Correct: Absolute path
generate_foundation_docs(project_path="C:/Users/willh/my-project")

---

Issue: "Changelog not found"

Symptom: get_changelog or add_changelog_entry fails

Cause: No changelog exists at project_path/coderef/changelog/CHANGELOG.json

Resolution:

# add_changelog_entry automatically creates changelog structure
# Just call it with your first entry:
add_changelog_entry(
    project_path="C:/path/to/project",
    version="1.0.0",
    change_type="feature",
    severity="major",
    title="Initial release",
    description="Created project with...",
    files=["*"],
    reason="Initial development",
    impact="Project created"
)

---

Issue: Generated docs are generic

Symptom: Documentation doesn't mention specific project features

Cause: Minimal code in project or AI needs more context

Resolution:

1. Ensure project has actual implementation code
2. Add code comments explaining key features
3. Provide additional context to AI during generation
4. Manually enhance generated docs if needed

---

The Changelog Trilogy Pattern

docs-mcp implements a unique meta-tool pattern for changelog management:

┌─────────────────────────────────────────┐
│ get_changelog (READ)                    │
│ Query changelog history                 │
└─────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────┐
│ add_changelog_entry (WRITE)             │
│ Execute changelog update                │
└─────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────┐
│ update_changelog (INSTRUCT)             │
│ Orchestrate agentic workflow            │
│ → Agent analyzes context                │
│ → Agent determines details              │
│ → Agent calls add_changelog_entry       │
└─────────────────────────────────────────┘

Why This Matters:

• Separation of Concerns: Read/write/orchestrate are distinct operations
• Agentic Design: Agents can self-document without explicit prompting
• Flexibility: Use WRITE directly or INSTRUCT for autonomous workflows

---

Additional Resources

• user-guide.md - Comprehensive user guide with best practices
• coderef/quickref.md - Quick reference for all 7 tools
• coderef/changelog/CHANGELOG.json - Project changelog
• MCP-SETUP-GUIDE.md - General MCP server setup
• MCP Specification - Official MCP docs
• MCP Python SDK - SDK documentation

---

Version History

Version	Date	Changes
1.0.5	2025-10-09	JSON schema validation, README routing fix (SEC-002, SEC-003)
1.0.4	2025-10-09	Path traversal security fix, jsonschema dependency (SEC-001, DEP-001)
1.0.3	2025-10-09	Added update_changelog agentic workflow tool
1.0.2	2025-10-09	Added changelog system (get_changelog, add_changelog_entry)
1.0.1	2025-10-09	Bug fixes and improvements
1.0.0	2025-10-08	Initial release with 4 documentation tools

See CHANGELOG.json for detailed change history.

---

Contributing

We welcome contributions! When making changes:

1. Make your changes to the codebase
2. Test thoroughly to ensure everything works
3. Document your changes using update_changelog:

   update_changelog(
       project_path="C:/Users/willh/.mcp-servers/docs-mcp",
       version="1.0.x"
   )
   

4. Commit with clear message describing what changed
5. Submit pull request with reference to changelog entry

---

License

[Specify license here - MIT, Apache 2.0, etc.]

---

AI Integration Footer

This MCP server is optimized for AI assistant integration. It provides:

• Structured templates that guide documentation generation with consistent quality
• Decision trees for content selection embedded in templates
• Command sequences for systematic documentation workflows
• Agent-friendly tools that enable autonomous self-documentation

For AI Assistants: Use the POWER framework templates to ensure comprehensive documentation. Follow the work section for systematic analysis and the requirements section for mandatory elements. The update_changelog tool demonstrates the meta-tool pattern for orchestrating agent workflows.

---

🤖 Generated with docs-mcp v1.0.5 Maintained by: willh, Claude Code AI