Engineering Documentation Server

Turn any software repository into professional engineering documentation — automatically.

A production-ready Model Context Protocol (MCP) server that analyzes code repositories and publishes comprehensive documentation directly to Google Docs. Works with Claude Code, Cursor, and any MCP-compatible AI assistant.

---

What It Does

Say this to your AI assistant:

"Document this project."

The server will:

1. Analyze the repository — languages, frameworks, API routes, DB models, env vars, CI/CD, dependencies
2. Generate 13 documentation sections with Mermaid architecture diagrams
3. Publish a formatted Google Doc and return the URL
4. Export to Markdown, HTML, or PDF (optional)

---

Features

Feature	Details
Language Detection	Python, JavaScript, TypeScript, Go, Rust, Java, C#, Ruby, PHP, and more
Framework Recognition	FastAPI, Django, Flask, Next.js, Express, NestJS, React, LangChain, LangGraph, and more
API Extraction	FastAPI, Flask, Django URLs, Express, Next.js App Router & Pages Router
Database Parsing	SQLAlchemy, Django ORM, Prisma, TypeORM, Mongoose
Architecture Diagrams	Mermaid flowcharts + ER diagrams
Google Docs	Create, update, share with professional formatting
Export Formats	Markdown, HTML (with Mermaid), PDF
CI/CD Detection	GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure DevOps
12 MCP Tools	Full tool suite exposed to AI assistants

---

Quick Start

1. Clone & Install

git clone https://github.com/your-org/engineering-docs-mcp.git
cd engineering-docs-mcp

# Using uv (recommended)
pip install uv
uv sync

# Or using pip
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

2. Set Up Google OAuth

Note (2026 UI): Google renamed "OAuth consent screen" to Google Auth Platform and reorganized it into tabs: Branding, Audience, Data Access, and Clients. The steps below reflect the current UI.

Step 1 — Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click the project dropdown (top-left) → New Project
3. Give it a name (e.g. Engineering Docs MCP) → Create

Step 2 — Enable the Required APIs

1. Go to APIs & Services → Library
2. Search "Google Docs API" → click it → Enable
3. Search "Google Drive API" → click it → Enable

Step 3 — Configure Google Auth Platform

1. Go to APIs & Services → Google Auth Platform

2. If you see a "Get Started" button, click it — this launches the setup wizard:

   Wizard — App Information

   Field	Value
   App name	Engineering Docs MCP
   User support email	Your Gmail address

   Click Next

   Wizard — Audience

   • Select External (works with any Gmail; choose Internal only for Google Workspace orgs)
   • Click Next

   ⚠️ You cannot change External → Internal later without creating a new project.

   Wizard — Contact Information

   • Enter your email for Google notifications
   • Click Next → Create

Step 4 — Add Scopes (Data Access Tab)

1. Click the Data Access tab
2. Click Add or Remove Scopes
3. In the filter/search box:
   • Search Google Docs → check /auth/documents
   • Search Google Drive → check /auth/drive
4. Click Update → Save

Step 5 — Add Test Users (Audience Tab)

1. Click the Audience tab
2. Scroll down to Test users → click + Add Users
3. Enter your Gmail address → Add → Save

While in Testing mode only listed emails can authenticate. You never need to publish the app for personal/dev use.

Step 6 — Create OAuth Credentials (Clients Tab)

1. Click the Clients tab
2. Click + Create Client
3. Application type: Desktop app
4. Name: Engineering Docs MCP → Create
5. In the dialog that appears, click Download JSON
6. Rename the downloaded file to credentials.json
7. Place it in the project root:

documentation_mcp/
├── credentials.json   ← here
├── server.py
└── ...

Quick Reference — Old vs New UI

Old UI	New UI (2026)
OAuth consent screen	Google Auth Platform
App information page	Branding tab
Scopes page	Data Access tab
Test users page	Audience tab
Credentials page	Clients tab

3. Configure Environment

