midnight-mcp

Midnight MCP Server is a community-maintained MCP Server developed by Olanetsoft (Idris Olubisi) and contributors, designed to provide AI assistants (Claude, Cursor, Windsurf, VS Code Copilot, etc.) with deep access to the Midnight blockchain ecosystem.

Core Capabilities#

Semantic Search#

• Semantic retrieval of Compact contracts, TypeScript code, and documentation
• Backend powered by Cloudflare Workers + Vectorize (OpenAI Embeddings)
• Indexes 102+ Midnight ecosystem repositories (from midnightntwrk organization and community partners)
• Real-time document fetching (fetch-docs)

Code Analysis & Compilation#

• Static Analysis: extract-contract-structure detects 15+ common error types (deprecated_ledger_block, invalid_void_type, invalid_pragma_format, etc.)
• Real-time Compilation: Validates Compact code and generates ZK circuits via hosted compilation service
  • Fast mode (skipZk=true): ~1-2 seconds for syntax validation
  • Full mode (fullCompile=true): ~10-30 seconds for ZK circuit generation
  • Automatic fallback to static analysis when compilation service is unavailable

AI Code Generation (requires client sampling support)#

• generate-contract: Generate contracts
• review-contract: Review contracts
• document-contract: Document contracts

Version Management & Migration#

• get-version-info, check-breaking-changes, get-migration-guide
• get-file-at-version, compare-syntax, get-latest-syntax

Composite Tools (saves 50-70% tokens)#

• upgrade-check, get-repo-context

Embedded Resources & Prompts#

• 9 offline resources: Compact syntax guides (v0.16-0.18), SDK API reference, OpenZeppelin contracts, tokenomics overview, wallet integration, common errors & solutions, etc.
• 5 prompt templates: create-contract, review-contract, explain-concept, compare-approaches, debug-contract

Installation & Deployment#

Prerequisites: Node.js 20+ (LTS recommended)

One-click Installation (Claude Desktop config example):

{
  "mcpServers": {
    "midnight": {
      "command": "npx",
      "args": ["-y", "midnight-mcp@latest"]
    }
  }
}

Same configuration applies to Cursor (.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json), VS Code Copilot (.vscode/mcp.json).

No API Key required. For higher GitHub API rate limits, add "GITHUB_TOKEN": "ghp_..." in env.

Local Development:

git clone https://github.com/Olanetsoft/midnight-mcp.git && cd midnight-mcp
npm install && npm run build && npm test

CLI Options & HTTP Endpoints#

npx midnight-mcp --help

• --stdio (default, for Claude Desktop)
• --http (HTTP + SSE)
• --port <number> (default 3000)
• --json (default YAML, improves LLM token efficiency by ~20-30%)
• --github-token (overrides GITHUB_TOKEN environment variable)

HTTP Endpoints: /health (health check), /mcp (Streamable HTTP), /sse (Server-Sent Events)

Local Mode (Privacy/Offline)#

{
  "mcpServers": {
    "midnight": {
      "command": "npx",
      "args": ["-y", "midnight-mcp@latest"],
      "env": {
        "MIDNIGHT_LOCAL": "true",
        "OPENAI_API_KEY": "sk-...",
        "CHROMA_URL": "http://localhost:8000"
      }
    }
  }
}

Requires local ChromaDB: docker run -d -p 8000:8000 chromadb/chroma

Architecture Overview#

• Frontend (MCP Server): TypeScript + tsup build, implements MCP protocol (28+ tools, 9 resources, 5 prompts, logging, completions, progress, sampling), supports stdio / HTTP + SSE transport
• Backend API: Cloudflare Workers + Vectorize (vector database), OpenAI Embeddings semantic search
• Compilation Service: Hosted compiler (migrated from onrender to railway), supports Compact compilation and ZK circuit generation
• Admin Panel: /dashboard?p=PASSWORD displays query volume, relevance scores, quality distribution, and search trends
• Dev Toolchain: Changesets (version management), Vitest (testing), GitHub Actions (CI/CD)

Project Info#

• Primary Language: TypeScript (99.7%), JavaScript (0.3%)
• Distribution: NPM package (midnight-mcp@latest)
• Latest Version: v0.2.16
• License: MIT