model-context-builder

Name: model-context-builder
Author: bobmatnyc

github.com/bobmatnyc测试与质量78135 次安装15 周前更新

代码仓库

关于 model-context-builder

model-context-builder 是用于设计评测的技能，通过复杂、真实的问题检验 LLM 使用 MCP 服务工具作答的能力。它指导问题与答案设计、只读内容检查，以及稳定且可验证的输出。

主要功能

01设计十道评测问题
02要求独立的只读操作
03构建多步骤工具任务
04设定稳定可验证的答案
05检查服务工具与内容

适用场景

01评估 MCP 服务工具的可用性
02构建可重复的 LLM 评测集
03测试多步骤信息检索

MCP 相关

它通过检验 LLM 是否能仅使用 MCP 服务的工具回答问题，指导对 MCP 服务进行评测。它本身不提供 MCP 服务或客户端。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bobmatnyc/claude-mpm-skills --skill model-context-builder

安装后在 Claude Code 中输入/model-context-builder确认已加载。

附带文件metadata.json

详细介绍

MCP 服务评估指南

概述

本文档提供了创建全面的 MCP 服务评估的指导。评估用于测试 LLM 是否能仅使用所提供的工具，通过 MCP 服务有效回答贴近实际且复杂的问题。

快速参考

评估要求

创建 10 个易于理解的问题
问题必须是只读、独立且非破坏性的
每个问题都需要多次工具调用（可能多达数十次）
答案必须是单一且可验证的值
答案必须保持稳定（不会随时间变化）

输出格式

<evaluation>
   <qa_pair>
      <question>Your question here</question>
      <answer>Single verifiable answer</answer>
   </qa_pair>
</evaluation>

评估目的

衡量 MCP 服务质量的标准不是服务实现工具的完善程度或全面程度，而是这些实现（输入／输出架构、文档字符串／说明、功能）能否让没有其他上下文、只能访问 MCP 服务的 LLM 回答贴近实际且难度较高的问题。

评估概述

创建 10 个易于理解的问题，回答时只需执行只读、独立、非破坏性且幂等的操作。每个问题都应当：

贴近实际
清晰简洁
含义明确
复杂，需要调用可能多达数十次工具或执行多个步骤
能通过一个可验证的值回答，并且该值需预先确定

问题指南

核心要求

问题必须相互独立
- 每个问题都不应依赖其他任何问题的答案
- 不应假设处理其他问题时进行过写入操作
问题必须只需使用非破坏性且幂等的工具
- 不应指示或要求通过修改状态来得出正确答案
问题必须贴近实际、清晰、简洁且复杂
- 必须要求另一个 LLM 使用多个（可能多达数十个）工具或步骤来回答

复杂度与深度

问题必须要求深入探索
- 考虑需要多个子问题和连续工具调用的多跳问题
- 每个步骤都应能从前面的问题中获取的信息中受益
问题可能需要大量分页
- 可能需要翻阅多页结果
- 可能需要查询旧数据（过时 1 至 2 年的数据）来查找小众信息
- 问题必须有难度
问题必须要求深入理解
- 不能只考查表面知识
- 可以将复杂观点设计为需要证据支持的判断题
- 可以采用选择题格式，要求 LLM 搜索不同假设
问题不能通过简单的关键词搜索解决
- 不要包含目标内容中的特定关键词
- 使用同义词、相关概念或释义
- 要求执行多次搜索、分析多项相关内容、提取上下文，然后推导答案

工具测试

问题应对工具的返回值进行压力测试
- 可以让工具返回大量 JSON 对象或列表，使 LLM 不堪重负
- 应要求理解多种数据类型：
  - ID 和名称
  - 时间戳和日期时间（月、日、年、秒）
  - 文件 ID、名称、扩展名和 MIME 类型
  - URL、GID 等
- 应测试工具返回所有有用数据形式的能力
问题应主要反映真实的人类使用场景
- 即由 LLM 协助人类完成的信息检索任务
问题可能需要数十次工具调用
- 这会考验上下文有限的 LLM
- 促使 MCP 服务工具减少返回的信息量
加入含义模糊的问题
- 问题可以含义模糊，或要求对调用哪些工具作出艰难判断
- 迫使 LLM 可能犯错或误解
- 确保即使存在歧义，仍然有一个可验证的唯一答案

