Axis MCP Server

关键词

Model Context ProtocolContext MirrorResources & ToolsStdio TransportSupabase persistence

使用说明（Markdown 格式）

  • 项目简介

    • Axis MCP 服务器是一个完整的后端实现，基于 Model Context Protocol (MCP) 与客户端进行上下文交互，托管资源、注册并执行工具、以及渲染提示模板。服务器端负责会话管理、能力声明，并支持多种传输方式（如 STDIO，SSE，WebSocket 等）。仓库实现了标准的 MCP 服务端核心能力，包含资源与工具的暴露、资源读取、工具执行以及对客户端的 JSON-RPC 风格响应。

  • 主要功能点

    • 资源与工具托管：提供可读取的资源、可执行的工具，以及与上下文推理相关的提示模板。
    • 会话与能力声明：对客户端会话进行管理，并以 JSON-RPC 风格返回能力信息与状态。
    • 多传输与兼容性：当前实现以 STDIO 为主要传输（便于 IDE 插件集成），并具备可扩展的传输层能力以支持 SSE、WebSocket 等。
    • 远端与本地持久化：整合 Supabase 作为持久化后端，同时支持本地状态存储与缓存（NerveCenter、锁、历史记录等）。
    • 订阅/访问控制：提供订阅校验、访问控制及错误容错，确保在订阅失效或 API 调用异常时的行为可控。
    • 安全与审计：日志、审计与限流等机制，帮助追踪工具调用、资源访问等行为。

  • 安装步骤

    • 安装依赖并构建：
      • 克隆仓库后，安装依赖并编译/构建（如使用 Bun/Node/Tsup 等工具链，具体命令请按项目实际使用的构建脚本执行）。
    • 本地开发启动：
      • 进行本地环境变量配置（如 Supabase、OpenAI、API 秘钥等），参考 README 给出的环境变量名称与用途。
      • 启动服务器（示例在 README/源码中给出了本地启动路径，通常通过 bun start:local 或等效命令启动本地 MCP 服务器）。
    • 运行后端 MCP 服务：
      • 服务器端会以标准的 MCP Server 形式启动，监听 STDIO/传输通道，等待 MCP 客户端连接。

  • 服务器配置（MCP 客户端使用的连接配置，JSON 格式） 说明：MCP 客户端需要知道要连接的 MCP 服务器的启动命令及参数等信息，以便通过指定的传输通道与服务器建立通信。以下配置示例基于仓库内的实现思路给出，实际路径与参数请按你的本地/云端环境调整。

    { "mcpServers": { "shared-context": { "name": "Axis Shared Context MCP Server", "command": "bun", "args": ["run", "/absolute/path/to/axis/src/local/mcp-server.ts"], "workingDirectory": "/absolute/path/to/axis", "description": "Axis MCP 服务器（Shared Context）用于向 MCP 客户端提供资源、工具及上下文镜像等能力。" } } }

    配置要点说明：

    • name：服务器的标识名称，便于区分不同 MCP 服务实例。
    • command / args：启动 MCP 服务器的实际命令及参数。此处示例使用 bun 来直接运行 TypeScript/TS 文件，路径请替换为实际项目中 mcp-server 的位置。
    • workingDirectory：运行时的工作目录，确保相对路径和产出正确解析。
    • 注：MCP 客户端不需要实现服务器端的逻辑，该配置仅用于指定如何启动并连接 MCP 服务器。

  • 基本使用方法

    • 连接与使用
      • 将客户端（如 Cursor、Claude、Windsurf 等）配置为指向本 MCP 服务器（通过上述配置）。
      • 客户端启动后，MCP 将暴露以下能力：资源读取、工具执行、以及上下文提示的渲染。LLM 客户端即可通过这些能力访问受控的资源与函数。
    • 常见工作流（示例，具体实现请按集成客户端的交互模式）：
      • 获取并加载项目“魂”信息（project soul），通过 get_project_soul 调用加载上下文与规范。
      • 使用 post_job 提交非平凡任务，claim_next_job 获取并锁定待处理的任务。
      • 通过 propose_file_access 锁定要编辑的文件，完成任务后调用 complete_job 释放锁并更新进度。
      • 根据需要调用 update_shared_context、update_project_soul 等工具来维护实时上下文与长期记忆。
    • 运行与排错
      • 确认环境变量、依赖、数据库连接及网络访问权限正确配置。
      • 如遇到并发锁、RPC 调用等问题，请查看服务器日志与相应的 RPC 返回，以定位竞态条件与权限/权限校验逻辑。

  • 备注与注意

    • 本实现围绕 MCP 的核心能力：Resources、Tools、Prompts、以及会话/能力声明，具备可运行的服务端逻辑，且提供本地化与远端 API 混合持久化方案，符合 MCP 服务器的基本要求。
    • 如需在生产环境部署，建议完善密钥管理、权限/鉴权策略，以及对外暴露的接口的安全性与审计日志。

服务器信息

访问项目