MCP 工具

本文描述 CG_RAG 的 Streamable HTTP MCP 入口和工具。MCP 适合让支持 MCP 的 AI app 或 agent 服务直接调用 CG_RAG 的 retrieve、rerank、constrained generation 和图片隐患识别能力。

入口

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] 引用的隐患判定

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，避免每张图都付多轮检索成本。