内容
# mcp-sandbox
**免费、开源的MCP服务器，适用于开发者和GenAI评估。**
每个工具都返回一个稳定的、极不可能的 **校验令牌** —— 模型通常不会主动提供此令牌。如果响应中出现该令牌，则调用确实已到达此模型上下文协议（MCP）服务器。如果没有，则工具从未被调用。这使其成为学习MCP、连接客户端以及在CI和评估中确认工具调用的干净装置。
🌐 **在线服务器：** `https://mcp.heptafox.com/mcp` · 📖 **指南：** [mcp.heptafox.com](https://mcp.heptafox.com/)
---
## 什么是mcp-sandbox？
一个公共的 [MCP](https://modelcontextprotocol.io) 服务器，提供 **确定性测试装置**。每个工具返回一个固定的校验字符串，而不是真实数据，因此您可以证明响应源自服务器，而不是模型的训练或上下文。
## 为什么使用它？
当您构建或测试代理时，您通常 *不* 希望将其指向生产MCP服务器。您需要一个确定性的端点，始终返回一个已知值。mcp-sandbox就是该端点：
- 🎓 **学习MCP** — 几分钟内连接真实服务器，无需API密钥或数据设置。
- 🔌 **测试客户端** — 确认客户端实际调用工具并中继输出。
- ✅ **验证集成** — 证明MCP层端到端工作。
- 🚦 **烟雾测试** — CI/CD管道的单次调用健康检查。
- 🧪 **自动化评估** — 断言稳定令牌，而不是模糊模型文本。
## 适用于谁？
MCP学习开发者 · AI应用和代理框架开发者 · QA工程师 · GenAI评估框架 · CI/CD集成测试。
## 支持的MCP客户端
与任何支持流式HTTP的MCP兼容客户端配合使用，包括：
Claude Desktop · Claude Code · Cursor · Google ADK · LangChain · CrewAI ·
OpenAI Agents SDK · MCP Inspector
## 功能
- ✨ **稳定校验令牌** — 您可以在其上精确断言的确定性输出。
- 🌐 **流式HTTP传输** — 现代MCP传输，端点 `/mcp`。
- 🔑 **持有者令牌身份验证检查** — 用于验证身份验证已到达服务器的工具。
- 🪶 **零设置** — 无API密钥，无帐户，无数据。
- 🆓 **免费和开源** — Apache-2.0。
## 学习进度
工具按顺序排列，您可以逐一学习概念，从“是否连接？”到“身份验证是否到达？”：
| 级别 | 工具 | 身份验证 | 参数 | 教学 |
|:-----:|--------------|:------:|:------:|--------------------|
| 1 | `identity` | 否 | 否 | 连接性 |
| 2 | `echo` | 否 | 是 | 传递参数 |
| 3 | `auth_check` | Bearer | 否 | 身份验证 |
## 工具
### `identity` — 连接性检查
无参数。返回固定ID字符串。原样显示以确认服务器已响应。
```
MCP-SANDBOX canary 7Q9X-ZK42-VORTEX-PARSNIP
```
### `echo` — 参数传递
参数：`message: str`，`repeat: int = 1`。将您的文本发送到服务器并返回到一个固定包装中，重复 `repeat` 次。
```
MCP-SANDBOX echo 4F7T-ECHO-START >>> 您的文本 <<< 4F7T-ECHO-END
```
### `auth_check` — 身份验证
无参数（读取 `Authorization` 头）。验证服务器是否看到您的 `Bearer` 令牌。
```
MCP-SANDBOX auth OK 9B3K-AUTHED-MARIGOLD # 有效令牌
MCP-SANDBOX auth FAIL 9B3K-NOAUTH-CINDER # 缺失/无效令牌
```
## 身份验证
`auth_check` 由 **公共开发持有者令牌** 控制：
```
Authorization: Bearer mcp-sandbox-dev-C7H2-KPMERCHANT
```
这是用于集成测试的共享烟雾测试令牌 — **它是公开的，不是生产凭证**。它仅控制 `auth_check`。
## 快速入门
### 使用托管服务器
**Claude Code** — 一个命令：
```bash
claude mcp add --transport http mcp-sandbox https://mcp.heptafox.com/mcp \
--header "Authorization: Bearer mcp-sandbox-dev-C7H2-KPMERCHANT"
```
**Claude Desktop** — 配置仅限stdio，因此通过 `mcp-remote` 在 `claude_desktop_config.json` 中桥接：
```json
{
"mcpServers": {
"mcp-sandbox": {
"command": "npx",
"args": [
"-y", "mcp-remote", "https://mcp.heptafox.com/mcp",
"--header", "Authorization: Bearer mcp-sandbox-dev-C7H2-KPMERCHANT"
]
}
}
}
```
**原始HTTP** — 直接调用端点：
```bash
curl -X POST https://mcp.heptafox.com/mcp \
-H "Authorization: Bearer mcp-sandbox-dev-C7H2-KPMERCHANT" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"identity","arguments":{}}}'
```
> **端点是 `/mcp` — 没有尾部斜杠。** `/mcp/` 307-重定向到 `/mcp`，某些客户端在重定向时可能会删除POST正文。请始终使用 `/mcp`。
### 在本地运行
```bash
uv sync
uv run server.py # 指南在 http://127.0.0.1:8000/ ，MCP在 /mcp
```
使用MCP Inspector检查它 — 指向 `http://127.0.0.1:8000/mcp`：
```bash
npx @modelcontextprotocol/inspector
```
## 示例
要求任何连接的模型调用工具，然后断言其转发的令牌：
> **提示：** 调用mcp-sandbox的 `identity` 工具并显示其返回值。
>
> **预期：** `MCP-SANDBOX canary 7Q9X-ZK42-VORTEX-PARSNIP`
如果令牌出现，则调用已到达此服务器。如果模型在没有令牌的情况下响应，则工具从未被调用。
## QA和GenAI评估
在评估中，**断言原始工具结果** (`result.content[0].text`)，而不是模型的自然语言摘要 — 令牌是稳定的，而措辞不是。
```python
import asyncio
from fastmcp import Client
async def main():
async with Client("https://mcp.heptafox.com/mcp") as c:
result = await c.call_tool("identity", {})
assert "7Q9X-ZK42-VORTEX-PARSNIP" in result.content[0].text
asyncio.run(main())
```
## 路线图
- 更多适合初学者的工具（错误模拟、流式传输、结构化输出）
- OAuth和附加身份验证示例
- 客户端集成示例（Cursor、Google ADK、LangChain、CrewAI、OpenAI Agents SDK）
- 现成的评估场景和教程
有想法吗？ [打开问题或讨论。](https://github.com/heptafox/mcp-sandbox/issues)
## 贡献
欢迎贡献 — 尤其是适合初学者的工具、客户端示例和文档。新工具只是 `server.py` 中的 `@mcp.tool` 函数，每个函数都返回一个唯一的校验字符串。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 开始。
## 部署您自己的
托管实例在AWS Lightsail（Ubuntu）上运行，位于nginx + Let's Encrypt后面。
要自行托管：`uv sync`，通过 `deploy/mcp-sandbox.service` （systemd）运行，使用 `deploy/nginx.conf` + `certbot --nginx -d <domain>` 启用前端，并仅打开端口80/443 — 应用程序绑定到localhost，nginx代理 `/mcp` 进入。下面是逐步说明。
<details>
<summary>完整的部署步骤（AWS Lightsail，Ubuntu）</summary>
1. **实例 + DNS** — 创建Ubuntu Lightsail实例，将域名A记录指向其静态IP，并在Lightsail防火墙中打开 **80 + 443** 端口。保持8000端口关闭；应用程序仅监听localhost。
2. **应用程序**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone <仓库> ~/mcp-sandbox && cd ~/mcp-sandbox && uv sync
```
3. **systemd** — 将 `deploy/mcp-sandbox.service` 复制到 `/etc/systemd/system/`，然后：
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-sandbox
```
4. **nginx + TLS**
```bash
sudo apt install -y nginx certbot python3-certbot-nginx
# deploy/nginx.conf设置为mcp.heptafox.com；复制到/etc/nginx/sites-available/，
# 在sites-enabled/中创建符号链接，然后：
sudo certbot --nginx -d mcp.heptafox.com
sudo systemctl reload nginx
```
验证：`systemctl status mcp-sandbox` 和 `curl -i https://<domain>/mcp`。
</details>
## 许可证
[Apache License 2.0](LICENSE)。通过贡献，您同意您的贡献根据Apache-2.0获得许可。
