内容
# 验证动作MCP
一个小型的 [MCP](https://modelcontextprotocol.io) 服务器，为编码代理提供一个 **世界模型**，以便在采取重要行动之前进行咨询。它公开了一个工具 — `verify_action` — 代理在执行难以逆转的操作（删除文件、破坏性 shell 命令、重写历史的 git 操作）之前调用。服务器询问世界模型LLM预测环境响应，并返回该预测，以便代理可以决定是否继续、改变方向或询问用户。
> 它是一个 **代理自愿咨询的预言**，而不是一个阻止行动的防护栏。代理自己的推理决定如何处理预测。
## 工作原理
```
代理 (Claude Code) ──verify_action──▶ verify-action-mcp ──▶ 世界模型 LLM
▲ │
└────────────── 预测的环境响应 ◀────────┘
```
操作被路由到一个领域系统提示（终端 vs. 软件工程），结合最近的交互历史，并发送到配置的后端。
## 后端
一个环境变量 (`WORLD_MODEL_BACKEND`) 选择后端:
| 后端 | 模型 | 成本 | 设置 |
|---|---|---|---|
| `groq` （默认） | `qwen/qwen3.6-27b` | 免费，无需卡 | 主机 | ~2 分钟 |
| `together` | `Qwen/Qwen3.5-35B-A3B`¹ | $25 免费积分 | 主机 | ~2 分钟 |
| `qwen_agentworld` | `Qwen-AgentWorld-35B-A3B` | 您的硬件 | **本地或云端** | ~10–20 分钟 |
¹ 请在您的仪表板上确认确切的 Together 模型 ID — 无服务器目录会发生变化，错误的 ID 会返回 *模型未找到*。
**您不需要 GPU 即可启动。** 使用 Groq（免费，托管）进行设置，时间仅需 2 分钟。`qwen_agentworld` 后端 — 真正的、专门构建的世界模型 — 可以在 **本地**（通过 Ollama/llama.cpp 的量化 GGUF）或 **云端**（通过 vLLM/SGLang 在租用的 GPU 上以全精度运行）运行。参见 [运行真正的模型](#运行真正的模型-本地或云端).
## 快速入门
```bash
git clone https://github.com/Haseebasif7/world-model-mcp.git
cd world-model-mcp
./setup.sh # 创建 venv，安装，拉取官方提示，打印配置
```
然后将您的密钥放入 `.env`（从 `.env.example` 创建）：
```env
WORLD_MODEL_BACKEND=groq
GROQ_API_KEY=gsk_your_key_here # 在 https://console.groq.com 免费获取
```
### 手动安装（无需 setup.sh）
```bash
uv venv
uv pip install -e .
cp .env.example .env # 然后编辑 .env
```
## 连接您的代理
这是一个标准的 **stdio MCP 服务器**，因此它与任何 MCP 兼容的框架都兼容 — Claude Code、Cursor、Windsurf、VS Code（Copilot）、Claude Desktop 等。它们都使用相同的想法：注册一个带有 `command`、`args` 和 `env` 的服务器。使用已安装二进制文件的绝对路径：
```
<repo>/.venv/bin/verify-action-mcp
```
共享配置格式（Cursor、Windsurf、Claude Desktop、Claude Code `.mcp.json`）：
```json
{
"mcpServers": {
"verify-action": {
"command": "/abs/path/to/.venv/bin/verify-action-mcp",
"args": [],
"env": {
"WORLD_MODEL_BACKEND": "groq",
"GROQ_API_KEY": "gsk_your_key_here"
}
}
}
}
```
每个框架读取的位置：
| 框架 | 配置位置 |
|---|---|
| **Claude Code** | `claude mcp add`（如下），或项目 `.mcp.json`，或 `~/.claude.json` |
| **Cursor** | `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目） |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **Claude Desktop** | `claude_desktop_config.json` |
| **VS Code (Copilot)** | `.vscode/mcp.json` — 注意：顶级键是 `servers`，而不是 `mcpServers` |
**Claude Code 快捷方式（CLI）：**
```bash
claude mcp add verify-action \
--env WORLD_MODEL_BACKEND=groq \
--env GROQ_API_KEY=gsk_your_key_here \
-- "$(pwd)/.venv/bin/verify-action-mcp"
```
复制 `.mcp.json.example` 以开始使用，然后在您的框架中重启/重新打开项目。在启动时，服务器将后端记录到 stderr，例如 `[verify-action-mcp] backend: Groq — qwen/qwen3.6-27b`.
## 安全
- **永远不要提交真实密钥。** `.env` 和 `.mcp.json` 被 gitignore；存储库仅提供 `.env.example` 和 `.mcp.json.example`，其中包含占位符。
- 如果密钥曾经暴露，**请旋转它** 在提供商处。
## 测试
```bash
WORLD_MODEL_BACKEND=groq uv run python tests/test_world_model.py
```
运行四个场景（只读 `ls`、`rm -rf`、`git reset --hard`、`git push --force`）并打印每个场景的世界模型的预测输出。
## 运行真正的模型（本地或云端）
`qwen_agentworld` 后端与 **任何 OpenAI 兼容的端点** 服务模型对话，因此您可以选择适合您硬件的路径。在这两种情况下，您只需要设置两个环境变量 — `QWEN_AGENTWORLD_URL`（它被服务的位置）和 `QWEN_AGENTWORLD_MODEL`（服务的名称） — 无需更改代码。
所有本地选项都使用 **量化 GGUF**。选择适合您 VRAM/RAM 的量化（较低的比特 = 更小 + 更快，但保真度较低）：
| 量化 | 大小 | 适合 |
|---|---|---|
| `Q2_K_XL` （2 位） | ~12 GB | 16 GB GPU，或 16 GB+ Mac，或 CPU+RAM |
| `Q4_K_M` （4 位，推荐） | ~22 GB | 24 GB GPU（4090/3090），32 GB+ Mac |
| `BF16` （完整） | ~69 GB | 云/多 GPU 路径（如下） |
### 选项 1a — 本地使用 Ollama（最简单）
```bash
# Ollama 在 :11434 上公开了一个 OpenAI 兼容的 API
ollama run hf.co/unsloth/Qwen-AgentWorld-35B-A3B-GGUF:Q4_K_M
```
```env
WORLD_MODEL_BACKEND=qwen_agentworld
QWEN_AGENTWORLD_URL=http://localhost:11434
QWEN_AGENTWORLD_MODEL=hf.co/unsloth/Qwen-AgentWorld-35B-A3B-GGUF:Q4_K_M
```
### 选项 1b — 本地使用 llama.cpp
[`llama-server`](https://github.com/ggml-org/llama.cpp) 直接从 Hugging Face 下载 GGUF 并提供 OpenAI 兼容的 API。通过 `brew install llama.cpp`（macOS）或从源代码构建，然后：
```bash
# -hf 从 HF 拉取量化；--port 设置 OpenAI 兼容的端点
llama-server -hf unsloth/Qwen-AgentWorld-35B-A3B-GGUF:Q4_K_M \
--port 8080 --ctx-size 16384 --jinja
```
```env
WORLD_MODEL_BACKEND=qwen_agentworld
QWEN_AGENTWORLD_URL=http://localhost:8080
# llama-server 忽略请求中的模型字段，因此任何非空值都有效：
QWEN_AGENTWORLD_MODEL=qwen-agentworld
```
> `--ctx-size` 控制上下文长度（如果您有内存，请提高它；完整模型支持高达 262,144）。 `--jinja` 启用模型的聊天模板。LM Studio 也以相同的方式工作 — 启动其本地服务器并将 `QWEN_AGENTWORLD_URL` 指向它。
### 选项 2 — 云端，全精度租用 GPU（最佳质量）
对于非量化模型，租用一个多 GPU 主机（~70 GB+ VRAM；例如 [RunPod](https://www.runpod.io)/[Lambda](https://lambdalabs.com) 上的 2× A100 80GB），并使用 vLLM 或 SGLang 提供服务：
```bash
# vLLM — --language-model-only 是必需的：检查点仅提供 LM 权重
vllm serve Qwen/Qwen-AgentWorld-35B-A3B \
--port 8000 --tensor-parallel-size 4 \
--max-model-len 262144 --reasoning-parser qwen3 \
--language-model-only --trust-remote-code
```
```env
WORLD_MODEL_BACKEND=qwen_agentworld
QWEN_AGENTWORLD_URL=http://YOUR_HOST:8000
QWEN_AGENTWORLD_MODEL=Qwen/Qwen-AgentWorld-35B-A3B
```
模型的默认上下文长度为 **262,144** 个令牌（降低它以减少 VRAM）。推荐采样：`temperature=0.6, top_p=0.95, top_k=20`.
## 链接
- Qwen-AgentWorld（完整）：https://huggingface.co/Qwen/Qwen-AgentWorld-35B-A3B
- Qwen-AgentWorld（GGUF，用于本地）：https://huggingface.co/unsloth/Qwen-AgentWorld-35B-A3B-GGUF
- Qwen-AgentWorld 仓库（提示/评估）：https://github.com/QwenLM/Qwen-AgentWorld
- MCP Python SDK：https://github.com/modelcontextprotocol/python-sdk
## 许可证
MIT — 参见 [LICENSE](LICENSE).
