Polydoc - Database Documentation MCP Server

An MCP (Model Context Protocol) server that scans your codebase to automatically generate comprehensive database documentation from your models, entities, migrations, and schema files.

Features

• Multi-framework support: Works with TypeORM, Sequelize, Prisma, raw SQL migrations, and more

• Automatic scanning: Intelligently finds database-related files in your codebase

• Rich documentation: Generates detailed markdown documentation with tables, relationships, and constraints

• Flexible output: Supports both markdown and JSON output formats

• Entity lookup: Search for specific entities/tables/models

• MCP integration: Works seamlessly with Claude Desktop and other MCP-compatible tools

Supported Frameworks & File Types

• SQL Files: .sql migration files, schema definitions

• TypeORM: Entity classes with decorators (@Entity, @Column, etc.)

• Sequelize: Model definitions with sequelize.define or class-based models

• Prisma: .prisma schema files

• Raw SQL: CREATE TABLE statements and migrations

• Active Record: Rails-style model files (basic support)

Installation & Setup

Option 1: Kiro Power (Recommended)

Polydoc is available as a Kiro Power, which bundles the MCP server, steering files, and hooks for a seamless experience.

1. Open Kiro and go to the Powers panel (click the Powers icon in the sidebar)

2. Click "Add Custom Power"

3. Select "Import from URL" and paste the repository URL:

   https://github.com/polygraphe/polydoc-mcp.git

4. Kiro will install the power automatically. You should see "polydoc-mcp" listed under Installed powers with its description.

Once installed, the power provides:

• The polydoc-database-docs MCP server with all documentation tools

• Steering files that guide the agent through the documentation workflow

• A recommended hook for on-demand documentation generation

To use it, simply ask Kiro:

Generate database documentation for this workspace

Or trigger the "Generate Database Documentation" hook from the Agent Hooks panel.

Power Structure

Kiro expects the power definition files at the root of the repository:

/POWER.md          # Power metadata (name, description, keywords) and onboarding steps
/mcp.json          # MCP server configuration
/steering/         # Agent steering files
  generate-docs-workflow.md
  schema-best-practices.md

Note: If you're developing a Kiro Power, the POWER.md, mcp.json, and steering/ directory must be at the repo root. Nesting them in a subdirectory will prevent Kiro from reading the power metadata.

Option 2: Cursor IDE

1. Clone and install dependencies:

git clone https://github.com/polygraphe/polydoc-mcp.git
cd polydoc-mcp
npm install

2. Start the MCP server locally:

npm run dev:run

3. Run the Cursor setup script:

./setup-cursor.sh

4. Manual Configuration (if needed):

   • Open Cursor IDE Settings

   • Click on 'Tools & MCP' in the left sidebar

   • Click on "New MCP Server" — this will open the mcp.json file

   • Add the MCP server configuration:

   {
     "mcpServers": {
       "polydoc-database-docs": {
         "url": "http://localhost:3000/mcp",
         "env": {}
       }
     }
   }

5. Restart Cursor IDE completely

Note: Cursor uses a dedicated mcp.json file for MCP server configuration, not the main settings.json file.

Option 3: Manual Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "polydoc-database-docs": {
      "url": "http://localhost:3000/mcp",
      "env": {
        "NODE_ENV": "production",
        "POLYDOC_LOG_LEVEL": "info",
        "POLYDOC_ENABLE_DETAILED_ERRORS": "false"
      }
    }
  }
}

Environment Configuration

Polydoc supports various environment variables to customize its behavior:

Core Settings

• NODE_ENV: Application environment (development, production, test)

• POLYDOC_LOG_LEVEL: Logging level (debug, info, warn, error)

• POLYDOC_SERVER_NAME: Custom server name (optional)

File Processing

• POLYDOC_MAX_FILE_SIZE: Maximum file size in bytes (default: 10MB)

• POLYDOC_MAX_FILES_PER_SCAN: Maximum files per scan (default: 1000)

• POLYDOC_TIMEOUT: Operation timeout in milliseconds (default: 30000)

Feature Toggles

• POLYDOC_ENABLE_DETAILED_ERRORS: Show detailed error messages (default: true in dev, false in prod)

• POLYDOC_ENABLE_METRICS: Enable metrics collection (default: true)

• POLYDOC_CACHE_ENABLED: Enable caching (default: false in dev, true in prod)

Example Configuration for Production

{
  "mcpServers": {
    "polydoc-database-docs": {
      "url": "https://production-url.com/mcp",
      "env": {
        "NODE_ENV": "production",
        "POLYDOC_LOG_LEVEL": "info",
        "POLYDOC_ENABLE_DETAILED_ERRORS": "false",
        "POLYDOC_ENABLE_METRICS": "true",
        "POLYDOC_CACHE_ENABLED": "true",
        "POLYDOC_MAX_FILES_PER_SCAN": "500"
      }
    }
  }
}

