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	基于候选文档做受约束生成
cg_rag	query, scope, topk, max_items, include_debug	执行完整 retrieve + rerank + constrained generation

MCP 工具统一返回 envelope：

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

字段含义：

• ok 表示 MCP 工具调用、参数校验和服务调用是否成功。
• operation_ok 表示 CG_RAG 业务操作是否成功。
• data 是对应 HTTP API 的业务返回。
• error 只在 ok: false 时出现。

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,
      "model": "deepseek-chat",
      "enable_thinking": false
    },
    "rerank": {
      "api_enabled": false,
      "model": "qwen-rerank"
    }
  }
}

cg_list_profiles

工具输入为空：

{}

示例输出，已删减：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {
    "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,
  "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": "GB55023-2022施工脚手架通用规范 6.0.5(1)",
    "pred_indices": [1],
    "pred_items": [
      "GB55023-2022施工脚手架通用规范 6.0.5(1)"
    ],
    "pred_raw": "{\"indices\":[1]}",
    "thinking": ""
  }
}

cg_rag

工具输入：

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

示例输出，已删减：

{
  "ok": true,
  "operation_ok": true,
  "message": "",
  "data": {
    "query": "脚手架验收需要检查哪些条文？",
    "retrieval": {
      "num_docs": 20,
      "cache": {
        "hit": false
      }
    },
    "generation": {
      "ok": true,
      "generation_mode": "constrained",
      "answer_text": "GB55023-2022施工脚手架通用规范 6.0.5(1)",
      "pred_indices": [1],
      "pred_items": [
        "GB55023-2022施工脚手架通用规范 6.0.5(1)"
      ]
    }
  }
}

错误和业务失败

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，只在调试时短期开启。