HCE MCP 服务器端

使用说明（Markdown 格式）

• 项目简介

  • 该项目实现了一个 MCP 服务器端，用于向 LLM 客户端提供可托管的资源（如记忆与数据）、可注册执行的工具，以及可渲染的 Prompt 模板。服务器通过 JSON-RPC 协议与客户端通信，支持多种传输模式，并对会话、能力声明及内存管理等提供完整实现。

• 主要功能点

  • hce_status：查看当前内存系统的状态与结构拆分（实体图、语义树、焦点缓冲区等）。
  • hce_store_interaction：将用户对话存入三大记忆结构，支持持续保存与跨会话使用。
  • hce_retrieve_context：基于图、树、缓冲区的检索，返回适合嵌入 Prompt 的上下文片段。
  • hce_crawl_project：对代码库进行 Crawling，建立 FILE/FUNCTION/CONCEPT 节点及 IMPORTS/CALLS/PART_OF 等边，支持多语言解析。
  • hce_search_graph：基于扩散激活对图中节点进行查询并返回相关实体及分数。
  • hce_clear_memory：清空三大内存结构并清除持久化状态。
  • 通过装饰器 @mcp.tool() 将上述函数暴露为 MCP 工具，客户端可通过调用这些工具实现对后端内存的管理与查询。
  • 流式传输方面，该服务器设置了日志输出到标准错误，确保 JSON-RPC 流不被日志污染。

• 安装步骤

  • 将仓库克隆到本地或服务器环境。
  • 安装依赖（如 Python 环境、所需库）。确保能够导入 hce_core、hce_pipeline、project_crawler、semantic_tree、entity_extractor 等模块。
  • 直接运行 hce_mcp_server.py 文件即可启动 MCP 服务器，默认使用标准输入输出（stdio）作为传输通道。

• 服务器配置（MCP 客户端使用的启动信息，JSON 格式，包含 server name、command、args 等）

  • 说明：MCP 客户端通常需要知道如何启动服务器进程以及连接方式。本实现的 MCP 服务器默认通过标准输入输出进行 JSON-RPC 通讯，启动时不必额外传入参数即可工作。下面给出一个准确描述性的配置示例（以便客户端参考），实际运行时客户端会直接启动服务器进程并建立通信通道。
  • 配置示例（JSON，注释性说明在文本中给出，实际使用时以纯 JSON 为准）: { "server_name": "HCE Memory MCP Server", "command": "python", "args": ["hce_mcp_server.py"], "transport": "stdio", "notes": "服务器通过标准输入输出(JSON-RPC)进行通信。若需要将传输改为其他通道，请参考 mcp 库的部署方式。" }

• 基本使用方法

  • 启动服务器后，MCP 客户端可以通过发送 JSON-RPC 请求来调用暴露的工具，如查询状态、存储对话、检索上下文等。
  • 客户端应遵循 MCP 协议规范构造请求并解析响应。服务器端会返回 JSON-RPC 响应，或在必要时返回错误信息。
  • 日志输出与错误处理将写入标准错误，以确保 protocol 流稳定。

• 运行与调试要点

  • 服务器默认使用 stdio 传输模式，确保客户端在同一进程或管道中与服务器进行交互。
  • 对持久化状态的访问受锁机制保护，防止并发写入导致的数据不一致。
  • 代码中已经为单元测试提供了完整的接口覆盖，包含状态展示、上下文检索、爬虫及内存清理等功能。