🌽 CornMCP

The AI Agent Intelligence Platform — MCP Server + Analytics Dashboard

Surgical code intelligence. Semantic memory. Quality enforcement. Stop burning tokens on full-file reads. Start extracting exactly what your agent needs.

---

What is CornMCP?

Corn Hub is a Model Context Protocol (MCP) server and real-time analytics dashboard that gives AI coding agents (Antigravity, Cursor, Claude Code, Codex) surgical access to your codebase through 18 specialized tools.

Instead of dumping entire files into the context window, CornMCP provides:

• 🧠 Semantic Memory — Agents remember across sessions via vector search
• 🔍 Native AST Engine — Real call graphs, type hierarchies, and symbol-level analysis via TypeScript Compiler API
• 📋 Quality Gates — Plans must score ≥80% before execution
• 📊 Live Analytics — Track every tool call, latency, and token savings
• 🔄 Multi-Agent Awareness — Agents see each other's changes in real-time
• 💾 Zero External Dependencies — No external services. Everything runs locally with SQLite.

---

Architecture

1. System Overview

How the three services connect and communicate.

graph TB
    subgraph IDE["🖥️ Your IDE"]
        Agent["🤖 AI Agent<br/>(Antigravity / Cursor / Claude)"]
    end

    subgraph MCP["🌽 corn-mcp :8317"]
        direction TB
        Transport["Streamable HTTP Transport<br/>/mcp endpoint"]
        Auth["API Key Auth<br/>middleware/auth.ts"]
        Tools["18 MCP Tools"]
        Telemetry["Telemetry Interceptor<br/>Logs every tool call"]

        subgraph ToolGroups["Tool Modules"]
            Memory["🧠 memory.ts<br/>store / search"]
            Knowledge["📚 knowledge.ts<br/>store / search"]
            Code["🔍 code.ts<br/>search / read / context<br/>impact / cypher"]
            Quality["📋 quality.ts<br/>plan_quality / report"]
            Session["🔄 session.ts<br/>start / end"]
            Analytics["📊 analytics.ts<br/>tool_stats"]
            Changes["🔀 changes.ts<br/>changes / detect"]
            Health["💚 health.ts<br/>health / list_repos"]
        end
    end

    subgraph API["⚡ corn-api :4000"]
        direction TB
        Hono["Hono REST API"]
        Routes["15 Route Modules"]
        AST["Native AST Engine<br/>TypeScript Compiler API"]
        SQLite[("💾 SQLite<br/>corn.db")]
        VectorDB[("🧲 SQLite Vector Store<br/>mem9-vectors.db")]
    end

    subgraph Dashboard["📊 corn-web :3000"]
        NextJS["Next.js 16 Dashboard<br/>Turbopack"]
    end

    subgraph Embeddings["☁️ External (Optional)"]
        Voyage["Voyage AI API<br/>voyage-code-3"]
    end

    Agent -->|"JSON-RPC over HTTP<br/>Bearer Token"| Transport
    Transport --> Auth
    Auth --> Tools
    Tools --> Telemetry
    Telemetry -->|"POST /api/metrics/query-log"| Hono

    Memory -->|"Embeds + stores vectors"| VectorDB
    Memory -.->|"Optional: Voyage AI"| Voyage
    Knowledge -->|"Embeds + stores vectors"| VectorDB
    Code -->|"POST /api/intel/*"| Hono
    Quality -->|"POST /api/quality/*"| Hono
    Session -->|"POST /api/sessions/*"| Hono
    Analytics -->|"GET /api/analytics/*"| Hono
    Changes -->|"POST /api/intel/detect-changes"| Hono
    Health -->|"GET /health"| Hono

    Hono --> Routes
    Routes --> AST
    Routes --> SQLite
    AST --> SQLite
    NextJS -->|"fetch() to :4000"| Hono

    style IDE fill:#1a1a2e,stroke:#e94560,color:#fff
    style MCP fill:#16213e,stroke:#0f3460,color:#fff
    style API fill:#0f3460,stroke:#533483,color:#fff
    style Dashboard fill:#533483,stroke:#e94560,color:#fff
    style Embeddings fill:#2d2d2d,stroke:#666,color:#aaa

How It Works

