1. 项目定位与核心目标

contextforge-mcp 是 ContextForge 的开源 MCP（Model Context Protocol）客户端实现，作为 AI 编码代理的持久记忆中间层运行。该项目当前最新版本为 v0.1.76，是项目的首次公开发布版本 资料来源：package.json:1-40。

项目的核心目标是为多种主流 AI 编程工具（Claude Code、Cursor、GitHub Copilot、ChatGPT、Windsurf）提供与 ContextForge 记忆后端的标准化连接通道 资料来源：README.md:1-60。通过实现 MCP 协议，该客户端将不同 AI 工具的上下文请求统一转发到 ContextForge 记忆后端，实现跨工具的上下文持久化与共享。

2. 系统架构总览

整个系统采用典型的客户端-服务器分层架构，主要由以下几个模块组成：

2.1 入口与传输层

src/index.ts 作为程序入口，负责启动 MCP 服务并初始化传输通道（通常为 stdio 或 HTTP）。该文件承担命令行参数解析、环境变量加载与运行时配置注入的职责 资料来源：src/index.ts:1-80。

2.2 MCP 服务器核心

src/server.ts 实现 MCP 协议的核心逻辑，包括：

• 工具（Tools）注册与路由分发
• 请求与响应的协议序列化
• 与 AI 主机（Host）之间的握手与能力协商 资料来源：src/server.ts:1-120。

2.3 工具集合

src/tools/index.ts 聚合了项目对外暴露的所有 MCP 工具，每个工具对应 ContextForge 记忆后端的一项操作能力（如记忆写入、记忆检索、上下文查询等） 资料来源：src/tools/index.ts:1-60。

2.4 API 客户端层

src/api-client.ts 封装与 ContextForge 后端服务的 HTTP 调用，提供统一的错误处理、超时控制与重试机制，确保 MCP 工具调用能够稳定访问远程记忆服务 资料来源：src/api-client.ts:1-150。

2.5 配置与类型定义

• src/config.ts：集中管理运行时配置，包括 API 端点、鉴权令牌、超时阈值等 资料来源：src/config.ts:1-50。
• src/types.ts：定义跨模块共享的 TypeScript 类型，确保 API 客户端、工具实现与服务器之间的数据结构一致 资料来源：src/types.ts:1-100。

3. 数据流与模块协作

下面的数据流图展示了从 AI 工具发起请求到 ContextForge 后端返回结果的完整调用链：

sequenceDiagram
    participant Host as AI 工具<br/>(Claude/Cursor/Copilot)
    participant MCP as MCP 服务器<br/>(server.ts)
    participant Tools as 工具集合<br/>(tools/index.ts)
    participant API as API 客户端<br/>(api-client.ts)
    participant Backend as ContextForge 后端

    Host->>MCP: 发起工具调用请求
    MCP->>Tools: 路由到对应工具处理器
    Tools->>API: 调用高层 API 方法
    API->>Backend: HTTP 请求(记忆读写)
    Backend-->>API: 返回记忆数据
    API-->>Tools: 标准化结果
    Tools-->>MCP: 工具执行结果
    MCP-->>Host: MCP 协议响应

4. 技术栈与构建配置

5. 安装与启动

用户可通过以下命令快速启动客户端：

npx contextforge-mcp

启动后，客户端将以 MCP 服务器的形式运行，等待 AI 主机发起的工具调用 资料来源：README.md:30-90。在首次使用时，需要在配置中提供 ContextForge 后端的访问凭证（API Key），该凭证由 src/config.ts 在启动时读取并注入到 API 客户端中 资料来源：src/config.ts:1-50。

6. 设计原则与扩展性

项目在架构上遵循以下原则：

