mcpscope

<p align="center"> <img src="docs/design-assets/logo.png" alt="mcpscope" width="320" /> </p> **一款用于开发、检查和基准测试MCP服务器的本地优先工作台，适用于本地（LM Studio，Ollama）或远程（OpenRouter）模型 — 一个共享的工作空间，带有Web UI供您使用，以及供您的编码代理使用的CLI + MCP接口。** 构建一个好的MCP服务器是经验性的工作，而且您通常不会单独完成：编码代理可以运行每个基准测试和读取每个跟踪，但只有当开发人员保持在循环中时，数字才会变得“良好” — 查看失败的运行，收紧工具描述或评分标准，决定下一步尝试，然后重新运行。mcpscope是为这种伙伴关系而构建的。它不是一个基准测试工具，供代理无人值守运行，也不是一个图形用户界面，供开发人员手动驱动：每个功能都通过Web UI暴露给人员，通过CLI和MCP接口暴露给代理，所有功能都基于一个共享的数据模型。人类可以准确地看到代理做了什么，代理可以准确地检查人类做了什么，基于类型标签的ID系统允许两者指向同一个会话、回合或工具调用。 为什么这个循环很重要：LLM的好坏取决于它所给出的工具 — 我在构建自己的MCP服务器用于数据分析和统计时学到了这一点。我的第一个版本做了显而易见的事情：包装现有的API并将原始数据返回给模型。结果证明这是一个糟糕的设计 — 浪费令牌、不精确并且依赖于具有大上下文窗口的大模型才能产生有用的结果。只有当服务器本身完成工作（计算、聚合和过滤）并返回答案而不是数据时，结果才变得良好。这种经验是mcpscope构建的前提：一个好的MCP服务器不是API包装器。它是一个为LLM构建的用户界面，旨在高效地解决特定任务，即使在小型本地模型上也是如此。而且它像其他应用程序一样，因此从明确的用例和质量标准开始，大多数普通的软件工程都适用。 不移植的部分是测试。你不能用确定性断言来确定端到端行为，因为模型是非确定性的，其输入和输出大多是自然语言。因此，像更广泛的评估生态系统一样，mcpscope统计质量 — 运行一组提示多次针对选择的模型和MCP服务器，然后读取每个工具的可靠性令牌成本，可选地由单独的评估模型对答案质量进行评分。mcpscope添加的内容是将测量 *置于* 迭代循环中，而不是在循环结束时：每次运行都保持可检查，直到每个推理步骤、工具调用和上下文令牌，因此“分数下降”立即变成“查看模型在这里做了什么”。 您可以运行提示或可重复的基准测试，针对本地（LM Studio，Ollama）或远程（OpenRouter）模型，查看每个推理步骤、工具调用和上下文令牌，然后更改一个内容（工具描述、参数、输出有效载荷）并再次运行。所有内容都保留在您的机器上。 ## 入门指南 **先决条件（2分钟）：** 运行LLM后端 — 本地（[LM Studio](https://lmstudio.ai)，[Ollama](https://ollama.com)）或远程（[OpenRouter](https://openrouter.ai)）。对于LM Studio：打开 **开发者** 标签 → **启动服务器**，加载模型，并记下其模型ID — 服务器URL为 `http://localhost:1234/v1`。 ### 桌面应用程序 — 最简单的试用方式 从 [**发布页面**](https://github.com/ffleurey/mcpscope/releases) 为您的操作系统下载安装程序（macOS `.dmg`，Windows `.exe`，Linux `AppImage`/`.deb`/`.rpm`）。所有内容都已捆绑 — 启动它，工作台就会打开；数据存储在 `~/.mcpscope`。当它运行时，它提供的后端与 `mcpscope serve` 相同，位于 **`http://localhost:3066`** （MCP接口位于 `/mcp`），因此编码代理和其他MCP客户端可以直接连接到它 — 在启动前设置 `BACKEND_HOST` / `BACKEND_PORT` 环境变量以更改地址（在 **配置 → 服务器** 下显示）。目前，构建版本未签名，因此macOS Gatekeeper / Windows SmartScreen在运行时会发出警告。 ### npm — 用于开发MCP服务器（添加CLI） 如果您正在构建MCP服务器，您将需要CLI（和用于您的编码代理的MCP接口）。需要 **Node.js 24+**： ```bash npm install -g mcpscope mcpscope serve ``` 或在不安装的情况下运行：`npx mcpscope serve`。 `mcpscope serve` 在 **`http://localhost:3066`** 启动mcpscope，并在您的浏览器中打开它。数据存储在 `~/.mcpscope`；使用 `Ctrl-C` 停止。标志： `--port <n>`， `--host <host>`， `--data-dir <path>`， `--no-open`。 ### 步骤（任一安装） 1. 在Web UI中，打开 **配置** 并添加 **LM连接** （上述基准URL）和 **模型配置** （您加载的模型ID），然后将其设置为默认模型。启动时不需要MCP配置文件 — mcpscope附带零配置 [配套MCP服务器](COMPANIONS.md)。如果您更喜欢编辑文件？相同的设置方式为JSON： [CONFIG.md](CONFIG.md)。 2. 创建会话，选择配套服务器（例如 **Open-Meteo Weather**），发送提示并检查完整跟踪：设置、工具定义、推理、工具调用和结果，以及每个回合的彩色编码上下文分解。 3. 当您准备好将mcpscope指向您自己的服务器时，添加 **MCP服务器配置文件**。 4. 定义 **基准** 并运行它，以针对模型重复测试MCP服务器 — 然后将相同的循环交给您的编码代理。 完整的演练在 [TUTORIAL.md](TUTORIAL.md) 中；有真实数字的工作示例在 [EXAMPLE.md](EXAMPLE.md) 中。 ## 用于编码代理 mcpscope本身支持MCP — 连接您的代理，它可以驱动UI中看到的整个循环： ```bash claude mcp add --transport http mcpscope http://localhost:3066/mcp ``` ```json { "mcpServers": { "mcpscope": { "type": "http", "url": "http://localhost:3066/mcp" } } } ``` 然后像这样的提示足以让代理工作： > mcpscope正在localhost:3066运行（MCP位于/mcp； `mcpscope` CLI是相同的接口）。使用其 `mcpscope_*` 工具来基准测试我的MCP服务器：首先使用 `mcpscope_list_mcp_profiles` 和 `mcpscope_list_model_configs`，创建会话并发送提示时使用 `wait: true`，这样您永远不会轮询，并在EXAMPLE.md中遵循循环。 每个操作既是CLI命令，又是MCP工具（测试强制对等），结果是snake_case JSON， `create` / `send` 需要 `wait`，以便代理在一次调用中获得终端结果。详细信息： [MCP.md](MCP.md)。 ## 其他运行方式 - **Docker**：发布的镜像发布到GHCR。参见 [TUTORIAL.md](TUTORIAL.md) 了解逐步路径， [RELEASING.md](docs/RELEASING.md) 了解镜像标签。 - **从源代码**：对于正在开发mcpscope本身，参见 [DEVELOPMENT.md](docs/DEVELOPMENT.md)。 ## 您可以使用 - **检查会话**：查看模型如何读取工具定义、推理、调用工具和消耗上下文窗口，并对每个部分进行可审计的令牌归属。 - **基准测试MCP服务器**：一组可重复使用的提示，针对选择的模型和MCP服务器运行N次，生成每个工具的错误/使用率评分卡和每个案例的可靠性（pass@k / pass^k）。 - **LLM评估答案质量**：单独的评估模型根据每个案例的评分标准评估每个运行的答案质量（参见 [BENCHMARK.md](BENCHMARK.md)）。 - **从Shell或作为MCP工具驱动它**：每个操作既是 `mcpscope <cmd>` CLI命令，又是 `mcpscope_<cmd>` MCP工具，因此编码代理可以运行整个循环 — 在UI中看到的同一个会话。 ## 比较 许多优秀的工具都涉及这个领域的部分内容；区别在于它们服务于循环的哪个部分，以及为谁提供服务。 - [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 在协议级别探测MCP服务器 — 列出工具，手动调用它们。循环中没有模型； mcpscope测试模型实际上 *做了什么*，使用您的服务器。 - [mcpsnoop](https://github.com/kerlenton/mcpsnoop) 捕获实际的客户端↔服务器MCP流量在线。mcpscope运行模型本身，并归因于每个上下文令牌。 - [MCPJam](https://github.com/MCPJam/inspector) 是最接近的邻居：带有评估和跟踪的LLM游乐场。 mcpscope在每个部分的令牌归属、pass@k / pass^k可靠性统计数据和一个共享存储库中具有人机对等性。 - [promptfoo](https://github.com/promptfoo/promptfoo)、 [mcp-eval](https://github.com/lastmile-ai/mcp-eval) 和 [DeepEval](https://github.com/confident-ai/deepeval) 是配置或代码驱动的评估工具，在其最佳状态下，可作为CI中的无人值守回归门。 mcpscope是迭代循环的交互式工作台 *之前* — 并通过CLI/MCP公开相同的操作，以便代理也可以驱动它。 - [MCPBench](https://github.com/modelscope/MCPBench)、 [MCP-Bench](https://github.com/Accenture/mcp-bench) 和 [MCPMark](https://github.com/eval-sys/mcpmark) 以固定的服务器集为基准测试 *模型*。 mcpscope以您选择的模型为基准测试 *您的服务器*。 - [LM Studio](https://lmstudio.ai) 和 [Open WebUI](https://docs.openwebui.com) 是带有工具支持的聊天接口 — 仅限于人类，具有聚合令牌计数。 LM Studio是mcpscope支持的后端之一，而不是竞争对手。 如果其中一个更适合您的工作流程，请使用它 — 其中几个非常优秀。 mcpscope适用于您和您的编码代理一起迭代您自己的MCP服务器的循环。 ## 文档 ### 入门指南 - [TUTORIAL.md](TUTORIAL.md) - 安装、配置、运行会话和基准测试MCP服务器 - [EXAMPLE.md](EXAMPLE.md) - 工作示例：检查 → 基准测试 → 更改一个内容 → 观察指标变化 - [CONFIG.md](CONFIG.md) - `mcpscope.config.json` 参考，包括完全无头设置 - [COMPANIONS.md](COMPANIONS.md) - 捆绑的零配置配套MCP服务器，您可以在无需设置的情况下选择 - [BENCHMARK.md](BENCHMARK.md) - 基准测试套件/案例/运行模型，确定性指标和LLM评分评估 ### 接口 - [MCP.md](MCP.md) - MCP接口：传输、工具表面和结构化结果 - [CLI.md](CLI.md) - CLI命令、标志、输出格式和退出代码 ### 内部和贡献 - [DEVELOPMENT.md](docs/DEVELOPMENT.md) - 从源代码运行、构建、开发助手和存储库说明 - [AGENTS.md](AGENTS.md) - 用于在mcpscope本身上工作的AI编码代理的指南：项目形状、对等原则、工作风格、验证 - [ARCHITECTURE.md](docs/ARCHITECTURE.md) - 系统设计、持久性、流媒体、重放和API表面 - [PROVIDERS.md](docs/PROVIDERS.md) - 提供者内部（LM Studio，Ollama，OpenRouter）：推理令牌、令牌计数、上下文窗口、模型加载/卸载（包括自动交换） - [DATA-MODEL.md](docs/DATA-MODEL.md) - 规范运行时树、部分分类和ID - [DATABASE-SCHEMA.md](docs/DATABASE-SCHEMA.md) - SQLite表、外键和ER图 - [DESIGN-SYSTEM.md](docs/DESIGN-SYSTEM.md) - 前端设计系统：令牌、基元和模式，保持GUI一致 - [design-assets/](docs/design-assets/) - 主logo SVGs（logo、mark、wordmark、favicon）；参见其README - [TESTING.md](docs/TESTING.md) - 测试策略、重放以及如何添加回归 - [RELEASING.md](docs/RELEASING.md) - 标签驱动的发布工作流：npm发布、GHCR镜像和桌面安装程序 内部/贡献者文档位于 [`docs/`](docs/) 下；面向用户的指南保留在存储库根目录下。