# mcp-ts-core — TypeScript Framework for MCP Servers
> Build MCP servers in TypeScript with declarative tool/resource schemas, auth, storage backends, and OpenTelemetry. Includes a Bun-powered scaffold command.
## Install
Merge the JSON below into your `.mcp.json`:
## Quick Use
```bash
bunx @cyanheads/mcp-ts-core init my-mcp-server
cd my-mcp-server
bun install
```
## Intro
mcp-ts-core is an infrastructure layer you install as a dependency to build MCP servers, so you focus on domain tools while the framework handles transports, auth, telemetry, and lifecycle.
**Best for:** Teams building multiple MCP servers with consistent auth/telemetry patterns
**Works with:** Bun or Node; TypeScript; MCP clients; OpenTelemetry integration
**Setup time:** 15–30 minutes
### Key facts (verified)
- README badges list version 0.9.0 and TypeScript ^6.0.3.
- Quick start is a single scaffold command: `bunx ... init` (README).
- GitHub: 138 stars · 24 forks; pushed 2026-05-11 (GitHub API verified).
## Main
Use this framework to standardize “how tools fail”:
- Keep tool schemas strict (Zod) and define recovery hints for expected failures.
- Emit telemetry by default so you can answer: which tools are slow, which inputs are large, where errors cluster.
- Treat the scaffolded `CLAUDE.md` / agent skills as the shared operating system for contributors.
### README excerpt (verbatim)
@cyanheads/mcp-ts-core
Agent-native TypeScript framework for building MCP servers. Build tools, not infrastructure. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.
[](./CHANGELOG.md) [](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [](https://modelcontextprotocol.io/) [](./LICENSE)
[](https://www.typescriptlang.org/) [](https://bun.sh/)
---
## What is this?
`@cyanheads/mcp-ts-core` is the infrastructure layer for TypeScript MCP servers. Install it as a dependency — don't fork it. Your agent collaborates with you to design and build the tools, resources, and prompts for your server.
The framework handles the plumbing: transports, auth, config, logging, telemetry, & more. Define your domain logic with the builders and let the framework take care of the rest.
```ts
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'),
}),
errors: [
{
reason: 'name_blocked',
code: JsonRpcErrorCode.Forbidden,
when: 'The provided name is on the configured block list.',
recovery: 'Use a different name.',
},
],
handler: async (input, ctx) => {
if (isBlocked(input.name)) throw ctx.fail('name_blocked', `"${input.name}" is blocked`);
return { message: `Hello, ${input.name}!` };
},
});
await createApp({ tools: [greet] });
```
### FAQ
**Q: Should I fork the repo?**
A: README suggests installing as a dependency rather than forking.
**Q: What runtime is preferred?**
A: README highlights first-class Bun support; Node is also supported.
**Q: What’s the main benefit?**
A: It handles transports/auth/telemetry so your server code stays domain-focused.
## Source & Thanks
> Source: https://github.com/cyanheads/mcp-ts-core
> License: Apache-2.0
> GitHub stars: 138 · forks: 24
---
## 快速使用
```bash
bunx @cyanheads/mcp-ts-core init my-mcp-server
cd my-mcp-server
bun install
```
## 简介
mcp-ts-core 是可作为依赖安装的 MCP server 基础设施层：你专注于领域工具，框架负责传输、鉴权、遥测与生命周期管理。
**最适合：** 需要统一鉴权/可观测性的多 MCP server 团队
**适配：** Bun 或 Node；TypeScript；MCP 客户端；支持 OpenTelemetry
**配置时间：** 15–30 分钟
### 关键事实（已验证）
- README Badge 显示版本 0.9.0 与 TypeScript ^6.0.3。
- 快速开始是一条脚手架命令：`bunx ... init`（README）。
- GitHub：138 stars · 24 forks；最近更新 2026-05-11（GitHub API 验证）。
## 正文
用它来把“工具怎么失败”标准化：
- schema 严格一些（Zod），为可预期失败定义清晰的恢复提示。
- 默认开启遥测，才能回答：哪些工具慢、输入/输出多大、错误集中在哪些场景。
- 把脚手架生成的 `CLAUDE.md` / agent skills 当作协作的共同操作系统来维护。
### README 原文节选（verbatim）
@cyanheads/mcp-ts-core
Agent-native TypeScript framework for building MCP servers. Build tools, not infrastructure. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.
[](./CHANGELOG.md) [](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [](https://modelcontextprotocol.io/) [](./LICENSE)
[](https://www.typescriptlang.org/) [](https://bun.sh/)
---
## What is this?
`@cyanheads/mcp-ts-core` is the infrastructure layer for TypeScript MCP servers. Install it as a dependency — don't fork it. Your agent collaborates with you to design and build the tools, resources, and prompts for your server.
The framework handles the plumbing: transports, auth, config, logging, telemetry, & more. Define your domain logic with the builders and let the framework take care of the rest.
```ts
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'),
}),
errors: [
{
reason: 'name_blocked',
code: JsonRpcErrorCode.Forbidden,
when: 'The provided name is on the configured block list.',
recovery: 'Use a different name.',
},
],
handler: async (input, ctx) => {
if (isBlocked(input.name)) throw ctx.fail('name_blocked', `"${input.name}" is blocked`);
return { message: `Hello, ${input.name}!` };
},
});
await createApp({ tools: [greet] });
```
### FAQ
**需要 fork 吗？**
答：README 建议直接作为依赖安装，不要 fork。
**推荐用什么运行时？**
答：README 强调对 Bun 的一等支持；也支持 Node。
**核心收益是什么？**
答：框架处理传输/鉴权/遥测，让你的代码更聚焦业务工具。
## 来源与感谢
> Source: https://github.com/cyanheads/mcp-ts-core
> License: Apache-2.0
> GitHub stars: 138 · forks: 24
---
Source: https://tokrepo.com/en/workflows/mcp-ts-core-typescript-framework-for-mcp-servers
Author: MCP Hub