稳定性

问题必须设计成答案不会改变
- 不要提出依赖动态“当前状态”的问题
- 例如，不要统计：
  - 帖子的反应数量
  - 主题帖的回复数量
  - 频道中的成员数量
不要让 MCP 服务限制你创建的问题类型
- 创建有挑战性且复杂的问题
- 有些问题可能无法使用现有 MCP 服务工具解决
- 问题可能要求特定的输出格式（datetime 与 epoch time、JSON 与 MARKDOWN）
- 问题可能需要数十次工具调用才能完成

答案指南

验证

答案必须能通过直接字符串比较进行验证
- 如果答案可以用多种格式改写，请在问题中明确指定输出格式
- 示例：“使用 YYYY/MM/DD。”“回答 True 或 False。”“只回答 A、B、C 或 D。”
- 答案应是单个可验证的值，例如：
  - 用户 ID、用户名、显示名称、名字、姓氏
  - 频道 ID、频道名称
  - 消息 ID、字符串
  - URL、标题
  - 数值
  - 时间戳、datetime
  - 布尔值（用于 True 或 False 问题）
  - 电子邮件地址、电话号码
  - 文件 ID、文件名、文件扩展名
  - 选择题答案
- 答案将通过直接字符串比较进行验证

可读性

答案通常应优先采用人类可读的格式
- 示例：姓名、名字、姓氏、datetime、文件名、消息字符串、URL、是/否、true/false、a/b/c/d
- 而非难以理解的 ID（但 ID 也可以接受）
- 绝大多数答案应当是人类可读的

稳定性

答案必须稳定/固定
- 查看旧内容（例如，已结束的对话、已发布的项目、已回答的问题）
- 根据“已结束”的概念创建问题，使答案始终不变
- 可以要求考虑固定的时间范围，以隔离非稳定答案的影响
- 依赖不太可能改变的上下文
- 示例：查找论文名称时，要明确到足以避免与之后发表的论文混淆
答案必须明确且无歧义
- 问题必须设计成只有一个明确答案
- 答案可以通过使用 MCP 服务工具得出

多样性

答案必须多样化
- 答案应是不同类型和格式的单个可验证值
- 用户相关概念：用户 ID、用户名、显示名称、名字、姓氏、电子邮件地址、电话号码
- 频道相关概念：频道 ID、频道名称、频道主题
- 消息相关概念：消息 ID、消息字符串、时间戳、月份、日期、年份
答案不得是复杂结构
- 不能是值列表
- 不能是复杂对象
- 不能是 ID 或字符串列表
- 不能是自然语言文本
- 除非答案可以通过直接字符串比较轻松验证
- 且实际可复现
- 应尽量避免大模型以其他顺序或格式返回相同列表

评估流程

步骤 1：检查文档

阅读目标 API 的文档以了解：

可用的端点和功能
如果存在歧义，请从网上获取更多信息
尽可能多地并行执行此步骤
确保每个子 Agent 只检查文件系统或网上的文档

步骤 2：检查工具

列出 MCP 服务中可用的工具：

直接检查 MCP 服务
了解输入/输出架构、文档字符串和描述
此阶段不要调用工具

步骤 3：深入理解

重复步骤 1 和 2，直到充分理解：

多次迭代
考虑可以创建哪些类型的任务
不断完善理解
在任何阶段都不应阅读 MCP 服务实现本身的代码
运用直觉和理解，创建合理、真实且极具挑战性的任务

步骤 4：只读内容检查

了解 API 和工具后，使用 MCP 服务工具：

仅通过只读且非破坏性操作检查内容
目标：识别具体内容（例如用户、频道、消息、项目、任务），以便创建真实的问题
不应调用任何会修改状态的工具
不会阅读 MCP 服务实现本身的代码
将此步骤分配给各自独立探索的子 Agent，并行执行
确保每个子 Agent 仅执行只读、非破坏性且幂等的操作
务必注意：某些工具可能会返回大量数据，导致上下文耗尽
以增量方式进行小范围、有针对性的探索调用
在所有工具调用请求中，使用 limit 参数限制结果数量（<10）
使用分页

