内容
# FactAnchor-MCP
> **通过本地上下文锚定将AI幻觉减少约80%。**
[](LICENSE)
[](https://www.python.org)
[](https://modelcontextprotocol.io)
[](https://modelcontextprotocol.io)
**FactAnchor-MCP** 是一个 **零成本、完全本地** 的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，可以将您的AI助手（Claude Desktop、Cursor、VS Code、Claude Code）固定在真实的、获取的网络文本上，并强制其仅从该文本中回答。
- 💸 **₹0托管成本** — 完全在您的机器上运行。无需云，无需付费API密钥。
- 🛡️ **严格的防护栏** — 大型语言模型必须引用来源或说 *"我无法找到此信息的已验证来源。"*
- 🔎 **免费网络获取** — 使用DuckDuckGo的免费搜索 + 页面抓取（无需Serper/Google密钥）。
- ⚡ **零配置设置** — `pip install -e .` + 连接您的MCP客户端。浏览器在首次启动时自动安装。
> ⭐ **如果FactAnchor-MCP帮助您交付更可靠、更少幻觉的AI，请考虑 [为仓库加星](https://github.com/Tausifonly001/FactAnchor-MCP)。** 这只需一步，帮助更多开发者发现一种真正零成本的方式来固定他们的代理。谢谢！ 🙏
---
## 🚀 1分钟快速入门
### 选项A — 推荐（跨平台，无需路径编辑）
```bash
git clone https://github.com/Tausifonly001/FactAnchor-MCP.git
cd FactAnchor-MCP
pip install -e . # 安装 `factanchor-mcp` 命令
```
然后将以下内容添加到您的 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"FactAnchor-MCP": {
"command": "factanchor-mcp"
}
}
}
```
### 选项B — 简单（直接使用脚本路径）
```bash
git clone https://github.com/Tausifonly001/FactAnchor-MCP.git
cd FactAnchor-MCP
pip install -r requirements.txt
```
将 **绝对路径** 添加到 `server.py`：
```json
{
"mcpServers": {
"FactAnchor-MCP": {
"command": "python",
"args": ["/绝对路径/到/FactAnchor-MCP/server.py"]
}
}
}
```
<details>
<summary>📂 各操作系统路径示例</summary>
- **Windows:** `"C:\\Users\\you\\FactAnchor-MCP\\server.py"`
- **macOS / Linux:** `"/Users/you/FactAnchor-MCP/server.py"` 或 `"/home/you/FactAnchor-MCP/server.py"`
</details>
### 3. 重启您的客户端
您现在将看到 **`fetch_verified_context`** 工具可用。提出一个事实性问题，并观察助手根据实时引用的来源回答。
> ✅ **零配置：** 在首次启动时，FactAnchor会在后台静默安装Playwright Chromium浏览器。无需 `crawl4ai-setup` 或手动浏览器命令。
>
> 💡 使用 `uv` 代替pip？ `uv pip install -e .` 工作相同，且 `factanchor-mcp` 命令位于您的PATH上。
---
## 🧩 支持的客户端（直接配置）
FactAnchor-MCP是一个 **标准MCP服务器**，因此它与 **任何MCP兼容的客户端** 配合使用。以下是直接粘贴的配置。每个客户端都使用相同的两种格式：
- **选项A（推荐）：** `"command": "factanchor-mcp"` — 需要 `pip install -e .` （因此命令在您的PATH上）。
- **选项B（基于路径）：** `"command": "python"` + `"args": ["/绝对路径/server.py"]` — 如果 `factanchor-mcp` 命令未找到，请使用此选项。
<details open>
<summary>💬 Claude Desktop</summary>
文件：`claude_desktop_config.json`（设置 → 开发者 → 编辑配置）
```json
{
"mcpServers": {
"FactAnchor-MCP": { "command": "factanchor-mcp" }
}
}
```
重启Claude Desktop。工具出现在工具列表中。
</details>
<details open>
<summary>🖥️ opencode</summary>
文件：`.opencode.jsonc`（项目根目录）
```jsonc
{
"mcpServers": {
"FactAnchor-MCP": { "command": "factanchor-mcp" }
}
}
```
通过 `/mcp` 验证 — 应该列出 `fetch_verified_context`。
</details>
<details open>
<summary>⌨️ Claude Code / Kimi Code / Qwen Code / Cline / Roo Code</summary>
这些是Claude-Code风格的客户端。使用项目 `.mcp.json`：
```json
{
"mcpServers": {
"FactAnchor-MCP": { "command": "factanchor-mcp" }
}
}
```
或从CLI添加（运行相同的服务器）：
```bash
claude mcp add factanchor -- factanchor-mcp
# Kimi/Qwen/Cline等效使用相同的 `mcp add` 子命令
```
</details>
<details open>
<summary>🌀 Cursor</summary>
文件：`~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目）
```json
{
"mcpServers": {
"FactAnchor-MCP": { "command": "factanchor-mcp" }
}
}
```
在 **设置 → MCP** 中启用并重启Cursor。
</details>
<details open>
<summary>📝 VS Code（Copilot / MCP扩展）</summary>
文件：`.vscode/mcp.json`（注意：VS Code使用 `"servers"` 键）
```json
{
"servers": {
"FactAnchor-MCP": {
"type": "stdio",
"command": "factanchor-mcp"
}
}
}
```
打开命令面板 → **MCP：列出服务器** 以确认已连接。
</details>
<details open>
<summary>🌟 Gemini CLI / Antigravity（谷歌）</summary>
文件：`.gemini/settings.json`
```json
{
"mcpServers": {
"FactAnchor-MCP": { "command": "factanchor-mcp" }
}
}
```
或：`gemini mcp add factanchor -- factanchor-mcp`
</details>
<details open>
<summary>🔧 通用MCP客户端（基于路径的备用方案）</summary>
如果 `factanchor-mcp` 命令不在您的PATH上，请在上述每个客户端上使用 `server.py` 的绝对路径：
```json
{
"mcpServers": {
"FactAnchor-MCP": {
"command": "python",
"args": ["/绝对路径/到/FactAnchor-MCP/server.py"]
}
}
}
```
各操作系统路径示例：
- **Windows:** `"C:\\Users\\you\\FactAnchor-MCP\\server.py"`
- **macOS:** `"/Users/you/FactAnchor-MCP/server.py"`
- **Linux:** `"/home/you/FactAnchor-MCP/server.py"`
</details>
---
## 🛠️ 工作原理
```
[Claude Desktop / Cursor / VS Code]
│ （提出事实性查询）
▼
[FactAnchor MCP 服务器] ───► [免费DuckDuckGo搜索 + 页面抓取]（实时事实）
│ │
│ （注入严格的防护栏 + 已验证的文本） │ （返回原始文本）
▼ ◀
[助手仅根据已验证的上下文回答 → ~0% 幻觉]
```
1. **上下文获取器** — `fetch_verified_context(query)` 运行免费的DuckDuckGo搜索以发现URL，然后 **Crawl4AI** 并发抓取它们，生成干净的、针对LLM优化的Markdown（导航栏、广告和页脚自动剥离）。
2. **防护栏注入** — 获取的文本被包装在一个严格的指令中（参见 `guardrail.py`）：
- 仅根据 `<verified_context>` 回答。
- 如果无法回答，请准确回复： *"我无法找到此信息的已验证来源。"*
- 在括号中引用每个声明，如 `[来源：...]`。
- 永远不要回退到预训练知识。
3. **仅本地** — 服务器使用 `stdio` 传输，因此所有处理都保留在您的机器上。
---
## 📦 项目结构
| 文件 | 目的 |
|------|---------|
| `server.py` | MCP服务器 + `fetch_verified_context` 工具（FastMCP）。 |
| `crawl_worker.py` | 无头抓取工作器（Crawl4AI）在隔离的子进程中运行，用于强大的MCP stdio。 |
| `guardrail.py` | 严格的事实锚定提示模板。 |
| `text_cleaner.py` | Markdown清理 + Crawl4AI输出截断。 |
| `pyproject.toml` | 打包 + `factanchor-mcp` 控制台命令。 |
| `requirements.txt` | 依赖项（`mcp`、`ddgs`/`duckduckgo_search`、`crawl4ai`）。 |
| `claude_desktop_config.example.json` | 直接粘贴的配置片段。 |
---
## 🧰 要求
- Python **3.10+**
- Internet 访问（用于免费搜索/抓取）
## 🔧 工具参考
```
fetch_verified_context(query: str, max_results: int = 3) -> str
```
| 参数 | 默认值 | 备注 |
|-------|---------|-------|
| `query` | — | 要固定的事实主题或问题。 |
| `max_results` | `3` | 要拉取的来源（限制1-5）。 |
---
## 🐛 故障排除
- **`command not found: factanchor-mcp`** → 您使用了选项A但未运行 `pip install -e .`，或您的虚拟环境不在PATH上。使用选项B（脚本路径）代替。
- **页面仅返回短片段（首次运行）** → Chromium仍在后台安装。等待约1-2分钟后重试；后续运行是即时的。
- **Linux上“浏览器可执行文件不存在”** → 安装操作系统依赖项一次：`sudo playwright install-deps chromium`（或 `sudo apt install libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libgbm1 libasound2`）。
- **来自工具的速率限制系统提示** → DuckDuckGo正在限制免费搜索。等待几分钟后重试。服务器永远不会崩溃；它为LLM返回一个干净的系统提示。
- **客户端中未出现工具** → 在编辑配置后完全重启客户端，并在其MCP/开发者面板中检查错误。
---
## 📈 传播策略
- **前后对比视频** （X/Twitter & LinkedIn）：展示助手编造虚假的npm功能，然后启用FactAnchor-MCP并观察它正确地说 *"我无法找到此信息的已验证来源。"* 在 `@AnthropicAI` 中标记 `#MCP` 和 `#AI`。
- **开源发布**: 将其提交到 [官方MCP服务器列表](https://github.com/modelcontextprotocol/servers) 和 `awesome-mcp` 集合中。
---
## 🤝 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。保持 **零成本** 和 **本地优先**。
## 📋 成功指标（v1.0）
- ✅ **~80%** 在测试查询期间减少了虚构事实。
- ✅ **<3 分钟** 用户设置时间（克隆 → 安装 → 配置）。
- ✅ **₹0.00** 服务器维护账单。
> ⚠️ FactAnchor减少了幻觉，但并未消除它。请始终将关键声明与引用的来源进行验证。
## 📜 许可证
[MIT](LICENSE) © FactAnchor-MCP贡献者。
