内容
# mock-mcp-server
一种用于建立模拟MCP（Model Context Protocol）服务器的配置驱动框架 — 在代理评估工具（deepeval，自定义评估循环）中很有用，因为真正的工具调用可能很慢、不稳定或成本高昂。
您可以用OpenAPI 3.1和一些`x-mock-*`扩展来描述API表面，并将其放在`configs/`下，然后按名称运行：
```bash
uv run mock-mcp --config monthly-report
```
服务器在`/mcp`上支持MCP，并在操作路径上提供与常规HTTP API相同的工具。
## 为什么
真正的生产工具通常会调用许多后端服务，并且每次调用都需要几秒钟。当评估工具调用同一个工具数百次时，运行变得不切实际。这个框架为您提供了一个**直接替换的模拟**：
- 返回针对相同输入的**确定性**合成数据（使用请求参数播种的RNG密钥）。
- 在`/mcp`上支持**MCP**，因此评估工具可以无需代码更改地插入。
- 发出与真实服务器相同的**OpenAPI结构**，因此代理看到的工具模式是相同的。
- **立即运行**，无需触及外部服务。
配置文件只是YAML — 无需Python即可添加新的模拟。
## 快速开始
```bash
# 1. 安装
uv sync
# 2. 运行捆绑的monthly-report配置文件
uv run mock-mcp --config monthly-report
# 3. 访问它
curl -H "Authorization: Bearer mock-test-token" \
"http://localhost:8001/reports/generate?report_month=2025-06"
```
MCP端点位于`http://localhost:8001/mcp`。标准的FastAPI文档位于`/docs`、`/redoc`和`/openapi.json`。
> **提示：** 将运行的模拟与[**Forbin**](https://github.com/chris-colinsky/forbin-mcp)（一个交互式MCP客户端）配对使用，可以在不编写任何客户端代码的情况下浏览和调用模拟的工具。参见[`docs/pairing-with-forbin.md`](docs/pairing-with-forbin.md)。
## 文档
[`docs/`](docs/)下的主题组织参考：
| 主题 | 描述 |
|---|---|
| [入门](docs/getting-started.md) | 安装、运行、CLI标志、并行运行多个模拟。 |
| [配置文件参考](docs/config-reference.md) | 解释每个`x-mock-*`扩展。 |
| [配方](docs/recipes.md) | 叶子配方目录（`random_int`、`faker`、`from`、`template`等）。 |
| [派生DSL](docs/derived.md) | 交叉字段运算符（`ref`、`sum`、`mul`等）用于不变量。 |
| [验证](docs/validation.md) | OAS关键词、内置验证器、编写自己的验证器。 |
| [身份验证](docs/auth.md) | Bearer令牌设置、MCP头部转发、常见陷阱。 |
| [创作策略](docs/strategies.md) | 模式：静态vs动态、确定性、陷阱、演练。 |
| [IDE设置](docs/ide-setup.md) | PyCharm和VS Code模式验证。 |
| [与Forbin配对](docs/pairing-with-forbin.md) | 用于测试模拟的交互式客户端。 |
| [开发](docs/development.md) | Makefile、测试、预提交、CI/发布工作流。 |
| [示例](docs/examples/) | 捆绑配置文件的演练。 |
| [未来方向](docs/FUTURE.md) | 开放设计问题和v0.2+的草图。 |
[`docs/README.md`](docs/README.md)是索引页。
## 捆绑配置文件
| 配置文件 | 演示 |
|---|---|
| [`configs/monthly-report.yaml`](configs/monthly-report.yaml) | 经过身份验证的配置文件，演示每个框架功能：动态配方、派生DSL、总和/增量不变量、自定义验证器、Bearer身份验证、种子确定性。（[演练](docs/examples/monthly-report.md)) |
| [`configs/inventory-briefing.yaml`](configs/inventory-briefing.yaml) | 开放（无身份验证）配置文件，演示可变形状响应、模板派生计算值和Faker生成的结构化记录。（[演练](docs/examples/inventory-briefing.md)) |
## 项目布局
```
mock-mcp-server/
├── pyproject.toml
├── Makefile
├── .pre-commit-config.yaml
├── .github/workflows/ # CI + 发布
├── schemas/ # x-mock-*扩展的JSON模式
├── configs/ # 捆绑配置文件YAML
├── app/ # 框架源代码
│ ├── __main__.py # CLI
│ ├── loader.py # OAS + x-mock-* → FastAPI
│ ├── mcp_server.py # /mcp端点，OAS → MCP工具
│ ├── auth.py # Bearer身份验证
│ ├── validators.py # 自定义验证器
│ └── mock/ # 响应生成引擎
├── tests/ # ~95个测试
└── docs/ # 本README的深入参考
```
## 限制
- **请求体模式**以OAS形式接受但不深度验证。主体原样传递到调度调用。如果需要严格的主体验证，请提出问题。
- **`/mcp`上没有SSE流** — 仅安装可流式的HTTP传输，工具调用响应在返回前被缓冲。对于无状态的一次性MCP调用来说很好。
- **`tools/call`以`TextContent`（JSON字符串）返回响应体** — 匹配大多数MCP客户端的预期。不会合成结构化的多块响应（图像、嵌入式资源）。
- **分发是“克隆存储库”，而不是`pip install`。** `--config <name>`解析器在存储库的`configs/`目录下查找；目前没有很好的用户体验来支持从已安装的包中自行配置。参见[`docs/FUTURE.md`](docs/FUTURE.md)以了解其发展方向。
## 许可证
MIT（在[`pyproject.toml`](pyproject.toml)中声明）。在项目分发到源存储库以外的其他地方之前，将添加单独的`LICENSE`文件。
MCP 市场