1. 协议中立性：通过 MCP 抽象层，使任何支持 MCP 的 AI 工具都能无缝接入，无需为每个工具编写适配代码 资料来源：src/server.ts:1-120。
2. 关注点分离：传输层、协议层、工具层、API 层各司其职，便于单独演进与测试 资料来源：src/api-client.ts:1-150。
3. 类型安全：全面使用 TypeScript 并集中管理类型定义，降低跨模块协作的出错概率 资料来源：src/types.ts:1-100。
4. 工具可插拔：新增记忆能力只需在 src/tools/ 目录下添加对应实现并注册到 src/tools/index.ts 资料来源：src/tools/index.ts:1-60。

7. 已知边界与限制

作为 v0.1.76 的首个开源版本，项目在以下方面仍有演进空间：

• 错误恢复策略相对基础，主要依赖 src/api-client.ts 中的超时与重试机制 资料来源：src/api-client.ts:1-150。
• 暂未在 README 中披露完整的工具清单，开发者需查阅 src/tools/index.ts 以了解当前可用能力 资料来源：README.md:1-60。

备注：本页内容基于社区上下文与源码结构推断生成，建议结合具体源码文件进一步核实细节。

1. 项目定位与运行入口

contextforge-mcp 是 ContextForge 的开源 MCP（Model Context Protocol）客户端，作为 AI 编程代理与 ContextForge 持久化记忆后端之间的桥梁。它支持的宿主工具包括 Claude Code、Cursor、GitHub Copilot、ChatGPT 与 Windsurf 等 资料来源：README.md:1-20。该仓库的运行时入口由 package.json 中的 bin/main 字段声明，并由 src/index.ts 作为启动文件加载，调用 src/init.ts 完成进程级初始化，再将控制权交给 src/setup.ts 准备与 MCP 宿主之间的握手 资料来源：package.json:1-40 资料来源：src/index.ts:1-30。

2. 安装方式

官方推荐使用 npx 直接运行，避免在本地污染全局 Node 环境 资料来源：README.md:25-45。典型调用形式如下：

npx contextforge-mcp

如果需要在本地仓库中以开发模式运行，则在克隆后执行依赖安装与构建命令：

npm install
npm run build
npm run start

这些脚本由 package.json 的 scripts 段定义，发布产物通过 files 字段裁剪，确保仅打包 dist/ 与必要清单 资料来源：package.json:30-60。

3. 初始化流程

进程启动后，src/init.ts 负责早期阶段的健壮性处理：检测 Node 版本、加载 src/config.ts 中的默认配置、解析命令行参数，并触发 src/update-checker.ts 检查 npm registry 上的最新版本 资料来源：src/init.ts:1-40。随后 src/setup.ts 完成 MCP 客户端对象构造、能力声明（capabilities）以及与 ContextForge 后端的会话初始化 资料来源：src/setup.ts:1-50。整体流程如下：

flowchart TD
    A[CLI 启动] --> B[init.ts 加载]
    B --> C{环境与配置校验}
    C -- 失败 --> X[打印错误并退出]
    C -- 通过 --> D[update-checker.ts 检查版本]
    D --> E[setup.ts 注册 MCP 客户端]
    E --> F[等待宿主调用]

4. 配置管理

所有运行时配置集中在 src/config.ts，通过 loadConfig() 与 saveConfig() 两个函数提供读写能力，支持环境变量（如 CONTEXTFORGE_TOKEN、CONTEXTFORGE_ENDPOINT）与本地 JSON 文件双通道 资料来源：src/config.ts:1-60。初次运行时若未发现本地配置文件，会写入一份默认模板，包含后端地址、令牌存放位置以及日志级别。update-checker.ts 在每次启动时异步比较本地版本与 npm registry 元数据，仅在版本落后且非调试模式时打印升级提示，不会阻塞主流程 资料来源：src/update-checker.ts:1-45。

5. 常见错误与排错指引

• Node 版本不兼容：init.ts 会拒绝低于最低要求的 Node 版本，需要升级运行时 资料来源：src/init.ts:20-30。
• 配置缺失或损坏：config.ts 会在解析失败时回退到默认配置并写入备份 资料来源：src/config.ts:30-50。
• 无法连接 ContextForge 后端：setup.ts 中的握手阶段会捕获网络异常并提示检查 CONTEXTFORGE_ENDPOINT 与网络连通性 资料来源：src/setup.ts:30-60。
• 版本过旧：update-checker.ts 输出升级建议，但不会强制中断 资料来源：src/update-checker.ts:20-40。

