MCP 采样服务器
一个模型上下文协议（MCP）服务器，用于展示 采样特征 在TypeScript中。此服务器展示了MCP服务器如何从连接的客户端请求大型语言模型（LLM）补全，从而实现智能体行为，而无需服务器端的API密钥。
什么是MCP采样？
在MCP（多客户端协议）中，服务器可以请求客户端生成大型语言模型（LLM）的输出。这实现了：
- 服务器端智能 没有API密钥
- 客户端控制的模型访问 以及权限
- 灵活的模型选择 基于客户能力
- 代理工作流 工具可以利用大型语言模型（LLM）的能力
特点/功能
这台服务器实现了七个工具和四个资源，用于展示采样、引出、根部（或解）以及资源相关内容：
采样示例
- 📝 文本总结使用大型语言模型（LLM）采样总结任意文本
- 💭 情绪分析分析文本情感并给出置信度评分
- 📚 生成故事根据提示创作创意故事
- ❓ 提问根据可选上下文回答问题
引出示例
- 👤 创建用户资料通过抽样收集缺失信息的交互式个人资料创建
- 📋 产品评价向导基于用户回答的多步骤调查，包含条件性问题
根部整合
- 🗂️ 分析工作区通过请求客户端的工作区根目录并使用抽样技术来提供智能分析和建议，演示了根目录功能
先决条件
- Node.js 18 或更高版本
- npm 或 yarn 包管理器
安装
- 克隆或导航到项目目录：
cd MCP-Sampling- 安装依赖项：
npm install运行服务器
开发模式（带热重载）
npm run dev生产模式
# Build the TypeScript code
npm run build
# Run the compiled JavaScript
npm start服务器将在 http://localhost:3000/mcp
测试服务器
使用MCP Inspector
测试您服务器的最简单方法是使用MCP Inspector：
npx @modelcontextprotocol/inspector http://localhost:3000/mcp使用Claude桌面版
注： 客户端必须支持 sampling 这些工具的工作能力。
添加到您的Claude桌面配置中（~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：
{
"mcpServers": {
"sampling-demo": {
"url": "http://localhost:3000/mcp"
}
}
}使用 Claude Code CLI
claude mcp add --transport http sampling-demo http://localhost:3000/mcp示例用法
一旦连接到客户端，您可以尝试：
文本摘要
Use the summarize-text tool to summarize this article: [paste long text]情感分析
Analyze the sentiment of this review: "The product exceeded my expectations!"故事生成
Generate a short story about a robot learning to paint问题回答
Ask a question: What are the benefits of using the Model Context Protocol?交互式个人资料创建（信息提取）
Create a user profile
(The tool will use sampling to request missing information like name, age, occupation, and interests)产品评论向导（多步骤引导）
Start a product review
(The wizard will guide you through multiple steps: product selection, rating, feedback, and conditional follow-up questions)工作区分析（根特征）
Use the analyze-workspace tool
(The tool will request roots from the client, analyze your workspace structure, and provide intelligent recommendations)利用资源
Access resources through your MCP client:
- mcp://server/info - View server information
- mcp://samples/1 - Read sample data by ID (1, 2, or 3)
- mcp://snippets/positive - Access text snippets by category
- mcp://analyzed/review1 - Get AI-analyzed text samples采样工作原理
当调用一个工具时：
- 工具接收输入 来自客户端（例如，需要总结的文本）
- 服务器创建一个采样请求 使用
mcpServer.server.createMessage() - 客户端收到请求 并可能向用户展示以供批准
- 客户端执行大型语言模型（LLM）调用 使用其配置的模型
- 响应被发送回去 到服务器
- 服务器处理并返回 将结果呈现给客户
如何进行引出（或诱导）
引出（或诱发） 这是通过与用户交互来收集缺失信息的过程。该实现展示了两种方法：
单步引出（或单步触发）create-user-profile）
当缺少必填字段时，该工具会通过抽样一次性请求所有缺失的信息：
- 检测哪些必填字段未提供
- 用途
createMessage()要求大型语言模型（LLM）提示用户提供缺失的数据 - 解析响应以提取提供的信息
- 将提取的数据与最初提供的任何值相结合
- 再次使用采样技术生成个性化摘要
多步骤引出法（或：多步骤诱发法）product-review-wizard)
实现了带有条件问题的引导式向导模式：
- 逐步流程每次通话都会按照预定义的步骤进行（开始 → 评分 → 反馈 → 完成）
- 条件逻辑低评分引发了更多关于改进的疑问
- 状态追踪该工具在多次调用之间保持调查状态
- 情感分析使用抽样来分析最终反馈
这两种方法都展示了MCP服务器如何通过利用采样能力来创建互动式的对话体验。
📖 代表“书籍”或“阅读”（根据上下文，可能具体翻译为“书本”或“阅读材料”等）。 有关详细示例和使用模式，请参阅 \ELICITATION_EXAMPLES.md\ 翻译成中文是：“引出（或提示）示例.md” 或 “诱导性示例.md”（具体翻译可能根据上下文有所调整，但核心意思是文件名表示的是用于引出或提示某些内容的示例）。在实际应用中，\md\ 是 Markdown 文本格式的缩写，所以这个文件名可能表示的是一个包含诱导性或提示性示例的 Markdown 文件
资源的工作原理
资源 在MCP（可能是指某种中间件或计算平台）中，数据可以暴露给大型语言模型（LLMs）而无需进行大量计算或产生副作用。与工具（由模型控制）不同，资源是由应用程序驱动的，这意味着MCP客户端决定如何暴露这些资源。
此服务器实现了四种类型的资源：
- 静态资源 (
mcp://server/info): 服务器元数据和配置 - 动态资源 (
mcp://samples/{id}): 基于URI参数提供数据 - 分类内容 (
mcp://snippets/{category}): 预定义的文本片段 - 增强型人工智能资源 (
mcp://analyzed/{textId}): 利用采样进行智能数据访问的资源
关键能力：
- 📦 无副作用地暴露结构化数据
- 🔗 使用URI模板处理动态内容
- 🎯 结合采样以增强数据的人工智能能力
- 📝 支持多种MIME类型（JSON、文本、Markdown）
- 🔄 应用程序控制的访问模式
📖（一本书） 如需完整的实施细节，请参阅 “RESOURCES_IMPLEMENTATION.md”翻译成中文是：“资源实施说明.md”
Roots Integration的工作原理
这台服务器实现了 根特征 以展示对工作空间的认知功能。该 analyze-workspace 工具：
- 请求根权限 来自客户端的使用
roots/list - 处理得当，应对自如 当根部得不到支撑时
- 与采样相结合 分析工作空间结构
- 生成智能见解 关于工作空间的组织
- 提供建议 基于工作区结构
关键能力：
- 🗂️ 发现可用的工作空间目录
- 🧠 利用人工智能分析项目结构
- 💡 提供情境感知的推荐
- 🔒 展示了适当的安全边界
- 🔄 有效整合多种MCP功能
📖（这个符号本身没有直接的中文翻译，它通常代表“书”或“书籍”的意思，在中文语境中可以理解为“书本”或“书籍”的图标或简写） 如需完整的实施细节，请参阅 ROOTS_IMPLEMENTATION.md 翻译为中文是：“ROOTS 实现说明.md” 或 “ROOTS 实施方案.md”（具体翻译可能根据上下文有所调整，但“.md”通常表示Markdown格式的文件，这里未直接翻译）
示例代码
const response = await mcpServer.server.createMessage({
messages: [
{
role: 'user',
content: {
type: 'text',
text: 'Please summarize: ' + text
}
}
],
maxTokens: 500,
modelPreferences: {
hints: [{ name: 'claude-3-sonnet' }],
intelligencePriority: 0.8,
speedPriority: 0.5,
costPriority: 0.3
}
});模型偏好
服务器使用模型偏好来指导客户端模型的选择：
- 提示建议具体型号（例如。，
claude-3-sonnet） - 智能优先 (0-1)：先进能力有多重要？
- 速度优先 (0-1): 低延迟有多重要？
- 成本优先 (0-1): 成本最小化有多重要？
客户可以自由地将这些偏好映射到他们可用的模型上。
项目结构
MCP-Sampling/
├── src/
│ └── index.ts # Main server implementation
├── dist/ # Compiled JavaScript (after build)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .gitignore # Git ignore rules
├── README.md # Main documentation
├── ELICITATION_EXAMPLES.md # Elicitation feature examples
└── ROOTS_IMPLEMENTATION.md # Roots feature implementation guide关键概念
MCP中的资源
资源 以结构化的方式将数据暴露给大型语言模型（LLMs），且不涉及计算或产生副作用。它们与工具从根本上不同：
- 工具 受模型控制并能采取行动
- 资源 受应用程序控制，提供只读数据
资源类型：
- 静态资源固定数据，如配置或文档
- 动态资源使用URI模板进行参数化数据
- 增强型AI资源结合资源与抽样实现智能数据访问
示例：
mcpServer.registerResource(
'sample-data',
new ResourceTemplate('mcp://samples/{id}', { list: undefined }),
{
title: 'Sample Data',
description: 'Example data by ID'
},
async (uri, params) => {
const id = Array.isArray(params.id) ? params.id[0] : params.id;
return {
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify(data[id], null, 2)
}]
};
}
);安全考虑因素
- 人参与其中（或人机交互）客户端应要求用户批准采样请求
- 用户控制用户应该能够查看和编辑提示
- 限速（或速率限制）客户端应实施适当的速度限制
- 数据处理双方必须妥善处理敏感数据
客户需求
为了使采样有效，客户必须：
- 声明
sampling初始化期间的能力 - 处理
sampling/createMessage请求： - 实施用户审批流程（推荐）
- 返回格式正确的响应
故障排除
服务器无法启动
- 确保已安装 Node.js 18 或更高版本：
node --version - 检查端口3000是否可用：
lsof -i :3000(macOS/Linux) - 安装依赖项：
npm install
工具无法正常工作
- 验证客户端是否支持
sampling能力 - 检查服务器日志中的错误
- 确保客户端已配置模型访问权限和API密钥
采样请求失败
- 客户必须批准采样请求（请查看客户界面）
- 验证客户端已配置LLM访问权限
- 检查客户端与服务器之间的网络连接
在MCP中的根源
什么是Roots？
根 在MCP（可能指某种管理或控制平台）中，为客户端提供了一种标准化的方式，以将文件系统位置暴露给服务器。它们定义了服务器在文件系统中可操作的范围边界，建立了明确的访问控制和工作区上下文。
关键概念
- 工作区边界根目录决定了服务器可以访问哪些目录和文件
- 客户端控制客户端向服务器暴露根目录，同时保持安全性和用户控制权
- 动态更新客户端可以在根列表发生变化时通知服务器
- 多重根支持多个项目目录、存储库或工作区
根是如何工作的
- 客户端声明具备根权限能力 在初始化期间
- 服务器请求根权限 使用
roots/list方法 - 客户端返回可访问的位置 （例如，项目目录）
- 服务器遵守root边界限制 在所有操作中
- 客户通知变更 当添加/移除根时
根系结构
每个根目录包括：
- uri（此处作为专有名词或特定术语，无直接中文对应，可保持原样或根据上下文具体含义翻译，如“URI”常译为“统一资源标识符”）唯一标识符（必须是
file://URI（统一资源标识符） - 名字可选的人类可读名称，用于显示
示例根目录：
{
"uri": "file:///home/user/projects/myproject",
"name": "My Project"
}协议消息
列出根目录（服务器 → 客户端）
{
"jsonrpc": "2.0",
"id": 1,
"method": "roots/list"
}响应（客户端 → 服务器）
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"roots": [
{
"uri": "file:///home/user/projects/frontend",
"name": "Frontend Repository"
},
{
"uri": "file:///home/user/projects/backend",
"name": "Backend Repository"
}
]
}
}根列表更改通知（客户端 → 服务器）
{
"jsonrpc": "2.0",
"method": "notifications/roots/list_changed"
}客户端功能
支持根节点的客户端在初始化时声明其能力：
{
"capabilities": {
"roots": {
"listChanged": true
}
}
}listChanged 指示客户端在根节点变化时是否会发出通知。
安全考虑事项
客户必须：
- 仅暴露具有适当权限的根（或：仅暴露经适当授权的根）
- 验证所有根URI，以防止路径遍历攻击
- 实施适当的访问控制
- 在暴露根目录前提示用户获取同意
- 监控root访问权限
服务器应当：
- 在请求之前检查是否具备root权限
- 处理根目录不可用的情况
- 在所有操作中尊重根边界
- 验证所有路径是否符合提供的根路径
- 优雅地处理根列表的更改
用例
- 项目工作区公开项目目录以启用上下文感知操作
- 多仓库开发在多个相关存储库之间工作
- 沙盒操作限制服务器访问特定目录
- 版本控制集成自动检测并暴露版本控制系统根目录
- 单仓库支持在单体仓库结构中暴露多个包
在本服务器上的实施
这个服务器实现了根目录功能 analyze-workspace 工具，其展示了：
- 从客户端请求根证书：
const rootsResponse = await mcpServer.server.request(
{ method: 'roots/list', params: {} },
z.object({
roots: z.array(z.object({
uri: z.string(),
name: z.string().optional()
}))
})
);- 存储和使用根信息：
if (rootsResponse && rootsResponse.roots) {
clientRoots = rootsResponse.roots;
}- 结合根与抽样：
- 该工具从客户端请求工作区根目录 - 使用大型语言模型（LLM）采样来分析工作空间结构 - 基于根本原因生成智能建议 - 提供对工作区的情境感知见解
- 在根目录不受支持时的优雅处理：
if (clientRoots.length === 0) {
return {
content: [{
type: 'text',
text: 'No roots available. The client may not support the roots capability.'
}]
};
}这展示了服务器如何结合多个MCP特性（根目录+采样）来提供复杂且具备上下文感知功能的功能。
使用根部的好处
- 🔒（锁形符号，常用于表示安全、保密或锁定状态） 增强安全性服务器操作的明确界限
- 🎯（靶心，意指精准的目标或焦点） 情境感知服务器了解其工作环境的上下文
- 🔄 翻译为中文是：循环/旋转（符号本身常用来表示循环、重复或旋转的动作） 动态更新适应不断变化的项目结构
- 👥 表示“人们”或“人群”。 用户控制用户明确授予文件系统访问权限
- 🏗️（建筑工地或施工的符号，无具体文字对应，可理解为“建筑”或“施工”的意象） 多项目支持同时跨多个项目开展工作
了解更多
许可证
MIT 许可证 - 详见 LICENSE 文件
贡献；做出贡献
欢迎贡献！这是一个演示项目，旨在帮助开发者了解MCP采样。
______________________________________________________________________
使用模型上下文协议，用心打造