Connection	Protocol	Description
IDE → corn-mcp	JSON-RPC over HTTP	AI agent sends tool calls via MCP SDK. Bearer token auth required.
corn-mcp → corn-api	REST HTTP (fetch)	Tool handlers call Dashboard API endpoints for data persistence.
corn-mcp → SQLite vectors	Direct file I/O	Memory and knowledge tools embed content and store vectors locally.
corn-mcp → Voyage AI	HTTPS API	Optional: semantic embeddings for memory/knowledge search. Falls back to local hash if unavailable.
corn-api → SQLite	sql.js (in-process)	All data stored in ./data/corn.db — sessions, quality, code graph, analytics.
corn-web → corn-api	REST HTTP (fetch)	Dashboard fetches data from :4000 API for real-time visualization.
Telemetry	Fire-and-forget POST	Every tool call logs to /api/metrics/query-log for analytics dashboard.

---

2. MCP Request Lifecycle

What happens step-by-step when your AI agent calls a Corn Hub tool.

sequenceDiagram
    participant Agent as 🤖 AI Agent
    participant IDE as 🖥️ IDE (MCP Client)
    participant MCP as 🌽 corn-mcp
    participant Auth as 🔐 Auth Middleware
    participant Tool as 🔧 Tool Handler
    participant API as ⚡ corn-api
    participant DB as 💾 SQLite
    participant Vec as 🧲 Vector Store
    participant Embed as ☁️ Embeddings

    Note over Agent,IDE: Agent decides to call corn_memory_store

    Agent->>IDE: tools/call {name: "corn_memory_store", params: {...}}
    IDE->>MCP: POST /mcp (JSON-RPC, Bearer token)

    MCP->>Auth: validateApiKey(request)
    Auth-->>MCP: ✅ valid (agentId: "local-ide")

    MCP->>MCP: createMcpServer(env)
    MCP->>MCP: new WebStandardStreamableHTTPServerTransport()
    MCP->>MCP: mcpServer.connect(transport)

    MCP->>Tool: corn_memory_store({content, projectId, tags})

    Tool->>Embed: embed(["memory content"])
    alt Voyage AI available
        Embed-->>Tool: [0.12, -0.34, 0.56, ...] (1024 dims)
    else Fallback
        Embed-->>Tool: [hash-based vector] (256 dims)
    end

    Tool->>Vec: INSERT INTO vectors (id, embedding, payload)
    Vec-->>Tool: ✅ stored

    Tool-->>MCP: {content: [{type: "text", text: "✅ Memory stored (id: mem-abc123)"}]}

    MCP->>API: POST /api/metrics/query-log (fire-and-forget telemetry)
    Note over API: Logs: tool=corn_memory_store, status=ok, latency=401ms

    MCP-->>IDE: JSON-RPC response
    IDE-->>Agent: Tool result displayed

    Note over Agent: Agent continues with stored memory context

Key Details

• Stateless: Each request creates a fresh McpServer instance — no session state on the server
• Auth: Bearer token validated against API keys stored in corn-api database
• Telemetry: Every tool call is logged (tool name, status, latency, input size) as fire-and-forget
• Embedding Fallback: If Voyage AI is rate-limited or unavailable, auto-rotates models then falls back to local hash embeddings
• Model Rotation: voyage-code-3 → voyage-4-large → voyage-4 → voyage-code-2 → voyage-4-lite

---

3. The 18 MCP Tools — Categories & Data Flow

Every tool grouped by category, showing what backend each one hits.