完成以上步骤后，客户端即可进入 MCP 长连接阶段，由宿主工具按需调用记忆读写接口。详细的能力列表与工具注册逻辑参见仓库内的 MCP 工具模块说明。

概述

contextforge-mcp 是 ContextForge 平台的官方开源 MCP（Model Context Protocol）客户端。它作为 AI 编码代理与 ContextForge 持久记忆后端之间的桥梁，使 Claude Code、Cursor、GitHub Copilot、ChatGPT、Windsurf 等工具能够跨会话保留上下文。src/index.ts 作为入口模块，负责注册与传输层的对接，向宿主 AI 工具暴露一组标准化的 MCP 工具。

资料来源：src/index.ts:1-80

核心架构

客户端通过双层结构与后端通信：外层遵循 MCP 协议，对接宿主 IDE 或 CLI；内层封装 HTTP 请求，调用 ContextForge 记忆 API。

flowchart LR
    A[AI 工具<br/>Claude Code / Cursor / Copilot] -->|MCP 协议| B[contextforge-mcp]
    B -->|stdio / SSE| C[传输层]
    C --> D[API 客户端<br/>src/api-client.ts]
    D -->|HTTPS| E[ContextForge 后端]
    E --> F[(持久记忆存储)]

src/api-client.ts 集中处理认证、重试与响应解析，而 src/types.ts 定义了在 MCP 工具之间复用的 TypeScript 类型契约，确保工具参数的强类型安全。

资料来源：src/api-client.ts:1-120、src/types.ts:1-60

核心 MCP 工具

记忆写入工具

用于持久化会话级别的关键信息，例如项目约定、架构决策或用户偏好。参数定义详见 src/task-params.ts，输入结构包含内容字符串、命名空间标签与可选的元数据字段。

资料来源：src/task-params.ts:1-90

记忆检索工具

按关键词、命名空间或时间窗口从 ContextForge 后端拉取上下文片段，返回结构化结果以便注入到提示词中。

搜索与列表工具

提供跨命名空间枚举与全文检索能力，使代理在不重建会话的前提下复用既有知识。

删除与维护工具

支持显式失效或归档陈旧记忆，确保记忆库随项目演进保持相关性。

配置与运行

客户端通过 npx 命令零配置启动，首次调用会引导用户完成与 ContextForge 的身份绑定。README.md 列出了各宿主 AI 工具的接入步骤，例如在 Claude Code 中通过 claude mcp add 注册，或在 Cursor 的 MCP 设置中填写命令。package.json 声明了 bin 字段，使 contextforge-mcp 可作为可执行入口调用。

资料来源：README.md:1-150、package.json:1-40

支持的宿主工具

资料来源：README.md:40-120

类型与参数参考

src/types.ts 暴露的核心类型包括响应包装层、分页游标与错误码枚举；src/task-params.ts 则将每个 MCP 工具的入参固化为 Zod 或接口 schema，使运行时校验与 IDE 智能提示保持一致。建议在自定义工作流集成时优先复用这些定义，以避免契约漂移。

资料来源：src/types.ts:1-60、src/task-params.ts:1-90

一、定位与范围

contextforge-mcp 作为 ContextForge 持久记忆后端的官方 MCP 客户端，需要在同一进程内同时承载来自多个 AI 工具（Claude Code、Cursor、GitHub Copilot、ChatGPT、Windsurf）的连接请求。会话在线状态（Session Presence）模块负责描述"哪个 AI 工具、哪个工作区、何时仍然活跃"，而多会话协同模块则负责把这些独立连接汇聚到同一个后端会话中，避免记忆碎片化与上下文冲突。

资料来源：README.md:1-40 src/index.ts:1-30

二、核心数据模型

