+ 发布产品

cortrix-mcp Skill 技能

IDE AI 编程助手的 31 工具 MCP Server

AI编程开发
查看 Skill ↗
认领产品

cortrix-mcp 是面向 IDE AI 编程代理（Claude Code / Cline / Cursor）的 MCP Server，把 Cortrix 语义存储 HTTP 服务暴露为 31 个 MCP 工具（29 个核心 + 2 个 admin），让 Agent 可以直接在 IDE 里索引文档、跑混合语义搜索、管理会话记忆、触发 admin 数据库导入。它构建在官方 MCP Python SDK v2 的 MCPServer + httpx 之上，纯 stdio 传输，HTTP 直连 cortrix-server（不绕 Python SDK）。

核心能力

  • 31 个 MCP 工具（按职责分组）：核心 12 个（cortrix_health / query / upload / list_documents / list_namespaces / create_namespace / memory_search / log_interaction / list_interactions / document_status / add_watcher / list_watchers）、扩展 4 个（跨命名空间查询、异步上传、过滤检索、提取触发）、Memory & 运维 9 个（审计、撤销事实、opt-out、批量提交、运维列表、记忆 CRUD）、Admin 2 个（数据库凭证注册、admin db_import_run，需 role=admin）。
  • 现代 + 旧版 MCP 协议双兼容：现代 2026-07-28 通过 server/discover，旧版 2025-11-25 通过 initialize 握手，沿用协议版本协商。
  • 结构化响应封装：所有 tool 返回 data + meta 两层信封，structured_data 含 trace_id / session_id / coverage_ratio，便于 Agent 推理重试与数据完整性。
  • 6 类稳定错误码：CX_ERR_MCP_BACKEND_TIMEOUT（重试 / 1s）、CX_ERR_MCP_BACKEND_UNAVAILABLE（重试 / 5s）、SCHEMA_VALIDATION_FAIL（不重试）、TOOL_NOT_FOUND（不重试）、AUTH_MISSING（不重试）、ADMIN_REQUIRED（不重试），错误归类稳定不漂移。
  • 可观测性：每个 backend 请求携带 X-Session-Id / X-Trace-Id / X-Agent-Id，可通过 GET /api/v1/traces/{session_id} 反向查询；cortrix-server 端会自动 adopt 这些 id 做服务端 trace。
  • 三种 MCP 客户端原生支持：Claude Code（~/.config/Claude/claude_desktop_config.json）、Cline（VS Code cline_mcp_settings.json）、Cursor（~/.cursor/mcp.json）均提供现成 JSON 片段。
  • Docker 镜像：发布到 cortrix/mcp:v1.0.0-rc.2，用 -e CORTRIX_URL=... -e CORTRIX_API_KEY=... 即可拉起，无需 Python 环境。

安装配置

  • pip 安装：pip install cortrix-mcp，自动安装 cortrix-mcp console 命令作为 stdio server 入口。
  • Docker 安装：docker run -i --rm -e CORTRIX_URL=http://host.docker.internal:8420 -e CORTRIX_API_KEY=your-cortrix-api-key cortrix/mcp:v1.0.0-rc.2，适合无 Python 环境。
  • 环境变量配置：CORTRIX_URL（cortrix-server base URL，默认 http://127.0.0.1:8420）、CORTRIX_NAMESPACE（默认 namespace）、CORTRIX_API_KEY（Bearer token）、CORTRIX_MCP_ADMIN（启用 admin 工具，默认 false）、CORTRIX_MCP_TIMEOUT（HTTP 超时秒数，默认 30）、CORTRIX_AGENT_ID（X-Agent-Id，charset [A-Za-z0-9_.:/-]，max 128 chars）。
  • MCP 客户端注册：把 cortrix-mcp 命令（或 docker run args）写入 Claude Code / Cline / Cursor 的 MCP 配置文件，重启客户端即生效。
  • 认证与租户隔离：租户 / 成员 / ACL / 配额 / RBAC / 租户隔离行为须对照 docs/compatibility.md 验证后再做生产 / 安全声明。
  • 协议兼容：Python 依赖 mcp>=2.0.0,<3.0.0；现代协议 2026-07-28、旧版 2025-11-25。

