io.github.cyanheads/mcp-ts-template

Quick start · Capabilities · API reference · Examples

Build AI tools for anything you can describe

Connect an API, a dataset, or a workflow to an AI agent through the Model Context Protocol (MCP). Your project holds the domain code; @cyanheads/mcp-ts-core handles the auth, storage, logging, and transports underneath it.

Agent-native. Every scaffold ships the framework reference and a set of Agent Skills: workflows for designing tools, writing tests, reviewing security, and cutting releases. You decide what the server does; your agent follows the skills to build it.

The framework stays a dependency. Infrastructure fixes arrive as package upgrades. Run the maintenance skill and your agent bumps core, syncs the latest skills, and adopts what changed.

Quick start

Servers run on Bun, Node.js 24+, or Cloudflare Workers.

bunx @cyanheads/mcp-ts-core init my-mcp-server
cd my-mcp-server
bun install

The scaffold includes a source tree, build and test configuration, CLAUDE.md/AGENTS.md, Agent Skills, and plugin metadata for Claude Code and Codex. Open it in Claude Code, Codex, or another agent and describe what you want:

Build an MCP server for my team's inventory API. We need to find products, check stock across warehouses, investigate stock movements, and record adjustments and transfers. Let's get started.

Already have a TypeScript project? Run bun add @cyanheads/mcp-ts-core and register your definitions with createApp().

A tool is a schema and a function

This is a complete server that searches a three-item catalog. To try it, replace the scaffold's src/index.ts with it:

import { createApp, tool, z } from '@cyanheads/mcp-ts-core';

const catalog = ['Notebook', 'Mechanical pencil', 'Desk lamp'];

const search = tool('catalog_search', {
  description: 'Search catalog item names. An empty query lists all items.',
  annotations: { readOnlyHint: true },
  input: z.object({
    query: z.string().describe('Text to find in an item name'),
  }),
  output: z.object({
    items: z.array(z.string()).describe('Matching item names'),
  }),
  async handler({ query }) {
    return {
      items: catalog.filter((name) =>
        name.toLowerCase().includes(query.toLowerCase()),
      ),
    };
  },
});

await createApp({ name: 'catalog-mcp-server', title: 'catalog-mcp-server', tools: [search] });

Build and run it over HTTP:

bun run rebuild
bun run start:http

Point your MCP client at http://127.0.0.1:3010/mcp (Streamable HTTP), or have the client launch it over stdio with bun /absolute/path/to/dist/index.js.

What comes with it

Optional integrations (DuckDB, Supabase, the OpenTelemetry SDK) are peer dependencies; install them when you need them.

Give agents useful results

Two declared contracts shape what an agent gets back. enrichment carries success-path context (totals, the parsed query, empty-result notices), populated with ctx.enrich(). errors lists each expected failure with its recovery guidance, and the handler throws one with the typed ctx.fail().

runSearch(query, limit) stands in for your search backend. It returns { items, total, parsed }, or null when the index is down:

import { createApp, tool, z } from '@cyanheads/mcp-ts-core';
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

const search = tool('search', {
  description: 'Search the catalog and return ranked matches.',
  annotations: { readOnlyHint: true },
  input: z.object({
    query: z.string().describe('Search terms'),
    limit: z.number().int().min(1).default(10).describe('Max results'),
  }),
  output: z.object({
    items: z.array(z.string()).describe('Matching item names, best first'),
  }),
  enrichment: {
    effectiveQuery: z.string().describe('Query as the server parsed it'),
    totalCount: z.number().describe('Total matches before the limit'),
    notice: z.string().optional().describe('Guidance when nothing matched'),
  },
  errors: [
    {
      reason: 'index_unavailable',
      code: JsonRpcErrorCode.ServiceUnavailable,
      when: 'The upstream search index is unreachable.',
      retryable: true,
      recovery: 'Retry in a few seconds — the index may be briefly unavailable.',
    },
  ],
  handler: async (input, ctx) => {
    const res = await runSearch(input.query, input.limit);
    if (!res) throw ctx.fail('index_unavailable');
    ctx.enrich({ effectiveQuery: res.parsed, totalCount: res.total });
    if (res.items.length === 0) {
      ctx.enrich({ notice: `No matches for "${input.query}". Try broader terms.` });
    }
    return { items: res.items }; // enrichment never rides in the domain return
  },
});

await createApp({ tools: [search] });

Both contracts are advertised in tools/list, so clients see them before calling, and the definition linter checks the handler against them. A failure with a declared reason reaches the client carrying that entry's recovery hint, and every tool error carries the request ID its server log records share.

Same data across client surfaces

MCP hosts differ in which part of a tool result they hand the agent: structuredContent (JSON), content[] (text), or both. The framework fills both with the same data, so the agent sees the same result on any host.

format() renders the text side; without one, content[] gets JSON. The format-parity lint rule fails lint:mcp if any output field is missing from the rendered text. Enrichment needs no format() entry, because the framework adds it to both surfaces. This formatter renders the items as a markdown list:

