jakreymyers/good-docs-mcp

Good Docs MCP Server

A Model Context Protocol (MCP) server that provides intelligent access to Good Docs Project documentation templates, enabling AI agents to discover, retrieve, and validate technical documentation using established best practices.

Overview

The Good Docs MCP Server bridges the gap between static documentation templates and dynamic AI workflows. It enables tools like Claude and other MCP clients to automatically suggest appropriate documentation types, retrieve complete template packages, and validate documentation quality.

Current Features

• MCP Protocol: Basic Model Context Protocol server implementation
• Health Check: Server connectivity and status verification
• Development Framework: FastMCP-based foundation for AI agent integration

Planned Features (Roadmap)

• Template Discovery: Browse and search Good Docs Project templates
• Intelligent Suggestions: Get template recommendations based on project context
• Document Validation: Validate documentation against Good Docs standards
• Advanced MCP Tools: Complete template management and validation tools

Prerequisites

• Python 3.10 or higher
• pip 23.0 or higher

Installation

1. Clone the Repository

git clone <repository-url>
cd good-docs-mcp

2. Set Up Python Virtual Environment

# Create virtual environment
python3.10 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

3. Install Dependencies

# Install production dependencies
pip install -r requirements.txt

# Install development dependencies (for contributors)
pip install -r requirements-dev.txt

Usage

Running the MCP Server

# Using module execution
python -m good_docs_mcp

# Or using the entry point script (when package is installed)
good-docs-mcp

MCP Client Configuration

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "good-docs": {
      "command": "python",
      "args": ["-m", "good_docs_mcp"],
      "cwd": "/path/to/good-docs-mcp"
    }
  }
}

Development

Development Setup

1. Follow the installation steps above
2. Install pre-commit hooks:

pre-commit install

3. Run tests to verify setup:

pytest

Code Quality

This project uses several tools to maintain code quality:

• ruff: Fast Python linter and formatter (fully configured)
• mypy: Static type checking with strict configuration (fully implemented)
• pytest: Comprehensive testing framework (123 tests across unit, integration, and performance)
• pre-commit: Git hooks for code quality (configured and active)

Testing

# Run all tests
pytest

# Run tests with coverage
pytest --cov=good_docs_mcp

# Run specific test file
pytest tests/unit/test_server_consolidated.py

Linting and Formatting

# Run ruff linter
ruff check .

# Format code with ruff
ruff format .

# Run type checking
mypy src/

Architecture

The server follows a layered architecture:

• Tools: MCP tool implementations (src/good_docs_mcp/tools/)
• Services: Business logic (src/good_docs_mcp/services/)
• Data: Template data access (src/good_docs_mcp/data/)
• Models: Data models and schemas (src/good_docs_mcp/models/)
• Core: MCP protocol handling (src/good_docs_mcp/core/)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT License - see file for details.

Support

For issues and questions, please use the GitHub issue tracker.