Skip to content

Sim-xia/deepplan-mcp-plus

BranchesTags
 
 

Repository files navigation

DeepPlan Logo

DeepPlan MCP

Architectural Intelligence Engine for AI-Powered Development

Turn vague plans into production-ready architecture blueprints —
reviewed by a Council of AI Architects before you write a single line of code.

npm version MIT License MCP Compatible Website

Why DeepPlan?

Every AI coding assistant can generate code — but architecture is where projects succeed or fail. DeepPlan catches design flaws, security gaps, and performance bottlenecks before they become expensive rewrites.

Without DeepPlan With DeepPlan
Planning AI gives generic, shallow plans 4 expert architects analyze in parallel
Quality No guardrails — hallucination drift Constitution enforces architectural correctness
Perspective Single viewpoint Security + Performance + UX/DX + DevOps
Output Vague suggestions Numbered, executable steps for your AI agent 
Your Draft Plan → 🔒 Security · ⚡ Performance · 🎨 UX/DX · 🔧 DevOps → 👑 Lead Architect → Blueprint

Works With

DeepPlan uses the Model Context Protocol (MCP) — it works with any MCP-compatible client, not just IDEs:

Client Use Case
🖥️ Cursor, Windsurf, VS Code Copilot Architecture review while coding
💻 Claude Code Terminal-based planning and brainstorming
🤖 Claude Desktop, ChatGPT Conversational architecture consulting
🔧 Custom MCP Clients Build your own AI-powered architecture tools
📡 CI/CD & Automation Automated architecture linting in pipelines

Quick Start

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "deepplan": {
      "command": "npx",
      "args": ["-y", "deepplan-mcp"],
      "env": {
        "DEEPPLAN_API_KEY": "dpk_your-key-here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "deepplan": {
      "command": "npx",
      "args": ["-y", "deepplan-mcp"],
      "env": {
        "DEEPPLAN_API_KEY": "dpk_your-key-here"
      }
    }
  }
}

Claude Code

claude mcp add deepplan -- npx -y deepplan-mcp --api-key=dpk_your-key-here

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "deepplan": {
      "command": "npx",
      "args": ["-y", "deepplan-mcp"],
      "env": {
        "DEEPPLAN_API_KEY": "dpk_your-key-here"
      }
    }
  }
}

Get your API key at deepplan.dev/api-keys — free tier included.

Use Cases

🏗️ Starting a New Project

"Build me a SaaS with Stripe billing and multi-tenant auth"

Get a complete architecture blueprint — data model, API design, auth flow, deployment strategy — reviewed by 4 experts before writing a single line of code.

🔄 Major Refactoring

"Migrate our REST API to GraphQL"

Get expert analysis of migration risks, breaking changes, edge cases, and a step-by-step execution plan your AI coding assistant can follow.

🛡️ Security Review

"Review this authentication flow for vulnerabilities"

Get a Security Architect's threat model: injection vectors, data exposure risks, and concrete mitigations tied to your tech stack.

⚡ Performance Audit

"Optimize this data pipeline that's hitting 5s response times"

Get bottleneck analysis with specific optimizations: caching strategy, query patterns, cold start reduction — all for your actual stack.

🧩 API Design

"Design a public REST API for our platform"

Get DX analysis, versioning strategy, error handling patterns, rate limiting architecture, and documentation structure.

📋 Architecture Review in CI/CD

"Automatically review architecture decisions in pull requests"

Integrate DeepPlan into your pipeline to catch architectural anti-patterns before they reach production.

Tools

upgrade_architecture_blueprint

Send a draft plan to the Council of Architects for expert-level review.

Parameter Required Description
draft_plan Yes The architecture plan text to upgrade
tech_stack No e.g. "SvelteKit, Cloudflare Workers, D1"
context_constraints No e.g. "Must run on Edge Runtime"
model_choice No AI model for the Lead Architect synthesis

Returns: A structured blueprint with Architecture Directives, Edge Cases, Constraints, Patterns, and numbered Next Steps your AI agent can execute immediately.

auto_select_personas

Analyze a plan and recommend which expert personas are most relevant.

Parameter Required Description
draft_plan Yes The plan to analyze
available_personas No Custom persona list (defaults to 4 built-in experts)

The Constitution

Every council session enforces architectural guardrails called "The Constitution" — rules that prevent AI hallucination drift and ensure high-quality output:

  • Terminology Precision — Flags misused architectural terms (e.g., "fetch" for a DB query → should be "query")
  • Clean Architecture Metrics — Enforces low coupling, high cohesion, correct dependency direction
  • No Code Output — Experts focus on WHAT and WHY, never HOW in code
  • Tech Stack Awareness — All recommendations must reference your actual stack
  • Impact Prioritization — Most critical findings first, no filler