graph LR
    subgraph Agent["🤖 AI Agent"]
        Call["Tool Call"]
    end

    subgraph Memory["🧠 Memory (2 tools)"]
        MS["corn_memory_store"]
        MR["corn_memory_search"]
    end

    subgraph Knowledge["📚 Knowledge (2 tools)"]
        KS["corn_knowledge_store"]
        KR["corn_knowledge_search"]
    end

    subgraph CodeIntel["🔍 Code Intelligence (7 tools)"]
        CS["corn_code_search"]
        CR["corn_code_read"]
        CC["corn_code_context"]
        CI["corn_code_impact"]
        CY["corn_cypher"]
        LR2["corn_list_repos"]
        DC["corn_detect_changes"]
    end

    subgraph QualityGates["📋 Quality (2 tools)"]
        PQ["corn_plan_quality"]
        QR2["corn_quality_report"]
    end

    subgraph Sessions["🔄 Sessions (2 tools)"]
        SS["corn_session_start"]
        SE["corn_session_end"]
    end

    subgraph Analytics2["📊 Analytics (2 tools)"]
        TS["corn_tool_stats"]
        CH["corn_changes"]
    end

    subgraph Health2["💚 Health (1 tool)"]
        HE["corn_health"]
    end

    subgraph Backends["Backends"]
        VecDB[("🧲 Vector Store<br/>SQLite")]
        APIDB[("💾 corn-api<br/>SQLite")]
        AST2["🏗️ AST Engine"]
        Git["📂 Git CLI"]
    end

    Call --> Memory & Knowledge & CodeIntel & QualityGates & Sessions & Analytics2 & Health2

    MS & MR --> VecDB
    KS & KR --> VecDB
    CS & CC & CI & CY & LR2 --> APIDB
    CS & CC & CI --> AST2
    CR --> Git
    DC --> Git
    DC --> AST2
    PQ & QR2 --> APIDB
    SS & SE --> APIDB
    TS --> APIDB
    CH --> APIDB
    HE --> APIDB

    style Agent fill:#e94560,stroke:#e94560,color:#fff
    style Memory fill:#1a1a2e,stroke:#0f3460,color:#fff
    style Knowledge fill:#1a1a2e,stroke:#0f3460,color:#fff
    style CodeIntel fill:#16213e,stroke:#533483,color:#fff
    style QualityGates fill:#0f3460,stroke:#e94560,color:#fff
    style Sessions fill:#533483,stroke:#e94560,color:#fff
    style Analytics2 fill:#2d2d2d,stroke:#666,color:#fff
    style Health2 fill:#1b4332,stroke:#2d6a4f,color:#fff

Tool Reference

#	Tool	Category	Backend	Description
1	corn_health	Health	API	System health — services, uptime, version
2	corn_list_repos	Code	API + AST	List indexed repositories with symbol counts
3	corn_code_search	Code	AST → SQLite	Hybrid vector/AST symbol search
4	corn_code_read	Code	Filesystem	Read raw source code from indexed repos
5	corn_code_context	Code	AST → SQLite	360° symbol view: callers, callees, hierarchy
6	corn_code_impact	Code	AST → SQLite	Blast radius analysis with recursive CTE
7	corn_cypher	Code	AST → SQLite	Cypher-to-SQL graph queries
8	corn_detect_changes	Code	Git + AST	Uncommitted changes cross-referenced with graph
9	corn_memory_store	Memory	Vector DB	Store agent memory with embedding
10	corn_memory_search	Memory	Vector DB	Semantic similarity search over memories
11	corn_knowledge_store	Knowledge	Vector DB	Store shared knowledge item
12	corn_knowledge_search	Knowledge	Vector DB	Semantic search over knowledge base
13	corn_plan_quality	Quality	API SQLite	Score a plan against 8 criteria (must ≥80%)
14	corn_quality_report	Quality	API SQLite	Submit 4-dimension quality report (must ≥80%)
15	corn_session_start	Session	API SQLite	Begin tracked work session
16	corn_session_end	Session	API SQLite	End session with summary and decisions
17	corn_tool_stats	Analytics	API SQLite	View tool usage analytics and trends
18	corn_changes	Analytics	API SQLite	Check for recent commits by other agents

---

4. Data Flow — From Code to Intelligence

How your codebase becomes a queryable knowledge graph.

