HallucC MCP Server

把 HallucC 的检测能力以 MCP（Model Context Protocol） 工具暴露给 Claude / Cursor / Claude Desktop 等客户端，零配置接入。

架构：薄代理（thin proxy）——本服务用官方 @modelcontextprotocol/sdk (TypeScript) 实现，不复制任何检测逻辑，只把客户端请求原样转发到现有 HallucC FastAPI 后端（server.py @ :8001）。鉴权走每用户 API key，额度与 Web 端同源（同一 key = 同一账号额度）。

工具集（4 个）

工具	后端端点	作用	耗额度
verify_text	POST /detect	逐声明幻觉核验：返回红/黄/绿汇总 + 每条声明 status/confidence/reason/sources + citations	✅ detect
verify_agent	POST /detect-agent	agent 最终输出文本级核验 + 执行轨迹六维评估（事实性/来源/指令合规/工具声明一致/任务完成/反思）	✅ detect
check_cua_actions	POST /cua/classify	Computer-Use Agent 动作风险分级 L0-L3（纯规则，无 LLM）	❌ 不耗
check_safety	POST /guard/check（fast=true → /guard/check-fast）	40+ 特征安全网关：Prompt 注入 / 越狱 / 有害内容 / 敏感信息泄露 / 欺诈	✅ detect

鉴权模型：客户端在各自机器配 Authorization: Bearer <你的 HallucC API key> 头 → server 提取并原样透传到后端 → 后端校验 + 扣同一账号额度。key 只在 HTTP 头里流转，不进工具参数、不进模型 transcript。

公网接入（推荐，无需本地运行）

MCP server 已部署在 https://aihcc.cloud/mcp（nginx → 本机 8787，TLS 由 nginx 终止）。客户端直接配公网地址 + 个人 API key 即可：

# Claude Code
claude mcp add --transport http hallucc https://aihcc.cloud/mcp \
  --header "Authorization: Bearer <你的 HallucC API key>"

Cursor / Claude Desktop 同理，URL 填 https://aihcc.cloud/mcp，Headers 加 Authorization: Bearer <key>。API key 在 https://aihcc.cloud 注册后于 /keys 页创建，免费套餐每日有额度。

本地运行

# 1. 装依赖（已装可跳过）
npm install

# 2.（可选）配置后端地址与端口；默认指向本机 8001
cp .env.example .env
#   HALLUCC_BASE_URL=http://127.0.0.1:8001
#   PORT=8787

# 3. 确保后端在跑：curl http://127.0.0.1:8001/health
# 4. 起 MCP server（dev 热重载）
npm run dev
# 或生产：npm start

服务监听 http://127.0.0.1:8787/mcp，健康检查 GET /health。

客户端接入

Claude Code（CLI）

# remote HTTP transport，带个人 key 头
claude mcp add --transport http hallucc http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer <你的 HallucC API key>"

# 验证
claude mcp list
# 在对话里调用：让 Claude 核验一段文本的幻觉 / 检测一段 prompt 的注入风险

Cursor

Settings → MCP → Add MCP server：

• Type: http
• URL: http://127.0.0.1:8787/mcp
• Headers: {"Authorization": "Bearer <你的 HallucC API key>"}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "hallucc": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer <你的 HallucC API key>" }
    }
  }
}

MCP Inspector（调试 / 不带额度也能测工具列表与鉴权）

npx @modelcontextprotocol/inspector
# 选 Streamable HTTP，URL 填 http://localhost:8787/mcp
# Custom Headers 加 Authorization: Bearer <key>

鉴权与额度

• 无 Authorization 头或 key 无效 → MCP 层返回 401 JSON-RPC 错误。
• key 有效但额度耗尽 → 后端返回 429，server 映射成「免费额度已用完，请明天重置或升级套餐」。
• 每个工具响应里的 quota 对象 = 后端 quota_status，与 Web 仪表盘同源、随调用递减。
• check_cua_actions 是纯规则，不调 LLM、不耗额度，可放心高频调用。

项目结构

src/
  server.ts     Express + StreamableHTTP transport（stateless）+ 鉴权中间件 + 注册工具
  context.ts    配置加载 + API key 提取
  backend.ts    BackendClient（透传 key、统一 401/429/5xx 错误映射）+ toMcpResult
  schemas.ts    4 工具 zod 输入 schema（约束对齐后端 Pydantic Field）
  tools/
    verifyText.ts       → /detect
    verifyAgent.ts      → /detect-agent
    checkCuaActions.ts  → /cua/classify
    checkSafety.ts      → /guard/check（fast → /guard/check-fast）
    index.ts            registerAllTools

传输

Streamable HTTP（当前 MCP 规范推荐的 remote 传输，即「HTTP+SSE」），stateless 模式：每个 POST 新建 transport + McpServer，处理完即关。Claude Code / Cursor / Claude Desktop 均原生支持。后续若要兼容只认旧版 SSE 的客户端，加 SSEServerTransport（双端点 /sse + /messages）即可。