Built-in Expert Personas

Persona Focus Areas
🔒 Security Architect Auth, data exposure, injection, CORS, API abuse, secrets management
⚡ Performance Engineer Latency, caching, token cost, cold starts, DB queries, concurrency
🎨 UX/DX Designer Integration smoothness, error clarity, onboarding, config simplicity
🔧 DevOps Engineer Deploy strategy, CI/CD, monitoring, disaster recovery, scaling
👑 Lead Architect Synthesizes all expert reports into a unified, executable blueprint

Want domain-specific experts? Create custom personas at deepplan.dev — available via proxy mode.

Modes

Proxy Mode (Recommended)

Uses your DeepPlan API key (dpk_...). Requests are analyzed by DeepPlan Scout (expert analysis) and synthesized by DeepPlan Architect (blueprint generation).

DEEPPLAN_API_KEY=dpk_your-key-here

Premium features via proxy mode:

  • Custom personas and councils
  • Advanced orchestration (debate mode, AI+IDE refinement)
  • AI-powered search context (Librarian)
  • Usage tracking and credit management

Direct Mode (Fallback)

Uses your own OpenRouter API key. The council runs locally with 4 built-in expert personas. No DeepPlan account needed.

OPENROUTER_API_KEY=sk-or-v1-your-key-here

Configuration

Variable Description
DEEPPLAN_API_KEY DeepPlan API key — enables proxy mode with full features
OPENROUTER_API_KEY OpenRouter key — enables direct mode (fallback)
DRAFT_PLAN_MAX_LENGTH Max input characters (default: 8000)

Configuration priority: CLI args > environment variables > .env file

npx deepplan-mcp --api-key=dpk_your-key-here

Extend & Build

DeepPlan is designed to be extended. The open-source core gives you building blocks to create your own architectural intelligence:

  • Custom Personas — Add domain-specific experts (Database Architect, ML Engineer, etc.) in src/prompts/personas.ts
  • Search Providers — Plug in your own search backend by implementing the SearchProvider interface in src/search/types.ts
  • Custom Constitutions — Define your team's architectural standards and coding conventions
  • Pipeline Integration — Use as a pre-commit hook, CI/CD step, or automated PR reviewer
  • Build Your Own Client — The MCP protocol means any client can connect — build custom tools on top of DeepPlan

Architecture

┌─────────────────┐    stdio     ┌──────────────┐
│  MCP Client      │◄────────────►│  DeepPlan    │
│                  │    MCP       │  MCP Server  │
│  • AI IDEs       │    Protocol  │  (this repo) │
│  • CLI Tools     │             └──────┬───────┘
│  • Custom Apps   │                    │
└─────────────────┘       ┌─────────────┴──────────────┐
                          │                            │
                    Proxy Mode                   Direct Mode
                          │                            │
                   ┌──────▼──────┐            ┌────────▼────────┐
                   │ DeepPlan API │            │    OpenRouter    │
                   │ deepplan.dev │            │       API        │
                   │              │            │                  │
                   │ • Scout      │            │ • 4 built-in     │
                   │   (analysis) │            │   personas       │
                   │ • Architect  │            │ • Basic council  │
                   │   (synthesis)│            │                  │
                   │ • Debate     │            │                  │
                   │ • AI Search  │            │                  │
                   └──────────────┘            └──────────────────┘

Premium Features

The open-source client provides full council functionality with 4 built-in personas. For teams and power users, deepplan.dev offers:

Feature Open Source DeepPlan Pro
4 Built-in Experts ✅ ✅
Custom Personas — ✅
Council Builder — ✅
Debate Mode (Pro/Con) — ✅
AI Search (Librarian) — ✅
Chair Persona — ✅
Constitution Editor — ✅
Usage Dashboard — ✅

Development

# Clone
git clone https://github.com/gapgapweiqi/deepplan-mcp.git
cd deepplan-mcp

# Install
npm install

# Dev (with hot reload)
npm run dev

# Build
npm run build

# Type check
npm run typecheck

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT — use it however you want.

Built with ❤️ by DeepPlan

About

MCP server for DeepPlan — upgrade shallow Ai coding plans into expert-level architecture blueprints via a Council of AI Architects

deepplan.dev

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • TypeScript 81.0%
  • JavaScript 19.0%