format: (result) => [{
  type: 'text',
  text: result.items.length > 0
    ? result.items.map((name) => `- ${name}`).join('\n')
    : 'No matching items.',
}],

Resources

Resources expose data at a URI. This one reads from your own getItem() service:

import { resource, z } from '@cyanheads/mcp-ts-core';

export const itemData = resource('items://{itemId}', {
  description: 'Retrieve item data by ID.',
  params: z.object({
    itemId: z.string().describe('Item ID'),
  }),
  async handler(params) {
    return await getItem(params.itemId);
  },
});

Everything registers through createApp() in your entry point:

await createApp({
  name: 'my-mcp-server',
  title: 'my-mcp-server', // display name in client UIs
  tools: allToolDefinitions,
  resources: allResourceDefinitions,
  prompts: allPromptDefinitions,
  instructions: 'Brief composition hints for the model.', // optional, sent on every `initialize`
});

On Cloudflare Workers, createWorkerHandler() takes the same definitions from a separate entry point.

Runtime and integration details

• Auth and storage: Declare auth: ['scope'] on a definition and the scope is checked, under JWT or OAuth, before the handler runs. ctx.state is tenant-scoped storage over in-memory, filesystem, Supabase, or Cloudflare D1/KV/R2, chosen by config.
• Client interaction: Return ctx.requestInput(...) to ask the user for input, the client's model for a sample, or the client for its roots. The handler runs again with the answers on ctx.inputs.
• Protocol compatibility: HTTP serves 2026-07-28 clients (per-request _meta envelope) and session-based 2025-era clients. The SDK's compatibility layer handles input requests for the older ones.
• Server presentation: instructions gives the model server-wide guidance once, at initialize, instead of in every tool description. Identity fields (title, websiteUrl, description, icons) populate the client's server info, the /.well-known/mcp.json server card, and the HTTP landing page.
• Definition checks: lint:mcp checks names, schemas, scopes, annotations, format parity, and JSON Schema portability. It runs at build time, never at startup, so a new rule can't break a deployed server.
• DataCanvas: An optional DuckDB workspace where agents run SQL across staged API results and export CSV, Parquet, or JSON. Agents share a workspace by passing its canvas token. Enable it with CANVAS_PROVIDER_TYPE=duckdb and @duckdb/node-api (Bun or Node.js only). brapi-mcp-server walks through loading API results into a dataframe and querying it.
• Mirror: The /mirror module keeps a persistent local copy of a bulk upstream dataset in embedded SQLite with an optional FTS5 index, so tools query it locally instead of paging the live API on every call. You write the sync ingester and the schema; the framework handles storage, resumable initial loads, and incremental refreshes. Bun or Node.js only (better-sqlite3 is an optional peer on Node). faa-aircraft-registry-mcp-server serves the full FAA registry this way.

See the framework reference for configuration and handler patterns, and the observability guide for Pino logging and OpenTelemetry traces and metrics.

Server structure

my-mcp-server/
  src/
    index.ts                              # createApp() entry point
    worker.ts                             # createWorkerHandler() (optional)
    config/
      server-config.ts                    # Server-specific env vars
    services/
      [domain]/                           # Domain services (init/accessor pattern)
    mcp-server/
      tools/definitions/                  # Tool definitions (.tool.ts)
      resources/definitions/              # Resource definitions (.resource.ts)
      prompts/definitions/                # Prompt definitions (.prompt.ts)
  package.json
  tsconfig.json                           # extends @cyanheads/mcp-ts-core/tsconfig.base.json
  CLAUDE.md / AGENTS.md                   # Server conventions; points to core's framework reference

Framework infrastructure lives in node_modules; your source tree holds the server's definitions, configuration, and domain services.

Configuration

Core config comes from environment variables, validated with Zod. Server-specific variables get their own schema, parsed lazily so Workers can inject env at request time.

See CLAUDE.md/AGENTS.md for the full configuration reference.

API overview

Entry points

Builders

Context

Tool and resource handlers receive a Context. ctx.enrich and ctx.fail are typed against the definition's declared contracts:

Subpath exports