cp .env.example .env
# Edit .env if needed — defaults work for most setups

4. Run the Server

python server.py

On first run, a browser window will open for Google OAuth authentication. After authorizing, a token.json is saved for subsequent runs.

---

Connecting to Claude Code

Add the server to your Claude Code MCP configuration:

# Edit ~/.claude/claude_desktop_config.json (Mac/Linux)
# or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "engineering-docs-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/engineering-docs-mcp/server.py"],
      "env": {
        "GOOGLE_CREDENTIALS_FILE": "/absolute/path/to/credentials.json"
      }
    }
  }
}

Or using uv:

{
  "mcpServers": {
    "engineering-docs-mcp": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/engineering-docs-mcp",
        "run", "python", "server.py"
      ]
    }
  }
}

Restart Claude Code to load the server.

---

Connecting to Cursor

Add to Cursor's MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "engineering-docs-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/engineering-docs-mcp/server.py"]
    }
  }
}

---

Example Prompts

Once connected, use natural language:

Document this project.

Analyze /path/to/my-api and create a Google Doc. Share it with [email protected].

Generate API documentation for the repository at /home/user/projects/my-service.

Export the documentation for /path/to/repo as Markdown.

Show me the database schema for /path/to/project.

Generate a README for /path/to/my-project.

Update Google Doc abc123 with the latest docs for /path/to/repo.

---

Available MCP Tools

Tool	Description
analyze_repository	Analyze a repo and return structured metadata
generate_project_documentation	Full pipeline: analyze → generate → publish to Google Docs
create_google_doc	Create a formatted Google Doc from analysis
update_google_doc	Update an existing Google Doc by ID
document_api	Extract and document all API endpoints
document_database	Extract and document all database models
generate_readme	Generate a professional README.md
generate_architecture	Generate architecture docs with Mermaid diagrams
export_markdown	Export documentation as Markdown
export_html	Export documentation as styled HTML
export_pdf	Export documentation as PDF (requires weasyprint)
share_google_doc	Share a Google Doc with email addresses

---

Generated Documentation Sections

Every generated document includes:

1. Executive Summary — What the project does in plain language
2. Project Overview — Purpose, features, stats, contributors
3. Technology Stack — Languages, frameworks, databases, infrastructure
4. Folder Structure — Annotated directory tree
5. Architecture — Patterns, request flow, Mermaid flowchart
6. API Documentation — All endpoints with methods, auth, handlers
7. Database Documentation — Models, fields, relationships, ER diagram
8. Environment Variables — All env vars with descriptions and examples
9. Installation Guide — Step-by-step setup instructions
10. Deployment — Docker, Kubernetes, CI/CD instructions
11. Dependencies — Production and dev dependencies with purposes
12. Security Notes — Auth, secrets, recommendations
13. Future Improvements — Suggested enhancements based on analysis

---

Docker

# Copy environment file
cp .env.example .env

# Build and run
docker compose up -d

# View logs
docker compose logs -f mcp-server

The Docker setup mounts:

• ./credentials.json — Google OAuth credentials (read-only)
• ./token.json — OAuth token (persisted across restarts)
• ./output/ — Generated export files
• ${REPOS_ROOT:-/repos} — Host directory for repository access

---

Development

# Install dev dependencies
uv sync

# Run tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Lint
ruff check .
ruff format .

# Type check
mypy .

Project Structure

