HCE MCP 服务器

使用说明（简明易懂，含关键点）：

• 项目简介

  • 该仓库实现一个基于 MCP 的服务端，用于将 HCE 的记忆能力暴露给 LLM 客户端，允许查询、存储记忆、爬取代码库、搜索图谱等功能，通过标准的 MCP 工具接口进行交互。
  • 支持三大核心能力：资源管理（实体图、树形记忆、焦点缓冲等数据结构）、工具注册与执行（如 hce_status、hce_retrieve_context、hce_store_interaction、hce_crawl_project、hce_search_graph、hce_clear_memory 等），以及通过上下文模板/提示构建增强的对话能力。

• 主要功能点

  • MCP 服务器核心功能：通过 JSON-RPC 风格的接口暴露工具，客户端可请求读取资源、执行工具、获取并渲染 Prompt 模板等。
  • 资源与数据管理：维护 EntityGraph（实体图）、SemanticTree（树状记忆）和 SlidingFocusBuffer（短期上下文）。
  • 工具集成与执行：hce_status、hce_retrieve_context、hce_store_interaction、hce_crawl_project、hce_search_graph、hce_clear_memory 等工具，用于查询内存状态、检索上下文、持久化存储、爬取代码库、图谱检索和内存清空等操作。
  • 会话与持久化：支持会话管理、状态持久化到磁盘、并发安全（通过文件锁保护状态目录）。
  • 多传输协议与安全性：当前实现以 stdio 传输为 MCP 客户端提供 JSON-RPC 接口，日志输出到标准错误，避免污染协议流。

• 安装与运行步骤

  • 环境准备：需要 Python 3.x 环境，安装项目依赖（如 MCP 库及本项目所需的 Python 包）。
  • 启动服务器：在命令行中执行 python hce_mcp_server.py 即可启动，服务器通过标准输入输出与 MCP 客户端通信，日志输出到标准错误。
  • 验证运行：启动后客户端可以通过 MCP 调用已注册的工具，如查询内存状态、检索上下文、爬取代码库等。

• 服务器配置（MCP 客户端连接使用的配置说明） 说明：MCP 客户端需要一个配置来知道如何启动并连接到 MCP 服务器。下面给出配置字段及示例含义（为便于理解，以文本描述JSON字段，不提供实际代码块）：

  • server_name：服务器名称，标识该 MCP 服务的名称，例如 "HCE MCP Server"。
  • command：启动服务器所用的命令，例如 "python"。
  • args：命令参数，提供启动脚本及必要参数，例如 ["hce_mcp_server.py"]。
  • transport（可选，若客户端支持多传输协议时可确认）：默认使用 stdio 传输。 注：该配置用于 MCP 客户端在本地启动与服务器的对接，实际运行时不需要将此配置写入服务器端代码中，只需客户端按该信息启动并连接即可。

• 基本使用方法

  • 启动后，MCP 客户端可以调用已注册的工具以完成以下场景：
    • hce_status：查看当前内存结构的状态与统计信息。
    • hce_retrieve_context：在回答问题前检索相关上下文（三大结构的记忆）。
    • hce_store_interaction：将有意义的对话存入记忆（焦点、树状记忆、实体图）。
    • hce_crawl_project：对指定代码库进行爬取并合并到现有图谱中。
    • hce_search_graph：基于图谱的扩展检索与相似性分析。
    • hce_clear_memory：重置内存状态与持久化数据。
  • 常见工作流程：启动服务器 → 使用客户端请求 hce_status 或检索上下文 → 进行对话并通过 wrap/chat 机制将对话写入内存 → 持久化状态以便跨会话恢复。

• 备注

  • 该实现包含大量单元测试，覆盖 EntityGraph、SemanticTree、EntityExtractor、Project Crawler、MCP 服务端工具等各个方面，能较全面地验证功能正确性。
  • MCP 客户端与服务器之间的协议细节由提供的 FastMCP 库负责实现，服务器端实现确保暴露的工具具有明确的输入输出约束与安全的并发控制。