mcponce

Cross-platform, single-executable Model Context Protocol (MCP) server framework powered by Hono and the official Model Context Protocol TypeScript SDK.

[!NOTE] Project Status: Alpha (v0.2.x) mcponce is currently in active Alpha development. Features and developer utilities are functional and covered by extensive tests, but APIs and internals may refine ahead of a v1.0.0 stable release. Community feedback and contributions are welcome!

npm install mcponce

⚡ Overview #

mcponce is an all-in-one developer framework (Alpha) for building, testing, and observing MCP servers for LLM agents (Claude Desktop, Cursor, Antigravity, custom AI workflows).

Unlike raw SDK setups that require managing subprocess lifecycles, setting up custom HTTP routers, or creating separate proxy daemons, mcponce packages everything into a single runnable file:

graph TD
    Client["AI Client (Cursor / Claude Desktop)"]
    CLI["Developer CLI (mcponce call)"]

    subgraph mcponce Server
        Router["Hono HTTP Router (/mcp, /health, /info, /metrics, /analytics)"]
        MW["Middleware Pipeline (app.use)"]
        Validator["Pre-compiled Zod Schema Validation"]
        Cache["In-Memory LRU Response Cache"]
        Queue["Concurrency & FIFO Mutex Queues"]
        Handler["Tool Execution & Inter-Tool Calling"]
        Telemetry["Analytics & Prometheus Metrics"]
    end

    Daemon["Unitup Shared Background Instance"]

    Client -->|Streamable HTTP / SSE| Router
    CLI -->|Parametric Invocation| Handler
    Router --> MW --> Validator --> Cache
    Cache -->|Cache Miss| Queue --> Handler
    Handler --> Telemetry
    Router -.->|--background| Daemon

graph TD
    Client["AI Client (Cursor / Claude Desktop)"]
    CLI["Developer CLI (mcponce call)"]

    subgraph mcponce Server
        Router["Hono HTTP Router (/mcp, /health, /info, /metrics, /analytics)"]
        MW["Middleware Pipeline (app.use)"]
        Validator["Pre-compiled Zod Schema Validation"]
        Cache["In-Memory LRU Response Cache"]
        Queue["Concurrency & FIFO Mutex Queues"]
        Handler["Tool Execution & Inter-Tool Calling"]
        Telemetry["Analytics & Prometheus Metrics"]
    end

    Daemon["Unitup Shared Background Instance"]

    Client -->|Streamable HTTP / SSE| Router
    CLI -->|Parametric Invocation| Handler
    Router --> MW --> Validator --> Cache
    Cache -->|Cache Miss| Queue --> Handler
    Handler --> Telemetry
    Router -.->|--background| Daemon

🚀 30-Second Quickstart #

Create a file named server.ts (or server.js):

import { createMcpServer } from 'mcponce';

// Initialize server instance
const app = createMcpServer({
  name: 'my-assistant-tools',
  version: '1.0.0'
});

// Register a type-safe tool
app.tool({
  name: 'calculate_mortgage',
  description: 'Calculates monthly mortgage payments based on loan amount and interest',
  inputSchema: {
    principal: 'number',
    annualRatePercent: { type: 'number', default: 6.5 },
    years: { type: 'number', default: 30 }
  },
  cache: { ttlMs: 60_000 },
  handler: ({ principal, annualRatePercent, years }) => {
    const monthlyRate = annualRatePercent / 100 / 12;
    const totalMonths = years * 12;
    const monthlyPayment =
      (principal * monthlyRate) / (1 - Math.pow(1 + monthlyRate, -totalMonths));

    return {
      monthlyPayment: Math.round(monthlyPayment * 100) / 100,
      totalPayment: Math.round(monthlyPayment * totalMonths * 100) / 100
    };
  }
});

// Start listening or coordinate background daemon
app.run();

node server.js

npx tsx server.ts

npx mcponce call calculate_mortgage --principal 300000 --years 15

🌟 Key Capabilities #

• Single-Executable Architecture: Everything in one file. Run directly or package with Bun/pkg/SEA.
• Universal Background Service: Pass --background (or -b) to coordinate a background daemon powered by Unitup . Multiple local client windows automatically share a single server process without port collisions.
• Inter-Tool Invocations: Call tools within tools (context.callTool) with cycle detection and stack traces.
• In-Memory Response Caching: Hot LRU responses with customizable TTL and deterministic argument hashing.
• Smart Input Coercion: Automatically coerces stringified numbers, booleans, and JSON objects sent by LLMs or CLI flags.
• Dynamic Resource Templates: RFC 6570 parametric URI templates (users://{userId}/profile) with automated variable extraction, autocomplete handlers, and return normalization.
• Resource Subscriptions & Live Push: Client subscriptions (resources/subscribe, resources/unsubscribe) with live push updates (app.notifyResourceUpdated, app.notifyResourceListChanged).
• Security, Authentication & Rate Limiting: Multi-key Bearer/API Key auth, custom identity validators (auth.validate), tool-level RBAC scopes, sliding-window rate limiting (429 Retry-After), and standard security headers.
• MCP Sampling & Workspace Roots: Turn tools into autonomous sub-agents by requesting LLM completions back from the client (context.sample) and discovering open project directories (context.listRoots).
• OpenAPI & Swagger Tool Generation: Auto-generate type-safe MCP tools from any OpenAPI 3 or Swagger 2 spec with app.fromOpenApi().
• Interactive Web Inspector & Autocomplete: Zero-dependency browser playground at /inspect (mcponce inspect / server.js inspect) with live form execution and official MCP completion/complete support.
• Images & Binary Media: Return raw Buffers or use image(buffer) helpers with automatic magic byte MIME detection and base64 encoding.
• Onion Middlewares: Express/Koa-style middleware chain (app.use) for auth, tracing, and enrichment.
• Real-Time Progress: Native context.reportProgress streaming back to Claude Desktop and Cursor.
• Full Observability: Built-in GET /analytics, Prometheus GET /metrics, system://metrics MCP resource, and daily rotating logs.
• CLI Parametric Caller: Test tools from your terminal: mcponce call <tool> --key=value.

📚 Documentation Sections #