步骤 5：生成任务

检查内容后，创建 10 个便于阅读的问题：

大模型应能够通过 MCP 服务回答这些问题
遵循上述所有问题和答案指南

输出格式

每组问答包含一个问题和一个答案。输出应为具有以下结构的 XML 文件：

<evaluation>
   <qa_pair>
      <question>Find the project created in Q2 2024 with the highest number of completed tasks. What is the project name?</question>
      <answer>Website Redesign</answer>
   </qa_pair>
   <qa_pair>
      <question>Search for issues labeled as "bug" that were closed in March 2024. Which user closed the most issues? Provide their username.</question>
      <answer>sarah_dev</answer>
   </qa_pair>
   <qa_pair>
      <question>Look for pull requests that modified files in the /api directory and were merged between January 1 and January 31, 2024. How many different contributors worked on these PRs?</question>
      <answer>7</answer>
   </qa_pair>
   <qa_pair>
      <question>Find the repository with the most stars that was created before 2023. What is the repository name?</question>
      <answer>data-pipeline</answer>
   </qa_pair>
</evaluation>

评估示例

好问题

示例 1：需要深入探索的多跳问题（GitHub MCP）

<qa_pair>
   <question>Find the repository that was archived in Q3 2023 and had previously been the most forked project in the organization. What was the primary programming language used in that repository?</question>
   <answer>Python</answer>
</qa_pair>

这个问题很好，因为：

需要多次搜索才能找到已归档的仓库
需要确定其中哪个仓库在归档前拥有最多复刻
需要查看仓库详情以确认所用语言
答案简单且可验证
基于历史数据（已关闭），不会发生变化

示例 2：需要结合上下文而非匹配关键词（项目管理 MCP）

<qa_pair>
   <question>Locate the initiative focused on improving customer onboarding that was completed in late 2023. The project lead created a retrospective document after completion. What was the lead's role title at that time?</question>
   <answer>Product Manager</answer>
</qa_pair>

这个问题很好，因为：

未使用具体的项目名称（“旨在改善客户引导流程的计划”）
需要查找特定时间段内已完成的项目
需要确定项目负责人及其职责
需要理解回顾文档中的上下文
答案通俗易懂且稳定
基于已完成的工作（不会变化）

示例 3：需要多步处理的复杂聚合（问题跟踪器 MCP）

<qa_pair>
   <question>Among all bugs reported in January 2024 that were marked as critical priority, which assignee resolved the highest percentage of their assigned bugs within 48 hours? Provide the assignee's username.</question>
   <answer>alex_eng</answer>
</qa_pair>

这个问题很好，因为：

需要按日期、优先级和状态筛选 Bug
需要按受派人分组并计算解决率
需要理解时间戳，以确定 48 小时的时间窗口
考验分页处理能力（可能需要处理大量 Bug）
答案是单个用户名
基于特定时间段的历史数据

示例 4：需要综合多种数据类型（CRM MCP）

<qa_pair>
   <question>Find the account that upgraded from the Starter to Enterprise plan in Q4 2023 and had the highest annual contract value. What industry does this account operate in?</question>
   <answer>Healthcare</answer>
</qa_pair>

这个问题很好，因为：

需要理解订阅层级的变更
需要确定特定时间段内的升级事件
需要比较合同金额
必须访问账户的行业信息
答案简单且可验证
基于已完成的历史交易

较差的问题

示例 1：答案随时间变化

<qa_pair>
   <question>How many open issues are currently assigned to the engineering team?</question>
   <answer>47</answer>
</qa_pair>

这个问题较差，因为：

随着议题的创建、关闭或重新分配，答案会发生变化
不基于稳定的数据
依赖会动态变化的“当前状态”

示例 2：关键词搜索就能轻松解决

<qa_pair>
   <question>Find the pull request with title "Add authentication feature" and tell me who created it.</question>
   <answer>developer123</answer>
