# Engineering Documentation MCP Server

> **Turn any software repository into professional engineering documentation — automatically.**

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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

```bash
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](https://console.cloud.google.com)
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

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

### 4. Run the Server

```bash
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:

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

```json
{
  "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:**

```json
{
  "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`):

```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 team@example.com.
```

```
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

```bash
# 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

```bash
# 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](analyzers/framework.py) and add entries to `FRAMEWORK_SIGNATURES`:

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

Add the framework to the `Framework` enum in [models/analysis.py](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:
```bash
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](LICENSE) for details.