使用TypeScript SDK构建MCP服务器——简短教程
本教程解释了什么是模型上下文协议（MCP）服务器，使其有用的核心概念（资源、工具、提示、采样），以及如何在此仓库中运行和检查示例TypeScript服务器。
清单
- 解释什么是MCP服务器及其用途
- 描述四个核心部分（资源、工具、提示、采样）
- 分解存储库并
src/server.ts（组件已注册） - 演示如何在本地运行服务器，连接MCP检查器，并使用
.vscode/mcp.json设置
什么是MCP服务器？
MCP服务器公开了一个结构化的HTTP/JSON表面，模型（或模型驱动代理）可以使用它来：读取和更新应用程序资源（数据），调用编程工具（操作），并按照具有指定采样设置的提示/指令进行操作。服务器声明模型可以访问的资源和工具，提供调用模型时使用的提示模板和采样配置，并可选择记录跟踪以供检查和调试。
为什么使用MCP？
- 使模型交互可审计和可调试。
- 保持模型可访问的数据和操作明确且类型化。
- 将域代码（资源/工具）与模型提示和采样分开。
核心部件
- 资源
- 内容：结构化数据端点（例如，用户、文档、票证）。 - 角色：让模型以可预测的方式查询和修改应用程序状态。 - 实现说明：资源通常实现读取/列表/创建/更新处理程序，并连接到持久存储（示例中为JSON文件或DB）。
- 工具
- What：模型可以使用结构化输入调用命名函数并接收结构化输出。 - 角色：执行模型不能直接执行的操作（发送电子邮件、调用外部API、运行计算），同时保持其安全性和可审计性。
- 提示/指示
- 内容：指导模型行为的模板或指令字符串（何时调用工具，如何格式化输出）。 - 作用：塑造决策和输出格式；经常注入资源快照或最近的上下文。
- 采样/调用配置
- 内容：模型调用参数（温度、最大令牌、top_p、停止序列）。 - 角色：控制模型的随机性、响应长度和确定性。
存储库布局（打开什么）
src/server.ts--主TypeScript注册文件。这是声明资源、工具、提示和采样以及启动HTTP服务器的地方。build/server.js--编译输出（如果您运行TypeScript构建）。src/data/users.json和build/data/users.json--样本使用的示例资源数据users资源。package.json和tsconfig.json--构建和运行时脚本/config。
高级演练： src/server.ts
以下是您将在中找到的概念性作品 src/server.ts。实际的变量和函数名称可能不同，但映射是相同的。
资源（例如： users)
- 声明：注册名为的资源的调用
users并为CRUD操作提供处理程序。 - 寻找什么：a
registerResource或server.resource('users', {...})调用，读/写处理程序src/data/users.json，以及任何验证代码。 - 为什么重要：模型将查询此资源以获取有关用户的事实，并通过资源契约请求突变，而不是进行任意更改。
工具（示例： sendEmail 或 lookupProfile)
- 声明：a
registerTool或server.tool('name', handler)公开模型可以调用的函数的调用。 - 要查找的内容：输入形状（类型/接口）、处理程序主体、错误处理以及工具是否记录请求而不是执行副作用（建议开发人员使用）。
- 为什么重要：工具是从意图到行动的安全桥梁——使它们明确且可测试。
提示/指示
- 声明：注册为服务器提示符的字符串或模板（通常命名为
default或assistant)，有时为资源快照使用占位符变量。 - 要查找的内容：模板文本、注入的变量以及服务器在模型调用之前如何构建提示。
- 为什么重要：提示指示模型是应该调用工具、更新资源还是直接返回文本。
采样/型号选项
- 声明：设置的对象或调用
temperature,max_tokens,top_p以及类似的参数。 - 寻找什么：a
sampling或invokeOptions对象传递给SDK的模型调用。 - 重要原因：当您期望模型精确选择动作时，较小的温度值（0-0.3）有助于确定性。
如何构建和运行服务器
安装依赖项：
npm install构建（编译TypeScript）：
npm run build # assumes package.json has a build script that runs tsc运行已编译的服务器：
node build/server.js快速开发模式（直接运行TypeScript）：
npm run dev # recommended to map to ts-node src/server.ts or nodemon公用端口：检查 src/server.ts 对于实际的侦听端口（通常 3000).
使用MCP检查器
- 启动服务器（请参阅上面的命令）。
- 打开MCP检查器UI。
- 连接到服务器URL（例如
http://localhost:3000).
检查器应显示已注册的资源、可用工具及其输入形状、提示模板、采样设置和最近的调用跟踪。使用检查器运行示例调用，并观察模型如何与资源和工具交互。
VS代码集成： .vscode/mcp.json
你可以添加一个小 .vscode/mcp.json 文件定义MCP扩展可以理解的本地MCP运行配置。调整字段以匹配您的 package.json 脚本和端口。
示例 .vscode/mcp.json:
{
"name": "local-mcp",
"command": "npm run dev",
"cwd": "${workspaceFolder}",
"port": 3000,
"inspect": true,
"env": { "NODE_ENV": "development" }
}笔记：
- 集
command启动开发服务器的脚本（例如dev运行的脚本ts-node src/server.ts). - 使用
port告诉IDE/检查器服务器在哪里可用。
服务器组件示例以及代码中要检查的内容
- 用户资源
- 在代码中可以期待什么：像这样的注册 server.resource('users', { list, read, create, update }) 或类似。处理程序将进行读写操作 src/data/users.json 并执行基本验证。 - 开发人员提示：使用乐观锁定或简单验证来保护演示服务器的并发写入安全。
- sendEmail工具（或同等工具）
- 期待什么：a server.tool('sendEmail', async (args) => { ... }) 注册。处理程序可能会记录电子邮件，而不是在开发过程中发送。 - 开发人员提示：在开发中模拟外部API并记录意图，而不是发送真实消息。
- 提示模板
- 预期内容：包含指令模板和资源快照注入点的常量或注册。 - 开发人员提示：在向提示中注入时，对长资源字段进行清理和截断。
- 采样选项
- 预期：一个物体，例如 { temperature: 0.2, max_tokens: 512 } 调用模型SDK时使用。 - 开发者提示：对于动作驱动的流，从低温开始。
安全和最佳实践
- 在开发中保持工具的约束性、幂等性和安全性。
- 验证服务器端的所有输入——不要相信模型输出是格式正确的。
- 使用低温进行确定性控制流。
- 记录跟踪，并使用检查器回放或逐步执行模型决策。
快速参考命令
npm install
npm run build
node build/server.js
# or during development
npm run dev