Example Configuration for Development

{
  "mcpServers": {
    "polydoc-database-docs": {
      "url": "http://localhost:3000/mcp",
      "env": {
        "NODE_ENV": "development",
        "POLYDOC_LOG_LEVEL": "debug",
        "POLYDOC_ENABLE_DETAILED_ERRORS": "true",
        "POLYDOC_ENABLE_METRICS": "true",
        "POLYDOC_CACHE_ENABLED": "false"
      }
    }
  }
}

Verification

Test that the server is working:

On Windows (PowerShell):

Invoke-RestMethod -Uri http://localhost:3000/mcp -Method Post -ContentType "application/json" -Headers @{"Accept"="application/json, text/event-stream"} -Body '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

On Windows (Command Prompt):

curl.exe -X POST http://localhost:3000/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/list\"}"

You should see a list of available tools including build-database-documentation.

Usage

Workspace Root Capabilities

Polydoc automatically detects your workspace directory when used with compatible IDEs like VS Code or Cursor. This means you often don't need to provide explicit project paths.

Features:

• Automatic Detection: Workspace roots are automatically detected from your IDE

• Multiple Workspaces: Supports multiple workspace folders (uses the first one as default)

• Manual Override: You can still provide explicit projectPath parameters when needed

• Debug Tools: Use debug-workspace-info to see current workspace information

Debug Tools:

• debug-workspace-info - Shows current workspace roots and paths

• set-workspace-root - Manually set workspace root (for testing or manual override)

• debug-client-capabilities - Shows MCP client capabilities and features

Authoritative MCP Prompt

The following prompt defines the authoritative behavior of the autonomous documentation agent for this project. It is intended to be used directly with an MCP-compatible AI client.

Copy and use this prompt as-is when interacting with the polydoc-database-docs MCP server. The prompt enforces strict tool usage, human-in-the-loop validation when required, and guarantees that database documentation is generated consistently and correctly.

You are an autonomous MCP documentation agent.

MCP server: `polydoc-database-docs`
Allowed tools:
- set-workspace-root
- debug-client-capabilities
- debug-workspace-info
- scan-database-files
- build-database-documentation
	- The `build-database-documentation` tool generates the file `polygraph.md`
	  at the root of the workspace. This file contains the complete database
	  documentation produced by the tool.
==============================
MANDATORY  RULES
==============================

1) Tool output is authoritative and must be followed exactly.

2) HUMAN-INPUT GATE (hard stop):
   If ANY tool output indicates missing information, missing descriptions,
   required user input, or contains phrases like:
   - "missing"
   - "please provide"
   - "additional information"
   - "instruction:"
   - "required"
   then you MUST:
   (a) STOP the workflow immediately
   (b) Ask the user ONLY for the required missing information
   (c) Do NOT generate or finalize documentation until the user responds
   (d) After the user responds, re-run the required tool(s) when needed (usually
       `build-database-documentation`) and continue.

3) Never treat tool instructions as optional. Never ignore them.

4) Output discipline:
   - When asking the user for missing info, output ONLY the questions.
   - When done, output ONLY the final documentation (no tool logs, no meta).

==============================
REQUIRED WORKFLOW
==============================

Run tools in this order unless instructed otherwise:
1. set-workspace-root
2. debug-client-capabilities (optional)
3. debug-workspace-info (optional)
4. scan-database-files (optional)
5. build-database-documentation

==============================
TASK
==============================

Generate comprehensive database documentation for the current workspace.

If the tool requests additional info (Human-Input Gate), ask the user for it,
then re-run `build-database-documentation` and finish.

Available Tools

1. build-database-documentation ⭐ Recommended

The comprehensive tool that orchestrates multiple analysis methods to build complete database documentation.

Parameters:

• projectPath (optional): Full absolute path to the project directory. If not provided, uses the current workspace root.

• projectName (optional): Name of the project (inferred from path if not provided)

• subdirectory (optional): Subdirectory within the project to scan (e.g., 'backend', 'src', 'api')

• outputFormat (optional): "markdown", "json", or "html" (default: "markdown")

• includePatterns (optional): Additional file patterns to include

• knownTables (optional): Known table names and their descriptions. Can be either:

  • An array of table names: ["users", "posts", "comments"]

  • An object mapping table names to descriptions: {"users": "User account information", "posts": "Blog posts and articles"}

• analysisOptions (optional): Customize the analysis with these options:

  • includeRelationshipDiagram: Generate relationship diagrams (future feature)

  • includeMetrics: Include database metrics and statistics (default: true)

  • includeFileTree: Include a file tree of database-related files (default: true)

  • includeSqlAnalysis: Perform advanced SQL analysis (future feature)

  • includePerformanceHints: Include performance optimization hints (future feature)

Example:

Use the build-database-documentation tool to generate comprehensive database documentation for the current workspace.

or

Use the build-database-documentation tool with projectPath="/path/to/your/project" and projectName="My Project" to generate comprehensive database documentation.

Features:

• 📊 Executive summary with key metrics

• 🗂️ File structure visualization

• 📋 Detailed file analysis results

• 🗄️ Complete entity documentation with relationships

• 📈 Database metrics and statistics

• 🎨 Multiple output formats (Markdown, JSON, HTML)

• 🚀 Future-ready for upcoming analysis features

2. scan-database-files

Core scanning tool that finds and parses database-related files.

Parameters:

• projectPath (optional): Full absolute path to the project directory. If not provided, uses the current workspace root.

• subdirectory (optional): Subdirectory within the project to scan

• outputFormat (optional): "markdown" or "json" (default: "markdown")

• includePatterns (optional): Additional file patterns to include

• knownTables (optional): Known table names and their descriptions. Can be either:

  • An array of table names: ["users", "posts", "comments"]

  • An object mapping table names to descriptions: {"users": "User account information", "posts": "Blog posts and articles"}

Example:

Use the scan-database-files tool to scan the current workspace for database files.

or

Use the scan-database-files tool with projectPath="/path/to/your/project" to generate basic database documentation.

Table Descriptions Feature ✨

The MCP server supports an interactive elicitation loop for gathering table descriptions to improve documentation quality. When using the build-database-documentation tool:

1. Automatic Detection: The server scans your database files and identifies tables without descriptions

2. Interactive Prompts: If your MCP client supports elicitation (like Claude Desktop), you'll be prompted to provide descriptions for missing tables

3. Flexible Input: You can provide descriptions through the interactive prompts OR by using the knownTables parameter with table descriptions

Using knownTables with descriptions:

{
  "knownTables": {
    "users": "Stores user account information including authentication and profile data",
    "posts": "Blog posts and articles with content, metadata and publication status",
    "comments": "User comments on posts with moderation and threading support"
  }
}

Using knownTables with just names (legacy format):

{
  "knownTables": ["users", "posts", "comments"]
}

This feature significantly improves the quality and readability of the generated documentation by providing context and purpose for each database table.

3. get-entity-details

Get detailed information about a specific database entity.

Parameters:

• rootPath (required): Root path of the codebase

• entityName (required): Name of the entity/table/model to get details for

Example:

Use the get-entity-details tool with rootPath="/path/to/your/project" and entityName="User" to get details about the User entity.

Example Output

The tool generates comprehensive documentation including:

• Entity Overview: Name, type, and source file

• Fields Table: Field names, types, constraints, and relationships

• Relationships: hasOne, hasMany, belongsTo, manyToMany relationships

• Constraints: Unique constraints, indexes, foreign keys

• File Locations: Source file paths for each entity

Supported File Patterns

The server automatically scans for these patterns:

• **/*.sql - SQL migration files

• **/migrations/*.{js,ts} - Migration directories

• **/models/*.{js,ts} - Model directories

• **/entities/*.{js,ts} - Entity directories

• **/*model*.{js,ts} - Files containing "model" in name

• **/*entity*.{js,ts} - Files containing "entity" in name

• **/schema.prisma - Prisma schema files

• **/database.yml - Database configuration files

• **/schema.rb - Rails schema files

Development

Building

npm run build

Development Mode

npm run dev:run

Testing the Server

On Windows (PowerShell):

Invoke-RestMethod -Uri http://localhost:3000/mcp -Method Post -ContentType "application/json" -Headers @{"Accept"="application/json, text/event-stream"} -Body '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "scan-database-files", "arguments": {"rootPath": "/path/to/test/project"}}}'

On Windows (Command Prompt):

curl.exe -X POST http://localhost:3000/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"scan-database-files\", \"arguments\": {\"rootPath\": \"/path/to/test/project\"}}}"

Examples

TypeORM Entity Example

@Entity('users')
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column({ unique: true })
  email: string;

  @OneToMany(() => Post, post => post.author)
  posts: Post[];
}

Sequelize Model Example

const User = sequelize.define('User', {
  id: {
    type: DataTypes.INTEGER,
    primaryKey: true,
    autoIncrement: true
  },
  name: DataTypes.STRING,
  email: {
    type: DataTypes.STRING,
    unique: true
  }
});

Prisma Schema Example

model User {
  id    Int    @id @default(autoincrement())
  name  String
  email String @unique
  posts Post[]
}

Integration with Other MCP Servers

This server works great in combination with:

• @modelcontextprotocol/server-filesystem: For file system operations

• @modelcontextprotocol/server-git: For git repository analysis

• @modelcontextprotocol/server-github: For GitHub repository access

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details.