mcp-ts-core

<div align="center"> <h1>@cyanheads/mcp-ts-core</h1> <p><b>TypeScript framework for building Model Context Protocol (MCP) servers. Declarative tool/resource/prompt definitions, pluggable auth, multi-backend storage, OpenTelemetry observability, and support for both local (stdio/HTTP) and edge (Cloudflare Workers) runtimes.</b></p> </div> <div align="center">

</div>

---

What is this?

@cyanheads/mcp-ts-core is the infrastructure layer for TypeScript MCP servers. Install it as a dependency — don't fork it. You write tools, resources, and prompts; the framework handles transports, auth, storage, config, logging, telemetry, and lifecycle.

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

const greet = tool('greet', {
  description: 'Greet someone by name and return a personalized message.',
  annotations: { readOnlyHint: true },
  input: z.object({ name: z.string().describe('Name of the person to greet') }),
  output: z.object({ message: z.string().describe('The greeting message') }),
  handler: async (input) => ({ message: `Hello, ${input.name}!` }),
});

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

That's a complete MCP server. Every tool call is automatically logged with duration, payload sizes, memory usage, and request correlation — no instrumentation code needed. createApp() handles config parsing, logger init, transport startup, signal handlers, and graceful shutdown.

Features

• Declarative definitions — tool(), resource(), prompt() builders with Zod schemas. Framework handles registration, validation, and response formatting.
• Unified Context — handlers receive a single ctx object with ctx.log (request-scoped logging), ctx.state (tenant-scoped storage), ctx.elicit (user prompting), ctx.sample (LLM completion), and ctx.signal (cancellation).
• Inline auth — auth: ['scope'] on definitions. No wrapper functions. Framework checks scopes before calling your handler.
• Task tools — task: true flag for long-running operations. Framework manages the full lifecycle (create, poll, progress, complete/fail/cancel).
• Structured error handling — Handlers throw freely; the framework catches, classifies, and formats. Error fac...