GZOO Cortex MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • Cortex 的 MCP 服务器实现，作为后端服务端提供资源管理、工具注册与执行、以及提示模板渲染等能力，便于 LLM 客户端（如 Claude Code 等）以标准化方式获取上下文信息和功能。

• 主要功能点

  • 通过 MCP 协议暴露一组工具（如获取状态、列出项目、查询实体、执行查询、纠正/解决对比等），支持 LLM 客户端直接调用。
  • 与本地存储（SQLite）和向量检索（向量存储）整合，能够对知识图谱进行查询、扩展和关系推断。
  • 具备会话管理、能力声明、以及对传输通道的适配（MCP 常用的 stdio 传输场景）。
  • 与 Cortex 的核心组件（核心模型、路由、错误处理、事件总线）协同工作，能够在 MCP 层触发事件并记录调用轨迹。

• 安装步骤

  • 获取代码并安装依赖（在包含 MCP 模块的根目录或相应子包中执行 npm install）。
  • 构建 MCP 模块，使 dist 输出可执行 JS 文件。
  • 通过环境变量配置 Cortex 配置目录，例如设置 CORTEX_CONFIG_DIR 指向 Cortex 的 cortex.config.json 所在目录。
  • 启动 MCP 服务器时，按照客户端约定的方式提供启动命令（下文有配置示例）。

• 服务器配置（MCP 客户端配置示例说明） MCP 客户端连接本 MCP 服务器时，通常需要指定服务器名称、启动命令与参数。以下为示意性的配置字段说明；实际使用以客户端工具要求为准。

  • serverName: cortex
  • command: node /path/to/packages/mcp/dist/index.js
  • args: []（若需传入额外参数，可在此列出） 注：MCP 客户端通常需要通过环境变量 CORTEX_CONFIG_DIR 指定 Cortex 的配置目录，确保服务器能够加载正确的系统配置与数据源。配置示例仅用于帮助理解启动信息，不需要在 MCP 客户端执行的实际调用中暴露具体实现细节。

• 基本使用方法

  • 启动与连接
    • 通过正确的启动命令启动 MCP 服务器（如 node /path/to/packages/mcp/dist/index.js），并确保环境变量 CORTEX_CONFIG_DIR 指向 Cortex 的配置目录。
    • 在 Claude Code 等 MCP 客户端中将服务器注册为一个新的 MCP 服务端，使用服务器名称 cortex（如 README 中的示例），并指定启动命令路径。
  • 调用与交互
    • 使用 MCP 客户端向服务器发送 JSON-RPC 请求来调用注册的工具（如 get_status、list_projects、find_entity、query_cortex 等）。
    • 服务器按工具定义执行对应的逻辑，返回结构化的 JSON-RPC 响应，以及必要的上下文信息与状态数据。
  • 事件与日志
    • 通过事件总线（EventBus）实现的系统事件在 MCP 层也能被记录与触发，便于与外部系统进行集成与监控。