import { createApp, tool, resource, prompt } from '@cyanheads/mcp-ts-core';
import { createWorkerHandler } from '@cyanheads/mcp-ts-core/worker';
import { McpError, JsonRpcErrorCode, notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
import { checkScopes } from '@cyanheads/mcp-ts-core/auth';
import { markdown, fetchWithTimeout } from '@cyanheads/mcp-ts-core/utils';
import { OpenRouterProvider, GraphService } from '@cyanheads/mcp-ts-core/services';
import type { DataCanvas, CanvasInstance } from '@cyanheads/mcp-ts-core/canvas';
import { defineMirror, sqliteMirrorStore } from '@cyanheads/mcp-ts-core/mirror';
import { validateDefinitions } from '@cyanheads/mcp-ts-core/linter';
import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
import { mcpTest, toolContractSuite } from '@cyanheads/mcp-ts-core/testing/vitest';
import { fuzzTool, fuzzResource, fuzzPrompt } from '@cyanheads/mcp-ts-core/testing/fuzz';
import { renderAppTool } from '@cyanheads/mcp-ts-core/testing/apps';

See CLAUDE.md/AGENTS.md for the complete exports reference.

Examples

examples/ holds a reference server built only on the public exports. examples/index.ts (Node/Bun) and examples/worker.ts (Cloudflare Workers) register the same definitions/index.ts barrels.

Testing

import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
import { myTool } from '@/mcp-server/tools/definitions/my-tool.tool.js';

const ctx = createMockContext();
const input = myTool.input.parse({ query: 'test' });
const result = await myTool.handler(input, ctx);

createMockContext() gives you a recording log, a signal, and a state backed by a real StorageService over an in-memory provider, so key validation, TTL expiry, and the JSON round-trip of stored values behave as they do in production: a Date reads back as its ISO string, and a value JSON cannot encode rejects. It uses tenant 'default' unless you pass { tenantId }. Pass { errors: myTool.errors } for a typed ctx.fail, { inputResponses, requestState } to start a multi-round-trip handler at its second round, or { clientCapabilities } to set what the client declared (seeded responses are then filtered to the declared kinds, as in production).

/testing also exports createMockSession() for session-bound contexts, createFetchMock() as a strict fake for upstream HTTP, and runToolContract(), which runs a definition through schema, handler, formatting, and error-envelope checks. /testing/vitest adds the mcpTest fixtures (ctx, session, fetchMock, storage) and toolContractSuite().

/testing/fuzz uses fast-check to generate valid inputs from your Zod schemas plus adversarial payloads, then checks for crashes, stack-trace leaks, and prototype pollution:

import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';

const report = await fuzzTool(myTool, { numRuns: 100 });
expect(report.crashes).toHaveLength(0);
expect(report.leaks).toHaveLength(0);
expect(report.prototypePollution).toBe(false);

It also exports fuzzResource, fuzzPrompt, zodToArbitrary, and ADVERSARIAL_STRINGS for custom property-based tests.

/testing/apps is a headless MCP Apps host. renderAppTool connects to your server as an MCP Apps client, calls an app tool, loads its ui:// view into chrome-headless-shell inside the sandbox and CSP the MCP Apps spec prescribes, runs scripted steps against the view, and returns a report:

import { renderAppTool } from '@cyanheads/mcp-ts-core/testing/apps';

const run = await renderAppTool({
  server: { command: 'bun', args: ['run', 'dist/index.js'] }, // or { url }
  tool: 'my_app_tool',
  arguments: { query: 'probe' },
  steps: [{ click: '#action-btn' }, { screenshot: 'after-click' }],
});
expect(run.initialized).toBe(true);
expect(run.errors).toHaveLength(0);
expect(run.cspViolations).toHaveLength(0);

The report also carries every message between the view and the host, the view's rendered text, and the screenshot paths. The same run from the command line, writing report.json and the screenshots under --out:

bunx @cyanheads/mcp-ts-core app-render --tool my_app_tool --args '{"query":"probe"}' \
  --click '#action-btn' --out ./app-run -- bun run dist/index.js

It needs the optional peers @modelcontextprotocol/client and @modelcontextprotocol/ext-apps, and a chrome-headless-shell build: the newest one in Puppeteer's cache (npx @puppeteer/browsers install chrome-headless-shell@stable --path ~/.cache/puppeteer), or an explicit executable path through browserPath, --browser, or MCP_APPS_BROWSER_PATH. Installed Chrome, Edge, Brave, and Chromium are never searched for.

Documentation

• CLAUDE.md/AGENTS.md: the framework reference, covering exports, patterns, Context, error codes, auth, config, and testing. It ships in the npm package, so your agent reads it from node_modules after init.
• docs/telemetry/: every span, metric, and attribute the framework emits (observability.md), plus an example Grafana dashboard and query recipes for Datadog, New Relic, and Honeycomb (dashboards.md).
• CHANGELOG.md: version history, indexing one file per release under changelog/. Each has a summary, migration notes, and links to commits and issues; releases that need downstream changes carry agent-notes for the maintenance skill to act on.

Development

bun run rebuild        # clean + build (scripts/clean.ts + scripts/build.ts)
bun run devcheck       # full gate: lint/format, typecheck, MCP defs, packaging, framework antipatterns, docs/skills/changelog sync, audit, outdated, tracked-secrets and to-do marker scans
bun run lint:mcp       # validate MCP definitions against spec
bun run test:all       # rebuild + coverage + Node.js + Workers + integration
bun run test:package   # pack the tarball and consume it as an external project would

License

Apache 2.0 — see LICENSE.