MCP¶

供调用方参考。适用于支持 MCP 的 AI 应用直接调用检索、受约束生成和图片隐患识别功能。

入口¶

http://127.0.0.1:8864/cg-rag/mcp/

MCP 客户端配置示例：

{
  "mcpServers": {
    "CG_RAG": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8864/cg-rag/mcp/"
    }
  }
}

工具总览¶

工具	参数	用途
`cg_health`	无	返回健康状态、active scope、profile、rerank 和 LLM 配置摘要
`cg_list_profiles`	无	返回可用检索范围
`cg_retrieve_rerank`	`query`, `scope`, `topk`	仅执行 retrieve + rerank
`cg_constrained_generate`	`query`, `retrieval_docs`, `max_items`, `include_debug`, `generation_enable_thinking`	基于候选文档执行受约束生成
`cg_rag`	`query`, `scope`, `topk`, `max_items`, `include_debug`, `generation_enable_thinking`	执行完整 retrieve + rerank + constrained generation
`cg_vision_answer`	`images`, `question`, `enable_thinking`	自由生成：直接根据图片识别隐患，不检索、不带引用
`cg_vision_observe`	`images`, `question`	结构化视觉观察：返回校验过的隐患标签与展示文本
`cg_vision_agentic`	`images`, `question`, `scope`, `max_search_rounds`, `topk`, `enable_thinking`	智能生成：模型自行检索法规，输出带 `[cite^n]` 引用的隐患判定
`cg_vision_hybrid`	`images`, `question`, `scope`, `max_search_rounds`, `enable_thinking`	垂域+RAG：千问先写描述，DeepSeek 再检索。`topk` 固定为 12，不作为参数

MCP 工具返回统一的基础 envelope。成功调用时还会附带 operation_ok：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {}
}

字段含义：

ok 表示 MCP 工具调用、参数校验及服务调用是否成功。
operation_ok 表示 CG_RAG 业务操作是否成功，仅在 ok: true 的成功调用 envelope 中出现。
data 为对应 HTTP API 的业务返回。
error 仅在 ok: false 时出现；此时 data 为空且不含 operation_ok。

失败 envelope 示例：

{
  "ok": false,
  "message": "服务当前请求过多，请稍后重试。",
  "data": {},
  "error": {
    "code": "capacity.exceeded",
    "message": "服务当前请求过多，请稍后重试。",
    "details": {"resource":"retrieval","max":16,"wait_timeout_seconds":5.0}
  }
}