flowchart TD
    subgraph Input["📂 Your Codebase"]
        Files["*.ts, *.tsx, *.js, *.jsx files"]
    end

    subgraph Indexing["🏗️ AST Engine (ast-engine.ts)"]
        Collect["collectFiles()<br/>Recursively scan project<br/>Skip: node_modules, dist, .git"]
        Parse["ts.createProgram()<br/>TypeScript Compiler API<br/>Full type-aware parsing"]
        Extract["AST Walk<br/>Extract symbols + edges"]
        Store["SQLite Persist<br/>INSERT into code_symbols<br/>INSERT into code_edges"]
    end

    subgraph Symbols["📊 Extracted Data"]
        SymTable["code_symbols table<br/>965 rows"]
        EdgeTable["code_edges table<br/>407 rows"]
    end

    subgraph Queries["🔍 Query Layer (intel.ts)"]
        Search["searchSymbols()<br/>LIKE + ranking"]
        Context["getSymbolContext()<br/>JOIN callers/callees/imports"]
        Impact["getSymbolImpact()<br/>Recursive CTE traversal"]
        Cypher["executeCypher()<br/>Cypher → SQL translation"]
    end

    subgraph MCPTools["🌽 MCP Tool Surface"]
        T1["corn_code_search"]
        T2["corn_code_context"]
        T3["corn_code_impact"]
        T4["corn_cypher"]
    end

    subgraph AgentUse["🤖 Agent Uses"]
        Understand["Understand codebase<br/>architecture"]
        PlanChanges["Plan changes with<br/>blast radius awareness"]
        Navigate["Navigate call graphs<br/>and dependencies"]
        Refactor["Safe refactoring with<br/>impact analysis"]
    end

    Files --> Collect --> Parse --> Extract --> Store
    Store --> SymTable & EdgeTable
    SymTable & EdgeTable --> Search & Context & Impact & Cypher
    Search --> T1
    Context --> T2
    Impact --> T3
    Cypher --> T4
    T1 --> Understand
    T2 --> Navigate
    T3 --> PlanChanges
    T4 --> Refactor

    style Input fill:#1a1a2e,stroke:#e94560,color:#fff
    style Indexing fill:#16213e,stroke:#0f3460,color:#fff
    style Symbols fill:#0f3460,stroke:#533483,color:#fff
    style Queries fill:#533483,stroke:#e94560,color:#fff
    style MCPTools fill:#e94560,stroke:#fff,color:#fff
    style AgentUse fill:#2d6a4f,stroke:#40916c,color:#fff

Symbol Extraction Details

Symbol Kind	Example	What's Captured
Function	createLogger()	Name, params, return type, file, lines, exported?, signature
Class	CornError	Name, extends, implements, methods, properties
Interface	Logger	Name, members, extends
Type	LogLevel	Name, definition
Enum	HttpStatus	Name, members
Variable	app	Name, type annotation, initializer

Edge Types

Edge	Meaning	Example
calls	Function A calls Function B	start() → getDb()
imports	File A imports from File B	index.ts → @corn/shared-utils
extends	Class A extends Class B	NotFoundError → CornError
implements	Class implements Interface	LocalHashEmbeddingProvider → EmbeddingProvider

Performance: Corn Hub indexes itself (49 files) in ~2 seconds, extracting 965 symbols and 407 edges.

---

Project Structure