engineering-docs-mcp/
│
├── server.py                 # FastMCP server with 12 tools
│
├── analyzers/                # Repository analysis engines
│   ├── orchestrator.py       # Runs all analyzers in sequence
│   ├── structure.py          # File/folder structure + language detection
│   ├── framework.py          # Framework, CI/CD, auth, deployment detection
│   ├── api.py                # API endpoint extraction
│   ├── database.py           # ORM model extraction
│   ├── environment.py        # Environment variable extraction
│   ├── dependencies.py       # Dependency manifest parsing
│   └── git_info.py           # Git metadata
│
├── generators/               # Documentation section generators
│   ├── orchestrator.py       # Assembles complete documentation
│   ├── overview.py           # Executive summary + project overview
│   ├── tech_stack.py         # Technology stack + architecture + Mermaid diagrams
│   ├── structure.py          # Folder structure section
│   ├── api_docs.py           # API documentation tables
│   ├── database_docs.py      # Database documentation tables
│   ├── env_docs.py           # Environment variables table
│   ├── installation.py       # Installation guide + deployment
│   ├── security.py           # Security notes + future improvements
│   └── dependencies_docs.py  # Dependencies tables
│
├── google_docs/              # Google Docs integration
│   ├── auth.py               # OAuth 2.0 authentication
│   ├── client.py             # Create, update, share documents
│   └── formatter.py          # batchUpdate request builder
│
├── services/
│   ├── documentation.py      # High-level pipeline orchestrator
│   └── export.py             # Markdown / HTML / PDF export
│
├── models/
│   ├── analysis.py           # Pydantic models for repository analysis
│   └── documentation.py      # Pydantic models for documentation
│
├── config/
│   └── settings.py           # Pydantic Settings configuration
│
├── tests/                    # pytest test suite
│
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── .env.example

---

Supported Frameworks

Language	Frameworks
Python	FastAPI, Django, Flask, LangChain, LangGraph, Celery, SQLAlchemy, Alembic
JavaScript / TypeScript	Next.js, React, Express, NestJS, Nuxt.js, Vue, Angular, Fastify, Hono
Testing	pytest, Jest, Vitest
Infrastructure	Docker, Kubernetes, Terraform

---

Environment Variables

Variable	Default	Description
GOOGLE_CREDENTIALS_FILE	credentials.json	Path to Google OAuth credentials
GOOGLE_TOKEN_FILE	token.json	Path to cached OAuth token
DEFAULT_OUTPUT_FORMAT	google_docs	Default output: google_docs, markdown, html, pdf
DEFAULT_DOC_TITLE	Engineering Documentation	Default document title
OUTPUT_DIR	output	Directory for exported files
LOG_LEVEL	INFO	Log verbosity: DEBUG, INFO, WARNING, ERROR
MAX_FILE_SIZE_KB	500	Maximum file size to parse (KB)
MAX_FILES_TO_ANALYZE	2000	Maximum files to include in analysis

---

Extending the Server

Adding a New Framework Detector

Edit analyzers/framework.py and add entries to FRAMEWORK_SIGNATURES:

Framework.MY_FRAMEWORK: [
    ("*.py", "from my_framework import"),
    ("requirements*.txt", "my-framework"),
],

Add the framework to the Framework enum in models/analysis.py.

Adding a New Documentation Section

1. Create a generator in generators/my_section.py extending BaseGenerator
2. Register it in generators/orchestrator.py
3. Add the field to ProjectDocumentation in models/documentation.py

---

Troubleshooting

FileNotFoundError: credentials.json Download OAuth credentials from the Clients tab in APIs & Services → Google Auth Platform and place credentials.json in the project root.

Can't find "OAuth consent screen" in the sidebar Google renamed it to Google Auth Platform. Navigate to APIs & Services → Google Auth Platform instead.

access_blocked error during OAuth login` Your email isn't in the Test Users list. Go to Google Auth Platform → Audience tab → Test users and add your Gmail address.

Token refresh failed Delete token.json and restart the server. A new browser authentication window will open.

Scopes not showing in Data Access tab The APIs must be enabled first. Go to APIs & Services → Library, enable Google Docs API and Google Drive API, then return to the Data Access tab.

PDF export fails WeasyPrint requires system libraries. On Ubuntu/Debian:

apt-get install libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0

No API endpoints detected Ensure the repository uses supported frameworks. Currently supports FastAPI, Flask, Django, Express, and Next.js route handlers.

---

License

MIT — see LICENSE for details.