MCP TypeScript Starter

MCP TypeScript 入门模板

一个功能完备的 TypeScript Model Context Protocol（MCP）服务模板。此入门模板以简洁、可用于生产环境的代码演示了 MCP 的所有主要功能。

📚 文档

• Model Context Protocol
• TypeScript SDK
• 构建 MCP 服务

✨ 功能

类别	功能	说明
工具	hello	带注解的基础工具
	get_weather	带结构化输出架构的工具
	ask_llm	调用 LLM 采样的工具
	long_task	每 5 秒更新一次进度的工具
	load_bonus_tool	动态加载新工具
资源	info://about	静态信息资源
	file://example.md	基于文件的 Markdown 资源
模板	greeting://{name}	个性化问候语
	data://items/{id}	按 ID 查找数据
提示词	greet	多种风格的问候语
	code_review	聚焦特定方面的代码审查

🚀 快速开始

前置条件

• Node.js 20+
• npm 或 pnpm

安装

# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-typescript-starter.git
cd mcp-typescript-starter

# Install dependencies
npm install

# Build
npm run build

运行服务

stdio 传输（用于本地开发）：

npm run start:stdio

HTTP 传输（用于远程／Web 部署）：

npm run start:http
# Server runs on http://localhost:3000

🔧 VS Code 集成

此项目包含 VS Code 配置，可实现流畅开发：

1. 在 VS Code 中打开项目
2. MCP 配置位于 .vscode/mcp.json
3. 使用 Ctrl+Shift+B（Mac 上使用 Cmd+Shift+B）进行构建
4. 使用 VS Code 的 MCP 工具测试服务

使用 DevContainers

1. 安装 Dev Containers 扩展
2. 打开命令面板：选择“Dev Containers: Reopen in Container”
3. 所有内容都已预先配置完毕，可直接使用！

📁 项目结构

.
├── src/
│   ├── tools.ts       # Tool definitions (hello, get_weather, ask_llm, etc.)
│   ├── resources.ts   # Resource and template definitions
│   ├── prompts.ts     # Prompt definitions
│   ├── server.ts      # Server orchestration (combines all modules)
│   ├── stdio.ts       # stdio transport entrypoint
│   └── http.ts        # HTTP transport entrypoint
├── .vscode/
│   ├── mcp.json       # MCP server configuration
│   ├── tasks.json     # Build/run tasks
│   └── extensions.json
├── .devcontainer/
│   └── devcontainer.json
├── package.json
├── tsconfig.json
├── .prettierrc        # Prettier configuration
└── eslint.config.js

🛠️ 开发

# Development mode with live reload
npm run dev

# Build for production
npm run build

# Format code
npm run format

# Lint
npm run lint

# Clean build
npm run clean && npm run build

实时重新加载

npm run dev 命令使用 tsx watch，可在开发期间即时重新加载。 对任何 .ts 文件的更改都会自动重启服务。

🔍 MCP Inspector

MCP Inspector 是用于测试和调试 MCP 服务的重要开发工具。

运行 Inspector

npx @modelcontextprotocol/inspector -- npx tsx src/stdio.ts

Inspector 提供的功能

• 工具选项卡：列出所有已注册工具及其参数，并可调用这些工具
• 资源选项卡：浏览和读取资源及模板
• 提示词选项卡：查看并测试提示词模板
• 日志选项卡：查看客户端与服务之间的 JSON-RPC 消息
• 架构验证：验证工具输入／输出架构

调试提示

1. 在连接 IDE／客户端之前启动 Inspector
2. 使用“Logs”选项卡查看准确的请求／响应载荷
3. 测试工具注解是否正确公开
4. 确认 long_task 的进度通知是否出现

📖 功能示例

带注解的工具

server.tool(
  "hello",
  {
    title: "Say Hello",
    description: "A friendly greeting tool",
    annotations: { readOnlyHint: true },
  },
  { name: z.string() },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
  })
);

资源模板

server.resourceTemplate(
  "greeting://{name}",
  { name: "Personalized Greeting", mimeType: "text/plain" },
  async ({ name }) => ({
    contents: [{
      uri: `greeting://${name}`,
      text: `Hello, ${name}!`,
    }],
  })
);

带进度更新的工具

server.tool(
  "long_task",
  { title: "Long Task" },
  { taskName: z.string() },
  async ({ taskName }, { sendProgress }) => {
    for (let i = 0; i < 5; i++) {
      await sendProgress({ progress: i / 5, total: 1.0 });
      await sleep(1000);
    }
    return { content: [{ type: "text", text: "Done!" }] };
  }
);

🔐 环境变量

将 .env.example 复制为 .env 并进行配置：

cp .env.example .env

变量	说明	默认值
PORT	HTTP 服务端口	3000

🤝 参与贡献

欢迎贡献！请确保你的更改与其他语言入门项目保持功能一致。

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE。