Flex MCP Server

使用说明

• 项目简介
  • 该仓库实现了一个基于 MCP 的后端服务器，向客户端提供对本地知识单元（cells）的只读 SQL 查询端点，并在需要时通过向量化检索（vec_ops）与外部嵌入模型集成来提升检索能力。
  • 服务器支持多种传输方式（标准输入输出、流式 HTTP），并具备对其他单元的附加（ATTACH）与多单元查询的能力。核心逻辑围绕从本地 SQLite 表构建可查询视图、执行只读查询、以及在需要时进行向量嵌入推理。
• 主要功能点
  • MCP 协议实现：处理来自客户端的请求，返回标准的 JSON-RPC 响应，支持查询、工具调用、以及视图/元数据等功能。
  • 数据访问：对知识单元以只读方式提供数据访问，通过 SQL 直接查询。
  • 向量检索集成：通过 vec_ops（以及引擎层的嵌入模型/向量缓存）实现语义层面的检索，加速候选集筛选与排序。
  • 多单元/附加能力：支持 ATTACH 其他单元的数据库，实现跨单元查询；注册、发现、解析单元（cells）。
  • HTTP 与 STDIO 双模式：可通过命令行启动 stdio 服务器，也可开启可流式的 HTTP 服务器进行远程调用。
  • 结构化元数据与工具：提供对工具（如 flex_search）的描述、输入模式与执行策略，便于 LLM 客户端调用。
• 安装与运行步骤
  • 依赖与环境
    • 需要 Python 3.x 及相关依赖（仓库内的代码结构表明使用标准库和对 MCP、向量等组件的依赖，实际依赖安装请参考项目文档和 setup/requirements 文件）。
  • 启动方式
    • 以 STDIO 模式启动（ Claude Code 这类环境的内置管道场景）:
      • 运行命令：python -m flex.mcp_server
    • 以流式 HTTP 模式启动（对外提供可流式响应的 HTTP 接口）:
      • 运行命令：python -m flex.mcp_server --http --port 7134
    • 指定需要加载的单元（若有多单元或自定义路径）:
      • 运行命令示例：python -m flex.mcp_server --cell claude_code --cell qmem
  • 服务器配置（客户端无需了解，仅供运维/部署时的可观测信息）
    • 配置项应以 JSON 形式提供，包含以下字段（字段含义说明在括号内）：
      • server_name：Flex MCP 服务的名称，用于标识该 MCP 服务实例
      • command：启动服务器的命令或可执行路径
      • args：启动命令的参数数组，包含运行模式、端口、需要加载的单元等
    • 参考配置（文本描述，不以代码块形式呈现，便于理解）：
      • server_name: "flex-mcp"
      • command: ["python", "-m", "flex.mcp_server"]
      • args: ["--http", "--port", "7134", "--cell", "claude_code", "--cell", "qmem"] 注释：该配置表示使用 HTTP 端口 7134 启动 Flex 的 MCP 服务器，并同时加载名为 claude_code 与 qmem 的两个单元。
  • 基本使用方法
    • 启动后，客户端可以通过 MCP 协议向服务器发送读取资源、执行 SQL、调用工具等请求。
    • 如果需要进行语义检索，请使用 vec_ops/嵌入模型相关的查询路径，或通过客户端暴露的向量化方案发起查询。
    • 如遇到跨单元查询，请确保已通过 ATTACH 方式将相关单元附加到会话中，并遵循服务器对于只读查询的限制。
• 注意事项
  • 服务器本质上是只读 SQL 端点，避免对知识库进行写操作。
  • 若要在生产环境中使用，请确保网络和身份认证的安全性，参考仓库对 Authorizer 与端口暴露的设置。