succ MCP 服务器实现

使用说明（Markdown格式）

• 项目简介

  • succ 是一个面向 LLM 客户端的 MCP 服务器实现，负责托管和管理 Resources、Tools、Prompts 等资源，允许 LLM 调用外部工具、访问数据，并定义和渲染 Prompt 模板，提供安全、可扩展的上下文服务框架。

• 主要功能点

  • MCP 协议实现与 JSON-RPC 通信：服务器按 MCP 规范处理请求并返回 JSON-RPC 响应。
  • 资源管理：提供 brain vault、Soul 文档等资源的读取与列表能力。
  • 工具注册与执行：142+ 条 MCP 工具组合（如 succ_search、succ_remember、succ_recall、succ_status、succ_web 等），支持搜索、存储、图谱、PRD、Web 搜索等多种能力。
  • 会话与生命周期管理：具备会话创建、活动、 idle/reflection 机制、统一守护进程支持等。
  • 安全与合规性：工具层面包含权限、分层能力声明、输入校验、敏感信息过滤与守卫等。
  • 多传输与守护：设计了不同传输实现（如 stdio、WebSocket、SSE 等）的后端支持，以及守护进程和作业队列。
  • 插件式扩展：模块化工具、资源、配置等分离，易于扩展和测试。

• 安装与运行

  • 本项目为一个后端 MCP 服务器实现，通常在带有 Node.js 的环境中直接运行 TypeScript 构建产物或 kullan 絶对 tsx 运行。
  • 推荐的运行方式：使用支持 TypeScript 的执行环境（如 tsx）直接启动源文件入口。
  • 启动示例（以开发环境为例，实际部署可按你的环境调整）：
    • 通过命令行直接以 tsx 运行入口
    • 交互式日志与调试信息将输出到标准输出和日志文件

• 服务器配置（MCP 客户端需要的启动信息） 说明：MCP 客户端不需要此 JSON 配置，它用于描述服务器端的启动信息，便于客户端了解如何连接到 MCP 服务器。以下为可用于客户端理解的配置信息文本描述（JSON 形式展示，实际客户端配置可直接参考该内容）。

  { "server_name": "succ", "command": "npx", "args": ["tsx", "src/mcp-server.ts"] // 启动该 MCP 服务器的命令及参数，客户端据此建立连接 }

  注释：

  • server_name：服务器在 MCP 客户端中的标识名称，建议与实际实现的一致（此处为“succ”）。
  • command/args：启动 MCP 服务器的命令和参数。示例使用 tsx 直接执行 TypeScript 源码入口，具体部署时可根据实际运行环境替换为 node/ts-node/tsx 等。
  • MCP 客户端无需修改服务器端的实现细节，但需要知道服务器名称与启动方式以建立连接。

• 基本使用方法

  • 启动服务器：在支持的执行环境中运行入口脚本，服务器启动后会监听并处理 MCP 客户端发送的请求。
  • 客户端交互：通过 JSON-RPC 方式向服务器发送请求，例如初始化能力、读取资源、调用工具、获取 Prompt 等，服务器返回 JSON-RPC 响应或通知。
  • 管理与扩展：服务器提供了模块化的工具和资源扩展点，便于按需增删工具、资源、配置，支持多后端存储和多 LLM 后端的使用。

• 运行与验证

  • 运行脚本位于源码中，测试和集成用例覆盖了工具、资源、路由、守护进程等核心能力，确保 MCP 协议的核心流程得以实现。