corn-hub/
├── apps/
│   ├── corn-api/              # Dashboard REST API (Hono + SQLite)
│   │   └── src/
│   │       ├── index.ts       # Server entry, health checks
│   │       ├── db/
│   │       │   ├── client.ts  # SQLite client (sql.js)
│   │       │   └── schema.sql # Database schema (code_symbols, code_edges, etc.)
│   │       ├── services/
│   │       │   └── ast-engine.ts  # 🆕 Native TypeScript Compiler API AST engine
│   │       └── routes/
│   │           ├── intel.ts      # Code intelligence (search, context, impact, cypher)
│   │           ├── indexing.ts   # Trigger AST analysis for projects
│   │           ├── analytics.ts  # Tool usage analytics
│   │           ├── knowledge.ts  # Knowledge base CRUD
│   │           ├── projects.ts   # Project management
│   │           ├── providers.ts  # LLM provider accounts
│   │           ├── quality.ts    # 4D quality reports
│   │           ├── sessions.ts   # Agent session tracking
│   │           ├── setup.ts      # System info
│   │           ├── stats.ts      # Dashboard metrics
│   │           ├── system.ts     # System metrics (CPU, memory)
│   │           ├── usage.ts      # Token usage tracking
│   │           └── webhooks.ts   # Webhook endpoints
│   │
│   ├── corn-mcp/              # MCP Server (18 tools)
│   │   └── src/
│   │       ├── cli.ts         # STDIO transport + telemetry interceptor
│   │       ├── index.ts       # Server factory + tool registration
│   │       ├── node.ts        # HTTP transport entry point
│   │       └── tools/
│   │           ├── analytics.ts   # corn_tool_stats
│   │           ├── changes.ts     # corn_changes, corn_detect_changes
│   │           ├── code.ts        # corn_code_search/read/context/impact, corn_cypher
│   │           ├── health.ts      # corn_health
│   │           ├── knowledge.ts   # corn_knowledge_search/store
│   │           ├── memory.ts      # corn_memory_search/store
│   │           ├── quality.ts     # corn_plan_quality, corn_quality_report
│   │           └── sessions.ts    # corn_session_start/end
│   │
│   └── corn-web/              # Analytics Dashboard (Next.js 16)
│       └── src/
│           ├── app/
│           │   ├── page.tsx       # Main dashboard
│           │   ├── quality/       # Quality reports & grade trends
│           │   ├── sessions/      # Agent session history
│           │   ├── usage/         # Token usage analytics
│           │   ├── knowledge/     # Knowledge base viewer
│           │   ├── projects/      # Project management
│           │   ├── installation/  # IDE setup guide
│           │   └── settings/      # Configuration
│           ├── components/
│           │   └── layout/        # Glassmorphic dashboard shell
│           └── lib/
│               └── api.ts         # API client
│
├── packages/
│   ├── shared-mem9/           # Vector DB + Embedding Provider
│   │   └── src/index.ts       # SQLite vector store, model rotation,
│   │                          # OpenAI/Voyage embeddings, hash fallback
│   ├── shared-types/          # Shared TypeScript interfaces
│   └── shared-utils/          # Logger, ID gen, error classes
│
├── infra/
│   ├── docker-compose.yml     # Optional Docker stack
│   ├── Dockerfile.corn-api
│   ├── Dockerfile.corn-mcp
│   ├── Dockerfile.corn-web
│   └── nginx-dashboard.conf
│
└── .agent/
    └── workflows/
        └── corn-quality-gates.md  # Mandatory AI quality workflow

---

Native AST Engine

Corn Hub includes a built-in TypeScript Compiler API engine that provides real code intelligence — no external services needed.

What It Extracts

Category	Details
Symbols	Functions, classes, interfaces, types, enums, variables, methods, properties
Edges	Function calls, imports, extends, implements
Metadata	File paths, line ranges, export status, signatures, JSDoc comments

How It Works

Local Project Directory
        │
        ▼
  collectFiles()          Recursively find all .ts/.tsx/.js/.jsx files
        │                 (skips node_modules, dist, .git, etc.)
        ▼
  ts.createProgram()      TypeScript Compiler API parses all files
        │
        ▼
  AST Walk                Extract symbols + build dependency edges
        │
        ▼
  SQLite Storage          INSERT into code_symbols + code_edges tables
        │
        ▼
  Query Functions         searchSymbols, getSymbolContext, getSymbolImpact,
                          executeCypher, getProjectStats

Capabilities

• Call Graph: Who calls dbRun? → 8 callers across 5 files with exact line numbers
• Impact Analysis: What breaks if I change createLogger? → Recursive CTE traces 6 downstream symbols
• Cypher Queries: MATCH (n:class) RETURN n → Finds all 10 classes in the codebase
• Import Mapping: Which files import from shared-utils? → Full dependency graph
• Type Hierarchies: CornError → NotFoundError, UnauthorizedError, ValidationError

Self-Indexing Results (Corn Hub itself)

Metric	Value
Files Analyzed	49
Symbols Extracted	965
Edges Built	407
By Kind	764 variables, 111 functions, 32 interfaces, 28 methods, 16 properties, 10 classes, 1 type
Analysis Time	~2 seconds

---

MCP Tools Reference

Corn Hub exposes 18 tools via the Model Context Protocol:

🧠 Memory & Knowledge

Tool	Description
corn_memory_store	Store a memory for cross-session recall
corn_memory_search	Semantic search across all agent memories
corn_knowledge_store	Save reusable patterns, decisions, bug fixes
corn_knowledge_search	Search the shared knowledge base

🔍 Code Intelligence (AST-Powered)

