使用说明

• 项目简介

  • Fractal 是一个将叙事管理能力暴露为 MCP 服务器的后端。它面向多项目场景，支持向 LLM 客户端提供结构化的记忆、工具及提示模板等能力，帮助在长文创作中维持一致性、提供外部功能调用和上下文渲染。

• 主要功能点

  • 多项目管理：在 FRACTAL_PROJECTS_ROOT 目录下维护多个独立项目，每个项目拥有自己的结构、版本控制（Git 自动提交）。
  • MCP 核心工具集合：提供 list_projects、template、get_context、create、update、write、edit、remove、select_variant、reorder_beats、session_summary、refresh_summaries 等工具，全部通过 MCP 的 JSON-RPC 进行交互。
  • 资源与数据能力：读取和写入项目结构、部份、章节、章节文本、Canon 条目、Scratch、注释等。
  • 工具与编码渲染：支持对 Beat 的原文 prose、变体、草稿、注释等进行结构化读写、编辑与版本管理。
  • Prompt 与上下文渲染：通过 get_context / 相关接口按需加载章节摘要、Beat 摘要、Canon 部分及 Sections，提供可控的上下文长度。
  • 安全和会话：通过可选的 OIDC/JWT 身份验证、会话管理、空闲会话回收等机制，确保多客户端并发且受控访问。
  • 传输与扩展：以 Streamable HTTP 的传输方式服务 MCP 请求，支持多路传输和扩展性能力。

• 安装与运行步骤

  • 环境准备：确保 Node.js 环境就绪，仓库中包含完整的服务端实现。
  • 安装与构建（简要）：安装依赖、构建并启动生产版服务器（dist/server.js）。
  • 运行指引要点：默认监听端口 3001，可通过 PORT 环境变量覆盖；项目根目录通过 FRACTAL_PROJECTS_ROOT 指定，默认指向 projects 目录。

• 服务器配置（客户端需要的最小信息）

  • MCP 客户端（如 Claude）需要的配置信息用于连接服务器。以下为示例描述，请按实际环境填写为 JSON 配置（客户端不需要你直接执行此配置）：
  • server_name: "fractal"
  • command: "node" 的执行命令（用于启动 MCP 服务器的可执行程序）
  • args: ["dist/server.js"]（生产环境通常通过打包后的入口启动）
  • 说明：服务器前置为 HTTPS/反向代理，实际连接到 /mcp 端点；如果启用了身份认证，需要提供有效的 Bearer Token（由客户端在初始化时获取并附带在请求头中）。客户端的连接参数不要求改动仓库代码，只需在连接时指向服务器的 /mcp 路径即可。

• 基本使用方法

  • 启动后，客户端通过 /mcp 端点建立会话并进行 JSON-RPC 调用。
  • 常用操作包括创建项目、读取上下文、修改章节、草稿草拟与版本控制等，详见 MCP 工具集文档。
  • 服务器提供健康检查接口 /health，帮助运维快速判定当前状态。

• 额外信息

  • 服务器实现了带有会话的流式传输，支持多会话并具备会话超时清理。
  • 具备完善的权限/鉴权入口，OIDC/JWT 认证可选开启。