axel-backend

使用说明（简明可操作版）

• 项目简介

  • 这是一个面向“LLM 上下文服务”的 MCP 服务器实现，包含资源、工具、Prompts 的管理与执行能力，并提供多种传输方式（如 SSE、stdio）供 MCP 客户端接入。
  • 服务器核心职责包括：托管资源、注册与执行外部工具、定义和渲染 Prompt 模板、会话管理与记忆体系的集成，以及对外暴露的 MCP 接口。

• 主要功能点（要点清晰，便于理解）

  • MCP 服务器核心：提供工具、资源、Prompts 的注册、查询与执行能力，支持工具调用、资源读取、提示模板获取等 MCP 请求的处理。
  • 工具与资源注册：通过装饰器方式注册工具，维护工具的 schemas、输入输出以及执行统计，支持工具的同步/异步执行和部分工具的后台执行（Deferred）。
  • 会话与记忆系统：整合 Working Memory、Session Archive、Long-Term Memory、Knowledge Graph 等，提供上下文组装、史料检索、以及跨会话的记忆管理。
  • Prompts 管理与渲染：通过 Context Optimizer 等组件，将系统提示、工作内存、长期记忆、代码上下文等内容组成最终的提示文本，提供可配置的分区预算与截断策略。
  • MCP 传输与协议：实现 MCP 的服务端逻辑，提供 SSE 传输和 stdio 模式，能够与 MCP 客户端进行 JSON-RPC 风格的请求/响应通信。
  • 容错与鲁棒性：实现断路器、重试、限流、缓存等模式，提升对外部 LLM 提示/工具调用的稳定性。
  • 本地与外部依赖：包含对 Gemini/LMM 的对接封装、对向外部 API 的请求池、以及对本地内存与图数据库（ChromaDB、SQLite 等）的操作封装。

• 安装步骤（简化流程）

  1. 克隆仓库并进入项目目录
  2. 配置环境变量（如 GEMINI_API_KEY、AXNMIHN_API_KEY、MCP 服务器端口等）
  3. 安装依赖并初始化环境
  4. 启动 MCP 服务器（SSE/stdio 模式可选），以及主 FastAPI 后端服务
  5. 根据需要配置系统服务（如 systemd 用户服务）以实现自启动

• 服务器配置（MCP 客户端使用，示例说明，不包含代码） 说明：MCP 客户端需要的配置信息用于连接与交互。以下为描述性 JSON 配置要素要如何设定（请按实际环境填充，不作为代码块）：

  • serverName: "axel-mcp-server"（MCP 服务器名称，用于标识目标 MCP 服务）
  • transport: "sse"（传输模式，SSE 为主流选择；若使用 stdio，请配置为 "stdio"）
  • host: "0.0.0.0"
  • port: 8555
  • mcpEndpoint: "/sse"（若使用 SSE 传输，则暴露的 Signal/消息端点）
  • mcpInitParams: 可以包含连接初始参数，例如：
    • timeout: 30
    • maxRetries: 3
  • authentication: 例如需要的 API KEY/令牌（如 AXNMIHN_API_KEY、GEMINI_API_KEY 等），若不需要可留空
  • toolsConfig: 工具注册相关信息（通常由服务端维护，客户端可查询工具列表与输入 schemas）
  • memoryConfig: 会话记忆与上下文预算相关参数（由服务端默认配置控制，客户端通常不需要修改）

  说明要点：

  • MCP 客户端在首次连接后会获取工具、资源、Prompts 等元数据，用以构造调用请求。
  • 配置要尽量贴合服务端暴露的能力，例如避免请求超时过短、确保工具数量与外部 API 限流策略相匹配。

• 基本使用方法（步骤清晰，便于上手）

  • 启动后端服务与 MCP 服务，客户端通过指定的服务器地址进行连接。
  • 客户端可向 MCP 服务发起读取资源、调用工具、获取 Prompts 等请求。
  • MCP 服务端会返回 JSON-RPC 风格的响应，或通过 SSE 的实时流输送内容。
  • 开发者可通过注册的工具接口在 MCP 服务端扩展能力，增加新的资源与工具。

• 运行与开发要点

  • 确认通信端口与传输协议设置正确（SSE vs stdio）。 选择合适的模型与嵌入模型，在缺省配置下，Gemini3/Gemini Embedding 适配即可启动。 请注意：客户端需要的具体请求格式、工具调用参数等，需参考服务端暴露的 Tool Schemas 与 API 文档。