使用步骤

  1. 部署 cortrix-server：先在本地或远端跑起 cortrix-server（默认监听 127.0.0.1:8420），准备好 API Key。
  2. 安装 cortrix-mcp：pip install cortrix-mcp 或拉 Docker 镜像 cortrix/mcp:v1.0.0-rc.2。
  3. 注册到 MCP 客户端：在 Claude Code 的 claude_desktop_config.json（或 Cline / Cursor 的对应文件）里加一段 mcpServers.cortrix 配置，包含 command + env（含 CORTRIX_URL / CORTRIX_API_KEY），重启客户端。
  4. 健康检查：Claude Code 里直接调用 cortrix_health 验证 server 可达；若返回 BACKEND_UNAVAILABLE 错误码，按 retry_after_ms 提示等 5 秒重试。
  5. 检索 / 上传 / 命名空间：用 cortrix_query / cortrix_upload / cortrix_list_documents / cortrix_create_namespace 等核心工具开始索引与查询；跨命名空间用 cortrix_cross_ns_query、异步上传用 cortrix_async_upload。
  6. 记忆管理：用 cortrix_memory_* 系列工具做 session 记忆写入 / 检索 / 审计 / 撤销；MEM02 memory extraction 当前在最新公开基线里为 Blocked（runtime 验证发现 LLM transport 超时路径），用前查 Compatibility 文档。
  7. 运维操作：watcher / 批量提交 / 运维列表用对应工具；admin 工具（cortrix_admin_db_*）需服务端接受 role=admin 调用方身份才能调用。
  8. 追踪调试：每次返回的 meta.structured_data 里有 trace_id / session_id，可通过 GET /api/v1/traces/{session_id} 反查 cortrix-server 端日志。

适用场景

  • IDE 内 AI 编程 + 知识库检索一体化：在 Claude Code / Cline / Cursor 中直接调 cortrix_query 索引项目文档、设计稿、规范，避免复制粘贴。
  • 多命名空间知识管理：用 create_namespace / cross_ns_query 隔离不同项目 / 客户的语料，跨项目检索用扩展工具。
  • AI Agent 会话记忆持久化：log_interaction + memory_* 系列工具把 Agent 的关键对话 / 决策写入可审计、可撤销的语义存储。
  • 文档自动化监控：add_watcher / list_watchers + document_status 跟踪文档上传与索引状态；upload / async_upload 选同步或异步路径。
  • 生产级运维 / 排错：6 类稳定错误码 + trace_id 反查让生产排错流程可工程化，不用猜测 agent 看到的失败原因。
  • 多 MCP 客户端统一接入：一份 cortrix-mcp 同时服务 Claude Code + Cline + Cursor + 其他 stdio MCP 客户端。
  • Docker 化部署：通过 cortrix/mcp:v1.0.0-rc.2 镜像在 K8s / 容器平台批量下发，无需宿主机 Python 环境。

适用人群

  • 在 IDE 里重度使用 Claude Code / Cline / Cursor 的资深开发者
  • 维护多项目 / 多命名空间知识库的技术 Lead
  • 想给 AI 编程助手接「持久记忆 + 可审计操作」的工程团队
  • 关注可观测性（trace_id / session_id）和错误归类稳定性的生产用户
  • 偏 stdio MCP 传输 + 自托管的企业 / 内网环境

工作原理

cortrix-mcp 跑在 stdio 传输上（不暴露远程或 loopback Streamable HTTP），用官方 MCP Python SDK v2 的 MCPServer + httpx 直连 cortrix-server HTTP API（默认 :8420）。每个 MCP tool 的实现都走 31 个不同的 REST 端点，请求带上 X-Session-Id / X-Trace-Id / X-Agent-Id 三件套，cortrix-server 端自动 adopt；响应统一走 data + meta 双层信封，meta.structured_data 含 trace_id / session_id / coverage_ratio。协议协商支持现代 2026-07-28（server/discover）与旧版 2025-11-25（initialize 握手）双轨；错误码分 6 类稳定编码（timeout / unavailable / schema / not-found / auth / admin），Agent 可据此判断是否重试或绕路。Admin 工具额外要求 role=admin 身份，由服务端判定是否放行。

官方链接

cortrix-mcp 网站预览

团队信息

AI产品库 官方
由 AI 猎手自动发现

评论与建议

0 条评论