MCP 工具当前返回 JSON 结果，不直接暴露 SSE token 流。如需动态流式输出，请使用 HTTP /cg-rag/rag/stream 或 /cg-rag/vision/*/stream。

cg_health¶

工具输入为空：

{}

示例输出，已删减：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {
    "ok": true,
    "service": "CG_RAG",
    "available_scopes": ["full", "usual", "usual_plus_law"],
    "active_scope": "full",
    "generation": {
      "configured": true,
      "provider": "deepseek",
      "model": "deepseek-v4-flash",
      "enable_thinking": false,
      "streaming": true
    },
    "rerank": {
      "api_enabled": false,
      "model": "qwen-rerank"
    }
  }
}

cg_list_profiles¶

工具输入为空：

{}

示例输出，已删减：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {
    "profiles": {
      "full": {
        "label": "全库",
        "retrieval_method": "qwen3-0.6b"
      },
      "usual": {
        "label": "常用规范",
        "retrieval_method": "qwen3-0.6b"
      }
    }
  }
}

cg_retrieve_rerank¶

工具输入：

{
  "query": "脚手架验收需要检查哪些条文？",
  "scope": "full",
  "topk": 2
}

示例输出，已删减：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {
    "query": "脚手架验收需要检查哪些条文？",
    "num_docs": 2,
    "topk": 2,
    "cache": {
      "hit": false
    },
    "retrieval_docs": [
      {
        "law_name": "GB55023-2022施工脚手架通用规范",
        "article_number": "6.0.5(1)",
        "contents": "脚手架搭设达到设计高度或安装就位后，应进行验收，验收不合格的，不得使用。"
      }
    ]
  }
}

cg_constrained_generate¶

工具输入：

{
  "query": "脚手架验收需要检查哪些条文？",
  "max_items": 2,
  "include_debug": false,
  "generation_enable_thinking": false,
  "retrieval_docs": [
    {
      "law_name": "GB55023-2022施工脚手架通用规范",
      "article_number": "6.0.5(1)",
      "contents": "脚手架搭设达到设计高度或安装就位后，应进行验收，验收不合格的，不得使用。"
    }
  ]
}

示例输出，已删减：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {
    "ok": true,
    "generation_mode": "constrained",
    "answer_text": "我根据在线检索与候选筛选结果，整理出以下最相关条文：\n1. GB55023-2022施工脚手架通用规范 6.0.5(1)",
    "pred_indices": [1],
    "pred_items": [
      "GB55023-2022施工脚手架通用规范 6.0.5(1)"
    ],
    "pred_raw": "{\"indices\":[1]}",
    "thinking": "",
    "generation_enable_thinking": false
  }
}

cg_rag¶

工具输入：

{
  "query": "脚手架验收需要检查哪些条文？",
  "scope": "full",
  "topk": 20,
  "max_items": 5,
  "include_debug": false,
  "generation_enable_thinking": false
}

示例输出，已删减：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {
    "query": "脚手架验收需要检查哪些条文？",
    "retrieval": {
      "num_docs": 20,
      "cache": {
        "hit": false
      }
    },
    "generation": {
      "ok": true,
      "generation_mode": "constrained",
      "answer_text": "我根据在线检索与候选筛选结果，整理出以下最相关条文：\n1. GB55023-2022施工脚手架通用规范 6.0.5(1)",
      "pred_indices": [1],
      "pred_items": [
        "GB55023-2022施工脚手架通用规范 6.0.5(1)"
      ]
    }
  }
}

cg_vision_answer¶

工具输入（data 为图片 base64，可用 data:<mime>;base64, 形式的 data URL）：

{
  "images": [
    {"data": "<base64>", "mime_type": "image/jpeg"}
  ],
  "question": "请检测图中的安全隐患"
}

示例输出，已删减：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {
    "ok": true,
    "mode": "free_form",
    "answer": "隐患等级：一般隐患\n\n隐患描述：\n1. 脚手架基础区域存在明显积水。\n\n整改措施和建议：\n1. 立即排除积水并设置排水设施。",
    "image_count": 1,
    "citations": [],
    "retrieval_docs": []
  }
}

cg_vision_agentic¶

工具输入：

{
  "images": [
    {"data": "<base64>", "mime_type": "image/jpeg"}
  ],
  "question": "请检测图中的安全隐患",
  "scope": "full",
  "topk": 12
}

示例输出，已删减：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {
    "ok": true,
    "mode": "agentic",
    "answer": "## 隐患等级\n重大事故隐患\n\n## 隐患判定依据\n1. ……不应有积水 [cite^2]。",
    "citations": [2],
    "retrieval_docs": [
      {
        "law_name": "GB55023-2022施工脚手架通用规范",
        "article_number": "2.0.1",
        "contents": "脚手架性能应符合下列规定……"
      }
    ],
    "scene_status": "assessable",
    "scope": "full",
    "warnings": []
  }
}

图片张数、体积上限、隐患等级取值和错误码见视觉隐患识别。

错误和业务失败¶

MCP 中业务失败通常表现为 ok: true、operation_ok: false，业务错误置于 data.error 或 data.generation.error 中。参数校验失败或工具异常时才返回 ok: false。

示例：

{
  "ok": true,
  "operation_ok": false,
  "message": "CG_RAG 业务操作失败",
  "data": {
    "ok": false,
    "error": {
      "code": "generation_not_configured",
      "message": "CG_RAG 生成接口未配置，请设置 CG_RAG_GENERATION_ENDPOINT 和 CG_RAG_GENERATION_MODEL。",
      "details": {}
    },
    "pred_indices": [],
    "pred_items": [],
    "pred_raw": ""
  }
}

集成建议¶

仅需候选文档时使用 cg_retrieve_rerank，勿调用完整 cg_rag 后丢弃 generation 结果。
调用完整 RAG 时应优先检查 operation_ok 与 data.generation.ok。
生产调用建议显式传入 scope、topk 和 max_items。
常规服务调用保持 include_debug: false，仅在调试阶段短期开启。
MCP task 取消会传播到服务 cancellation context；容量耗尽时 ok=false 且错误码为 capacity.exceeded。
MCP 返回完整 JSON envelope，不提供 token stream；如需 SSE，请改用 HTTP /cg-rag/rag/stream 或 /cg-rag/vision/*/stream。
视觉工具的失败（未配置、图片非法、上游错误）以 ok: false 及 vision_not_configured / invalid_image / vision_upstream_error 等错误码返回。
批量筛查使用 cg_vision_answer，仅对需要出具法规依据的图片调用 cg_vision_agentic，以避免对每张图片均产生多轮检索开销。

inbound_token / path_ids（2026-09-29）¶

cg_rag.inbound_token（secrets）/ CG_RAG_INBOUND_TOKEN：入站 Bearer。
cg_rag.expose_docs / CG_RAG_EXPOSE_DOCS：默认 false。
CG_RAG_REQUIRE_INBOUND_AUTH、CG_RAG_STRICT_CONFIG_CONFLICTS：严格启动开关，默认关。
health/profiles 的 path_ids：sha256(os.path.realpath(path))[:16]；测试向量 compute_path_id("/data/x") == "e220a107e93688b1"。