</qa_pair>

这个问题较差，因为：

通过直接搜索确切标题的关键词即可解决
不需要深入探索或理解
不需要综合或分析

示例 3：答案格式不明确

<qa_pair>
   <question>List all the repositories that have Python as their primary language.</question>
   <answer>repo1, repo2, repo3, data-pipeline, ml-tools</answer>
</qa_pair>

这个问题较差，因为：

答案是一个列表，顺序可以任意
难以通过直接字符串比较进行验证
大模型可能采用不同格式（JSON 数组、逗号分隔、换行分隔）
最好询问特定的汇总值（数量）或最高项（星标数最多）

验证流程

创建评估后：

检查 XML 文件，了解其架构
加载每项任务说明，并行使用 MCP 服务和工具，通过直接尝试完成任务来确定正确答案
标记任何需要 WRITE 或 DESTRUCTIVE 操作的操作
收集所有正确答案，并替换文档中的任何错误答案
移除任何需要 WRITE 或 DESTRUCTIVE 操作的 <qa_pair>

记住，并行解决任务以避免上下文耗尽，然后收集所有答案，并在最后修改文件。

创建高质量评估的提示

认真思考并提前规划，再生成任务
尽可能并行处理，以加快进度并管理上下文
关注真实的使用场景，即人们实际希望完成的任务
创建有挑战性的问题，以测试 MCP 服务能力的极限
通过使用历史数据和已结束的概念确保稳定性
使用 MCP 服务工具解答问题，以验证答案
根据过程中发现的情况迭代和改进

运行评估

创建评估文件后，使用提供的评估框架测试 MCP 服务。

设置

安装依赖项

pip install -r scripts/requirements.txt

或手动安装：

pip install anthropic mcp

设置 API 密钥

export ANTHROPIC_API_KEY=your_api_key_here

评估文件格式

评估文件使用 XML 格式，包含 <qa_pair> 元素：

<evaluation>
   <qa_pair>
      <question>Find the project created in Q2 2024 with the highest number of completed tasks. What is the project name?</question>
      <answer>Website Redesign</answer>
   </qa_pair>
   <qa_pair>
      <question>Search for issues labeled as "bug" that were closed in March 2024. Which user closed the most issues? Provide their username.</question>
      <answer>sarah_dev</answer>
   </qa_pair>
</evaluation>

运行评估

评估脚本（scripts/evaluation.py）支持三种传输类型：

重要：

stdio 传输：评估脚本会自动为你启动并管理 MCP 服务进程。不要手动运行服务。
sse/http 传输：运行评估前，你必须单独启动 MCP 服务。脚本会连接到指定 URL 上已运行的服务。

1. 本地 STDIO 服务

适用于本地运行的 MCP 服务（脚本会自动启动服务）：

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  evaluation.xml

使用环境变量：

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  -e API_KEY=abc123 \
  -e DEBUG=true \
  evaluation.xml

2. 服务器发送事件（SSE）

适用于基于 SSE 的 MCP 服务（先启动服务）：

python scripts/evaluation.py \
  -t sse \
  -u https://example.com/mcp \
  -H "Authorization: Bearer token123" \
  -H "X-Custom-Header: value" \
  evaluation.xml

3. HTTP（可流式传输的 HTTP）

适用于基于 HTTP 的 MCP 服务（先启动服务）：

python scripts/evaluation.py \
  -t http \
  -u https://example.com/mcp \
  -H "Authorization: Bearer token123" \
  evaluation.xml

命令行选项

usage: evaluation.py [-h] [-t {stdio,sse,http}] [-m MODEL] [-c COMMAND]
                     [-a ARGS [ARGS ...]] [-e ENV [ENV ...]] [-u URL]
                     [-H HEADERS [HEADERS ...]] [-o OUTPUT]
                     eval_file

positional arguments:
  eval_file             Path to evaluation XML file

optional arguments:
  -h, --help            Show help message
  -t, --transport       Transport type: stdio, sse, or http (default: stdio)
  -m, --model           Claude model to use (default: claude-3-7-sonnet-20250219)
  -o, --output          Output file for report (default: print to stdout)