Tool	Description
corn_code_search	Hybrid vector + AST search across the codebase
corn_code_read	Read raw source from indexed repos with line ranges
corn_code_context	360° view of a symbol: callers, callees, imports, hierarchy
corn_code_impact	Blast radius analysis — recursive CTE on dependency edges
corn_cypher	Cypher-like queries translated to SQL against the code graph
corn_detect_changes	Analyze uncommitted changes + cross-reference with indexed symbols
corn_list_repos	List all indexed repositories with symbol/edge counts

📋 Quality & Sessions

Tool	Description
corn_plan_quality	Score a plan against 8 criteria (must pass ≥80%)
corn_quality_report	Submit 4D quality scores (Build, Regression, Standards, Traceability)
corn_session_start	Begin a tracked work session
corn_session_end	End session with summary, files changed, decisions
corn_changes	Check for recent changes from other agents

📊 Analytics & System

Tool	Description
corn_tool_stats	View tool usage analytics, success rates, latency
corn_health	System health check — all services, embedding status

---

Mandatory Quality Workflow

Every task follows this enforced pipeline:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  PHASE 0     │────▶│  PHASE 1     │────▶│  PHASE 2     │
│  Session     │     │  Planning    │     │  Execution   │
│  Start       │     │              │     │              │
│              │     │  Plan must   │     │  Build &     │
│ • tool_stats │     │  score ≥80%  │     │  implement   │
│ • changes    │     │  or REJECTED │     │              │
│ • memory     │     │              │     │              │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
┌──────────────┐     ┌──────────────┐             │
│  PHASE 4     │◀────│  PHASE 3     │◀────────────┘
│  Session     │     │  Quality     │
│  End         │     │  Report      │
│              │     │              │
│ • knowledge  │     │  Score must  │
│ • memory     │     │  be ≥80/100  │
│ • end        │     │  or FAIL     │
│ • stats      │     │              │
└──────────────┘     └──────────────┘

Configure in .agent/workflows/corn-quality-gates.md.

---

Installation

One-Command Installer (Recommended)

npx corn-install

The interactive installer will:

1. Check for Docker, Node.js, Git, pnpm
2. Install missing dependencies (with your permission)
3. Clone the Corn Hub repository
4. Configure Voyage AI API key for embeddings
5. Build and start the Docker stack
6. Configure your IDE (Antigravity, Claude Code, Cursor, VS Code, Codex, Windsurf)
7. Verify all 18 MCP tools are working

After installation, run the live monitor dashboard:

npx corn-install monitor

Prerequisites

• Node.js 22+
• pnpm 10+
• Docker (required for running the full stack)

Quick Start (Manual)

# Clone
git clone https://github.com/yuki-20/corn-hub.git
cd corn-hub

# Install dependencies
pnpm install

# Start the API backend
cd apps/corn-api && npx tsx src/index.ts

# In another terminal — start the MCP server (HTTP mode)
cd apps/corn-mcp && npx tsx src/node.ts

# In another terminal — start the dashboard
cd apps/corn-web && npx next dev

Service	Port	Description
corn-api	:4000	Hono REST API + SQLite + AST Engine
corn-mcp	:8317	MCP Gateway (HTTP transport)
corn-web	:3000	Next.js Dashboard

IDE Configuration

⚠️ Replace the path below with where YOU cloned corn-hub.

Antigravity / Codex (VS Code)

{
  "mcpServers": {
    "corn": {
      "command": "node",
      "args": ["/path/to/corn-hub/apps/corn-mcp/dist/cli.js"]
    }
  }
}

Cursor

1. Settings → Features → MCP
2. Click + Add new MCP server
3. Name: corn · Type: command
4. Command: node /path/to/corn-hub/apps/corn-mcp/dist/cli.js

Claude Code

claude mcp add corn -- node /path/to/corn-hub/apps/corn-mcp/dist/cli.js

OS	Example Path
Windows	C:\Users\You\corn-hub\apps\corn-mcp\dist\cli.js
macOS	/Users/You/corn-hub/apps/corn-mcp/dist/cli.js
Linux	/home/You/corn-hub/apps/corn-mcp/dist/cli.js

Indexing Your Project

Once the API is running, create a project and index it:

# Create a project pointing to your local repo
curl -X POST http://localhost:4000/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"My Project","gitRepoUrl":"/path/to/your/repo"}'