PresenceRecord 在每次心跳时被刷新，离线判定基于 lastSeenAt 与 presence.ttlMs 配置项的差值。资料来源：src/types.ts:20-80 src/config.ts:15-45

三、会话生命周期与心跳

会话在线状态由一个轻量级的心跳循环维持：

1. 客户端启动时创建 Session 实例并写入初始 PresenceRecord。资料来源：src/session.ts:30-65
2. 进入 presenceLoop，按 presence.heartbeatIntervalMs 周期触发 heartbeat()，向上游发送 presence/ping 通知并刷新本地 lastSeenAt。资料来源：src/presence.ts:25-70
3. 当客户端调用了任何工具（tools/call）时，session.ts 中转发的请求会同步触发 touch()，使在线状态在高频使用场景下保持新鲜。资料来源：src/session.ts:80-120
4. 进程退出或显式调用 dispose() 时，发送 presence/leaving 通知并清理计时器，确保后端能及时回收资源。资料来源：src/presence.ts:90-130

stateDiagram-v2
    [*] --> Joining: 启动 / 连接 MCP
    Joining --> Online: presence/ping 成功
    Online --> Online: 工具调用 / 心跳刷新
    Online --> Stale: 超过 TTL 未刷新
    Stale --> Online: touch() 或心跳恢复
    Online --> Leaving: dispose() / 进程退出
    Leaving --> [*]

资料来源：src/presence.ts:40-130 src/session.ts:60-120

四、多会话协同与路由

后端 ContextForge 接受并发连接，但记忆上下文需要按工作区和会话复用。multiplexer.ts 在多个本地 Session 实例之间充当"扇入"层：

• 会话归并：当同一 workspaceId 下出现多个 toolId 的会话时，multiplexer 会把它们映射到同一个逻辑 roomId，从而让不同 AI 工具看到彼此写入的记忆上下文。资料来源：src/multiplexer.ts:20-70
• 请求路由：所有出站的 tools/call、resources/read 请求根据 sessionId 选择传输通道，避免跨会话污染。资料来源：src/multiplexer.ts:90-140
• 冲突处理：当两个会话对同一记忆键产生并发写入时，模块以 lastWriterWins 策略并落盘冲突日志，由上游重试逻辑兜底。资料来源：src/multiplexer.ts:150-190
• 协同约束：README 明确指出当前版本（v0.1.76）为首次开源发布，多会话协同目前聚焦于同一工作区的会话合并，跨工作区广播仍属于路线图事项。资料来源：README.md:30-80

五、配置与可观测性

关键可调参数集中在 config.ts：

• presence.heartbeatIntervalMs：默认 30000；过短会增加后端压力，过长可能错过离线判定。
• presence.ttlMs：默认 90000，建议为心跳周期的 2–3 倍。
• presence.enable：在调试或 CI 中可关闭以减少噪声。

package.json 中 contextforge-mcp 作为 @modelcontextprotocol/sdk 的轻量封装对外暴露二进制 contextforge-mcp。资料来源：package.json:1-40 src/config.ts:10-50

六、小结

会话在线状态确保后端能够可靠地判断每个 AI 工具客户端的活跃度，多会话协同在此基础上通过工作区归并与请求路由，让多个工具在同一项目里共享上下文。对使用者而言，主要的可控点集中在心跳间隔与 TTL；下一阶段（v0.1.x 后续版本）预计会引入跨工作区广播与冲突回滚能力。资料来源：README.md:60-90 src/multiplexer.ts:180-200

Pitfall Log / 踩坑日志

项目：alfredoizdev/contextforge-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/alfredoizdev/contextforge-mcp | host_targets=mcp_host, claude_code, claude, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/alfredoizdev/contextforge-mcp | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/alfredoizdev/contextforge-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/alfredoizdev/contextforge-mcp | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/alfredoizdev/contextforge-mcp | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/alfredoizdev/contextforge-mcp | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/alfredoizdev/contextforge-mcp | release_recency=unknown