stdio options:
  -c, --command         Command to run MCP server (e.g., python, node)
  -a, --args            Arguments for the command (e.g., server.py)
  -e, --env             Environment variables in KEY=VALUE format

sse/http options:
  -u, --url             MCP server URL
  -H, --header          HTTP headers in 'Key: Value' format

输出

评估脚本会生成一份详细报告，其中包括：

汇总统计信息：
- 准确率（正确数/总数）
- 平均任务耗时
- 每项任务的平均工具调用次数
- 工具调用总次数
每项任务的结果：
- 提示词和预期响应
- Agent 的实际响应
- 答案是否正确（✅/❌）
- 耗时和工具调用详情
- Agent 对其处理方法的总结
- Agent 对工具的反馈

将报告保存到文件

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_server.py \
  -o evaluation_report.md \
  evaluation.xml

完整示例工作流

以下是创建并运行评估的完整示例：

创建评估文件（my_evaluation.xml）：

<evaluation>
   <qa_pair>
      <question>Find the user who created the most issues in January 2024. What is their username?</question>
      <answer>alice_developer</answer>
   </qa_pair>
   <qa_pair>
      <question>Among all pull requests merged in Q1 2024, which repository had the highest number? Provide the repository name.</question>
      <answer>backend-api</answer>
   </qa_pair>
   <qa_pair>
      <question>Find the project that was completed in December 2023 and had the longest duration from start to finish. How many days did it take?</question>
      <answer>127</answer>
   </qa_pair>
</evaluation>

安装依赖项：

pip install -r scripts/requirements.txt
export ANTHROPIC_API_KEY=your_api_key

运行评估：

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a github_mcp_server.py \
  -e GITHUB_TOKEN=ghp_xxx \
  -o github_eval_report.md \
  my_evaluation.xml

查看 github_eval_report.md 中的报告，以便：
- 查看哪些问题通过或未通过
- 阅读 Agent 对工具的反馈
- 找出需要改进的方面
- 迭代改进 MCP 服务设计

本地 MCP 服务约定（mcp-* 仓库）

构建或评估 MCP 服务时，请遵循以下模式：

提供一个运行 stdio 服务的 mcp 子命令（例如，mcp-vector-search mcp、mcp-ticketer mcp --path <repo>、mcp-browser mcp）。
尽量采用紧凑、整合的工具集，以减少 token 占用；列出数据时使用分页和紧凑模式。
添加 setup、install 或 doctor 命令，以验证运行时依赖项并与客户端集成。
优先使用包含 type: stdio、明确指定 command 且只需少量 env 覆盖项的 .mcp.json 条目。

.mcp.json 条目示例：

{
  "mcpServers": {
    "mcp-vector-search": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "mcp-vector-search", "mcp"],
      "env": {
        "MCP_ENABLE_FILE_WATCHING": "true"
      }
    }
  }
}

运行注意事项：

为适配器和数据库路径使用明确的环境变量（例如，MCP_TICKETER_ADAPTER、KUZU_MEMORY_DB）。
运行 HTTP/SSE 变体时，提供健康检查端点。
浏览器集成应支持动态分配端口（mcp-browser 使用端口范围）。

故障排除

连接错误

发生连接错误时：

STDIO：确认命令和参数正确
SSE/HTTP：检查 URL 是否可访问，以及请求头是否正确
确认所需的 API 密钥已设置在环境变量或请求头中

准确率低

如果许多评估未通过：

查看 Agent 对每项任务的反馈
检查工具描述是否清晰、全面
确认输入参数是否有完善的文档说明
考虑工具返回的数据是否过多或过少
确保错误消息具有可操作性

超时问题

如果任务超时：

使用能力更强的模型（例如，claude-3-7-sonnet-20250219）
检查工具是否返回了过多数据
确认分页功能正常
考虑简化复杂问题

支持 Markdown

登录后评论

基本信息

作者: bobmatnyc
仓库: bobmatnyc/claude-mpm-skills
分类: 测试与质量
安装次数: 135
GitHub Stars: 78

报告问题