How InkPal Works

InkPal is a TypeScript MCP server with 157 tools across 12 domains. This post explains how it's built, how the pieces fit together, and why we made the architectural decisions we did.

The Stack

┌─────────────────────────────────┐
│  AI Agent (Claude, Cursor, etc) │
├─────────────────────────────────┤
│  MCP Protocol (stdio/SSE)       │
├─────────────────────────────────┤
│  InkPal MCP Server              │
│  ├── Tool Registry (157 tools)  │
│  ├── Safety Gates (18 checks)   │
│  ├── Cortex (context engine)    │
│  └── Constitution (rules)       │
├─────────────────────────────────┤
│  Domain Engines                 │
│  ├── PatternSearch (Supabase)   │
│  ├── ErrorDatabase              │
│  ├── VisionAnalyzer             │
│  ├── FigmaPipeline              │
│  ├── ShaderGenerator            │
│  └── ... 33 more               │
├─────────────────────────────────┤
│  External Services              │
│  ├── Supabase (patterns, auth)  │
│  ├── Railway (API hosting)      │
│  ├── Redis (caching)            │
│  └── Figma API                  │
└─────────────────────────────────┘

MCP Protocol

The Model Context Protocol is a JSON-RPC based protocol over stdio or Server-Sent Events. Each tool is registered with a name, description, and JSON Schema for its parameters. When the AI agent decides to use a tool, it sends a tools/call message:

{
  "method": "tools/call",
  "params": {
    "name": "patterns",
    "arguments": {
      "query": "infinite scroll",
      "limit": 5
    }
  }
}

InkPal routes this to the correct domain engine, executes the tool, and returns structured JSON.

Safety Gates

Every tool call passes through safety gates before execution. We have 18 gates covering:

• Blast radius analysis: Will this change break other files?
• Import graph validation: Are the imports safe and circular-free?
• Pubspec corruption prevention: Never break dependency resolution
• DNS rebinding protection: Block malicious localhost redirect attacks
• Session isolation: Each project gets its own sandboxed context
• HMAC verification: License key authenticity

Cortex — The Context Engine

Cortex is InkPal's memory. It maintains a CortexStore that tracks:

• Current project structure and dependencies
• Recent tool calls and their results
• Error history and fix patterns
• App DNA (learned project-specific patterns)

This means tool #47 in a chain knows what tool #1 discovered. The agent doesn't need to re-explain context.

App DNA

The most unique feature. App DNA learns your project's patterns:

dna_build → Scans your codebase, extracts patterns
dna_query → "How does this project handle authentication?"
dna_learn → Feeds new patterns from your latest code
dna_diff  → Shows what changed since last DNA build

Over time, InkPal's suggestions become project-specific, not generic.

Performance

The server handles ~400 TypeScript files and 50K+ lines of code. Key performance decisions:

• Lazy loading: Domain engines load on first use, not at startup
• Connection pooling: Single Supabase client, Redis connection reuse
• Streaming: Large pattern searches use streaming responses
• Caching: Frequently accessed patterns cached in Redis (5 min TTL)

What We Learned

Building a 157-tool MCP server taught us:

1. Safety is not optional. One bad fabricate call can overwrite hours of work. Gates prevent this.
2. Context is everything. Tools that share context via Cortex are 10x more useful than isolated tools.
3. Structured output > text output. Agents parse JSON reliably. They struggle with freeform text.
4. Test on real projects. Our test suite runs against actual Flutter apps, not mocked environments.

InkPal is open for early access. Get started free →