# Trigger AST analysis (returns projectId from above)
curl -X POST http://localhost:4000/api/intel/analyze \
  -H "Content-Type: application/json" \
  -d '{"projectId":"proj-XXXXX"}'

---

Dashboard (Optional Docker)

docker compose -f infra/docker-compose.yml up -d --build

Open http://localhost:3000 → the Corn Hub Analytics Dashboard.

Note: Docker is optional. All services run natively with Node.js for development.

---

Environment Variables

Variable	Default	Description
OPENAI_API_KEY	—	Voyage AI / OpenAI API key for embeddings
OPENAI_API_BASE	https://api.voyageai.com/v1	Embedding API base URL
MEM9_EMBEDDING_MODEL	voyage-code-3	Primary embedding model
MEM9_EMBEDDING_DIMS	1024	Embedding dimensions
MEM9_FALLBACK_MODELS	voyage-4-large,voyage-4,voyage-code-2,voyage-4-lite	Fallback model rotation chain
DASHBOARD_API_URL	http://localhost:4000	Dashboard API URL

Model Rotation

When the primary model hits rate limits (429), Corn Hub automatically rotates through fallback models:

voyage-code-3 → voyage-4-large → voyage-4 → voyage-code-2 → voyage-4-lite
 (best code)     (largest gen)    (gen-4)    (older code)    (lightweight)

Each model gets 3 retries with exponential backoff before rotating. Set MEM9_FALLBACK_MODELS to customize.

---

Real Token Savings (Measured Data)

These numbers are from actual usage, not theoretical projections.

During a live 29-call session on the Corn Hub codebase (55 files, 217 KB):

Metric	Value
Avg tokens per tool call	137 tokens
Avg tokens per file read (standard)	~1,500 tokens
Tool call overhead (29 calls)	3,966 tokens
File re-reads prevented	~34,600 tokens saved

Savings by Codebase Size

Repo Size	Standard Agent	With Corn Hub	Savings
Small (55 files)	~195K tokens	~135K tokens	30%
Medium (200 files)	~450K tokens	~180K tokens	60%
Large (1000 files)	~1.2M tokens	~250K tokens	79%
Enterprise (5000+)	~3M+ tokens	~400K tokens	87%

Corn Hub's semantic search is O(1) — it returns ~137 tokens regardless of codebase size.

---

Troubleshooting

Error: Cannot find module '.../dist/cli.js'

• Run pnpm build first — the dist/ folder is generated by the build step
• Check the path points to YOUR local clone
• On Windows, use forward slashes or escaped backslashes in JSON config

429 Too Many Requests from Voyage AI

• Free tier: 3 RPM, 10K TPM. Corn Hub automatically retries with backoff and rotates models
• Add a payment method at dashboard.voyageai.com for higher limits

Dashboard shows 0 agents / 0 queries

• Restart your IDE to reload the MCP server with the latest telemetry interceptor
• Ensure corn-api is running on port 4000

STDIO invalid character '\x1b' errors

• Corn Hub patches console.log to redirect to stderr. If a dependency bypasses this, check for ANSI color output leaking to stdout.

Code intelligence returns empty results

• Ensure your project is indexed: POST /api/intel/analyze {"projectId":"..."}
• Check the project has gitRepoUrl set to a valid local directory path

---

Tech Stack

Layer	Technology	Why
MCP Server	TypeScript + @modelcontextprotocol/sdk	Type-safe tool definitions
API	Hono 4	Ultra-fast, 0-dependency HTTP
Database	sql.js (WASM SQLite)	In-memory + file persistence, no C++ deps
AST Engine	TypeScript Compiler API	Real call graphs, not text grep
Vectors	SQLite vector store	Cosine similarity search, no external DB
Embeddings	Voyage AI (voyage-code-3)	Best-in-class code retrieval
Dashboard	Next.js 16 (Turbopack)	Fast dev, modern React
Monorepo	pnpm + Turborepo	Incremental builds

---

Releases

See the GitHub Releases page for version history and changelogs.

---

Contributors

yuki-20	AntiTamper
🏆 Creator & Lead	🤝 Co-Contributor

---

License

MIT © yuki-20