ChatNut MCP 服务器

关键词

AI代理协作本地 SQLite 存储实时推送工具注册调用资源与会话管理

使用说明（简要概览，帮助快速了解与接入要点）

  • 项目简介

    • ChatNut 是一个面向 LLM 客户端的后端服务，遵循模型上下文协议（MCP），提供资源访问、工具注册与调用、以及对话/提示模板等能力，目标是为大语言模型在应用层面提供可扩展的上下文服务框架。
    • 服务端实现了基于 FastAPI 的 REST / SSE 流、以及 FastMCP 的 MCP 工具接口，支持通过 STDIO、HTTP 等传输方式与客户端通信；同时具备会话管理、能力声明和版本检查等能力。

  • 主要功能点（简明扼要）

    • MCP 核心能力
      • 注册并暴露一组 MCP 工具（如 ping/init_room/post_message/read_messages 等），用于 LLM 客户端调用外部功能与查询服务。
      • 提供房间/聊天室的创建、消息记录、归档、删除等操作的服务端实现，支持多项目隔离。
      • 提供对话上下文相关的查询能力（如读取历史、按类型筛选消息、对话统计等）。
    • 数据存储与一致性
      • 使用本地 SQLite（WAL 模式）作为存储，提供迁移机制与数据模型（房间、消息、读取游标、房间状态等）。
    • 实时通信与流
      • REST 接口用于普通请求，SSE/流式接口用于实时推送房间列表、消息与状态更新。
    • 安全与扩展性
      • 支持本地化部署、可扩展的工具集成、以及与 Claude Code 等 MCP 客户端的对接，具备会话管理与能力声明。
    • 部署与运维
      • 提供 CLI 入口（chatnut），可通过 serve 子命令启动 HTTP 服务器，支持端口自选、端口文件与 PID 文件管理，方便在 Claude Code 等环境中自动连接。

  • 安装步骤（简要）

    • 官方一键安装（推荐）
      • 使用一键脚本安装并注册到 Claude Code 等 MCP 客户端。
    • 手动安装（适合本地开发/自部署）
      • 安装 ChatNut，注册为 MCP 服务端（Claude Code 端的 mcp 配置）。
      • 启动服务器：执行 chatnut serve，默认会绑定一个可用端口并在运行目录下写入 server.port 与 server.pid。
      • 启动后，Claude Code 等客户端在配置中使用该服务器进行 MCP 交互。

  • 服务器配置（MCP 客户端的配置示例说明）

    • 客户端需要的最小信息（以 JSON 形式表达，供 MCP 客户端读取并建立连接；实际接入的程序不需要你在客户端模版中输入代码，仅需要知道配置信息要包含以下字段）：
    • serverName: chatnut
    • command: chatnut
    • args: serve 注释说明：上述信息描述的是服务器名称、启动命令及其参数，客户端在建立 MCP 连接时会参考此信息来定位并启动对接的 MCP 服务器。实际接入时，客户端通常使用服务地址、端口或传输通道进行连接，无需包含前端代码。

  • 基本使用方法

    • 启动与连接
      • 使用 CLI 启动服务器后，MCP 客户端（如 Claude Code）即可通过标准 MCP 客户端协议与服务端对接，进行工具调用、资源访问、以及读取/写入上下文信息。
    • 常用操作示例（通过 MCP 客户端工具在逻辑上执行，非代码演示）：
      • ping：检查服务器健康、运行时数据库路径、版本信息等。
      • init_room：创建或获取一个聊天室，CLI/客户端会收到房间 ID、所属项目等信息。
      • post_message/read_messages：向指定房间写入消息，或读取历史消息，支持按时间/ID 片段获取。
      • update_status/get_team_status：对团队成员状态进行上报与获取，支持多成员的状态并发查看。
    • 实时与状态流
      • 使用 /stream 接口（SSE）获取活跃房间、归档房间及其状态、以及房间内消息的变更。
    • 维护与扩展
      • 支持通过 migrations 管理数据库结构、通过 CLI 启动服务器、通过 MCP 工具扩展新的工具。

  • 运行与调试要点

    • 运行环境：本地开发环境建议使用 Python 3.12 及相关依赖，SQLite 作为存储。
    • 路由与传输：支持 REST、SSE、以及通过 MCP 的工具调用；在 Claude Code 等客户端中可结合自带的工具来触发房间创建、消息发送等流程。
    • 日志与故障排除：若遇到端口/进程相关问题，可以查看 CHATNUT_RUN_DIR 下的 server.port、server.pid 与 server.log 文件，定位服务启动情况与健康状态。

  • 额外说明

    • 服务器的实现明确包含后端服务器代码（FastAPI、MCP 集成、数据库层、路由、SSE 流等），具备完整的服务器端能力，而非仅为示例或测试用例。
    • 项目还提供了与客户端（Claude Code 等）集成的完整使用路径、安装脚本、以及对 MCP 的工具集（如 ping、init_room、post_message、read_messages、wait_for_messages、mark_read、list_rooms、archive_room、delete_room、clear_room、search、list_projects、get_team_status、update_status 等）进行端到端测试的测试用例，证实其服务器实现的完整性。

服务器信息

访问项目