mcp-ts-core: Instructions file for Codex

Developer Protocol

Package: @cyanheads/mcp-ts-core Version: 0.12.5 Engines: Bun ≥1.3.0, Node ≥24.0.0 MCP SDK: @modelcontextprotocol/server ^2.0.0 (protocol revisions 2026-07-28 and 2025-*) Zod: ^4.5.4 GitHub: cyanheads/mcp-ts-core npm: @cyanheads/mcp-ts-core Docker: ghcr.io/cyanheads/mcp-ts-core

Developer note: Never assume. Read related files and docs before making changes. Read full file content for context. Never try to edit a file before reading it.

---

Consumers

This package serves two consumer paths. When making changes, know which audience your change affects:

Path	On-ramp	Affected by changes to
Direct package import — existing project pulls in the package	bun add @cyanheads/mcp-ts-core → import { createApp, tool, z } from '@cyanheads/mcp-ts-core'	Public API surface (src/) — existing consumers feel changes immediately on upgrade
Init-scaffolded server — fresh project bootstrapped from this repo's templates	bunx @cyanheads/mcp-ts-core init [name] copies templates/ into the new directory	templates/ — only affects newly scaffolded servers, not existing ones

Both paths share the same public API. Init copies starter package.json, configs (tsconfig, biome.json, vitest.config.ts, devcheck.config.json, bunfig.toml), .env.example, Dockerfile, LICENSE, .gitattributes, CLAUDE.md/AGENTS.md, .github/ (issue forms, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md), example definitions and tests, framework scripts/, and external-audience skills/. _-prefixed files (e.g. _.gitignore) drop the prefix on copy. Existing files are never overwritten; init without a name scaffolds in place (upgrade flow). After init, consult the setup skill.

---

Core Rules

• Logic throws, framework catches. Pure, stateless handler functions, no try/catch. Plain Error works — framework catches, classifies, formats. Use McpError(code, message, data, options?) only when you need a specific JSON-RPC code or structured data; 4th arg { cause } chains.
• Full-stack observability. The framework automatically instruments every tool/resource call — OTel span, duration/payload/memory metrics, structured completion log. Use ctx.log for additional domain-specific logging within handlers (external API calls, multi-step operations, business events). requestId, traceId, tenantId auto-correlated. No console calls.
• Unified Context. Handlers receive ctx with logging (ctx.log), tenant-scoped storage (ctx.state), multi-round-trip input (ctx.requestInput / ctx.inputs), and cancellation (ctx.signal). Context extends RequestContext, so ctx goes straight into any service, storage, or logger call.
• Decoupled storage. ctx.state for tenant-scoped KV. Never access persistence backends directly.
• Canvas tokens are capabilities, not tenant-scoped state. A canvasId is a 10-char URL-safe token; possession grants full read/write/drop. Shareable between agents and across users in single-tenant deployments. Tools accept token in input (omit to create fresh) and return in output; collaboration is opt-in via token exchange.
• Runtime parity. All features work across stdio/http/Worker. Guard non-portable deps via runtimeCaps from /utils (isNode, isBun, isWorkerLike, hasBuffer, hasProcess, etc.). Prefer runtime-agnostic abstractions (Hono, Fetch APIs).
• Definition linting is build-time only. Run bun run lint:mcp (standalone) or bun run devcheck (gate). Not invoked at server startup — new lint rules are additive and never break deployed servers. Every diagnostic links to the rule reference in api-linter skill; see that skill for the full rule catalog.
• Ask for missing input by returning, not awaiting. return ctx.requestInput({ inputRequests: … }) suspends the handler; it is re-entered with ctx.inputs populated. One handler serves both protocol eras.
• Close the loop on issues. When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.