本地MCP服务器

锻造MCP服务器

Forge是一个仅限个人本地的MCP服务器，用于Codex CLI项目的连续性。它专为一台机器、一名开发人员和针对本地项目状态的低延迟stdio使用而设计，而不是任何远程服务。

服务器在本地保持连续性 .forge/ 文件，读取 ~/.forge/global.json，并支持快速本地发现和原子写入，而不是多用户功能。当前的设计比原始项目计划更精简：Forge充当了一个局部连续性架，带有键入的注释、明确的阶段进度、精确的状态突变和一个用于结构项目图的单独形状层。

需求

• Node.js 20+
• npm

设置

npm install

在开发中运行

npm run dev

构建并运行

npm run build
npm start

Codex CLI使用

Forge旨在在Codex CLI中配置为本地stdio MCP服务器。在已建成的入口点放置Codex：

node /absolute/path/to/forge-mcp/dist/index.js

这使得仅在这台机器上进行调用，避免了网络延迟，并让Forge直接读写您的本地连续性文件。

快速验证

npm run check

锻造模型

Forge现在是一个面向代理的小型状态系统，具有单独的结构图。

外部形状，Forge的作用是：

• 结构化智能笔记
• 显式会话切换
• 明确的阶段/步骤进度
• 精确状态突变

这并不是要表现得像：

• 第二个推理大脑
• 计划驾驶舱
• 隐藏的路由引擎
• 告诉代理人该做什么的经理

公共工具界面

Forge目前公开了6个公共工具：

• forge_init
• forge_load
• forge_checkpoint
• forge_update
• forge_shape
• forge_update_shape

forge_init

显式创建 .forge/ 种子：

• memory.json
• plan.json
• phases.json
• shape.json

当您希望目录成为Forge管理目录时，请使用它。

forge_load

被动读取路径。

forge_load 默认为 compact 模式并返回：

• workingView.shelf
• workingView.session
• 最小 shapeMeta
• 文件状态元数据
• 托管/非托管项目状态

使用 mode: "full" 只有当你有意想要生的时候：

• memory
• plan
• phases

forge_load 不会自动初始化项目。如果不存在Forge项目，它将报告一个非托管目录，并且在您运行之前，写入工具将不会继续 forge_init.

forge_checkpoint

默认的里程碑写入。

它可以结合：

• 一个里程碑注释
• 一个明确的打字笔记
• 已完成的步骤
• 会话切换更新
• 可选的轻量级形状元数据(summary, projectType, confidence)

当项目达到一个有意义的进度点，并且您想要一个干净的连续性写入时，请使用它。

不要使用 forge_checkpoint 添加或重写Shape结构。如果表面、功能或零件发生变化，请阅读 forge_shape 并用 forge_update_shape.

检查点注释类型有意轻量级。它们现在包括实用类型，例如：

• milestone
• interpretation
• ambiguity
• superseded_read
• fact
• reference
• concern

forge_update

精确突变API。

当你确切地知道什么结构化状态应该改变时，使用它。

实际上， forge_update 是先进的精密路径。 当你想：

• 故意结束或缩小问题
• 添加或更新正式解释
• 直接存储被取代的结论
• 明确设置相位状态

如果此刻主要是“我们取得了进步，应该把架子收拾干净”，更喜欢 forge_checkpoint.

它可以更新：

• 笔记
• 决定
• 解释
• 被取代的结论
• 问题
• 会话上下文
• 计划字段
• 阶段状态

forge_shape

从以下位置读取结构图 shape.json.

当您需要了解以下内容时，请使用它：

• 表面
• 能力
• 零件

而不会加载完整的项目连续性。

forge_update_shape

精确地改变结构图。

当当前项目表单以持久的方式更改时使用它：

• 新表面
• 增加能力或实质性重新界定范围
• 添加零件或重新确定范围
• 项目整合方式的有意义变化

状态模型

Forge阅读 ~/.forge/global.json 并将项目存储在当地州 .forge/.

plan.json

稳定的项目身份：

• 堆栈
• 设计风格
• 核心功能
• 计划的功能
• 架构决策

memory.json

持久的连续性：

• 打字笔记
• 决定
• 解释
• 被取代的结论
• 问题
• 会话切换

phases.json

执行结构：

• 阶段
• 步骤
• 步骤状态
• 可选步骤说明

shape.json

结构工程图：

• 表面
• 能力
• 零件

本地文件布局

全局只读文件：

• ~/.forge/global.json

内部项目文件 .forge/:

• memory.json
• plan.json
• phases.json
• shape.json

代理工作流

预期的Forge工作流程故意狭窄有序：

1. forge_init 一次用于新的非托管项目
2. forge_load 在有意义的会议开始时
3. forge_shape 只有当项目有一个值得保留的持久地图时
4. 在文件中完成实际工作
5. forge_update 只有当明确需要精确的结构化校正时
6. forge_update_shape 只有当结构图在阅读后发生实质性变化时 forge_shape
7. forge_checkpoint 在停止之前或在一个有意义的里程碑之后

良好的默认模式：

• 从...开始 forge_load
• 正常工作
• 使用 forge_update 谨慎地进行精确修复
• 以...结束 forge_checkpoint

这是标准的Forge循环。如果代理在托管项目中使用Forge，这应该是默认行为，而不是即兴创作。

工作视图

在 compact 模式下，面向读取面的主要代理是：

• workingView.shelf

  • 笔记
  • 决定
  • 特征
  • 问题
  • 解释
  • 阶段

• workingView.session

  • 总结
  • 下一步
  • 时间戳

这是一个刻意的架子，而不是建议层。

操作行为

• Forge发现最近的项目 .forge/ 从工作目录或提供的可选工具向上移动目录 cwd
• 管理项目行为中故意排除了确切的主目录，因此 ~/.forge 保持全局状态，而不是托管项目根
• 面向写的工具通过原子写入来持久化数据
• forge_init 拒绝覆盖现有的Forge文件，除非 force 已明确设置
• 在工具处理程序使用之前，存储的JSON通过迁移层进行规范化

锻造形状

Forge Shape是该项目当前的结构心智模型。

将其用于：

• 存在哪些表面
• 该项目目前提供哪些功能
• 哪些主要部件支持这些功能
• 这些部分如何在结构层面上组合在一起

当项目有多个持久的工件或流时，形状最有用，这些工件或流的角色应在会话中保持清晰。

良好的形状适合：

• 具有多个面向用户的界面的应用程序
• 仪表板和多屏幕工具
• 多文档研究或调查工作区
• 多个输出、工作流或子系统组合在一起的项目以及以后的会话应快速恢复该映射

对于非UI工作，将Shape想象为：

• surfaces：工作遇到或消耗的主要地点
• capabilities：工作空间或系统可以有意义地做什么
• parts：支持该工作的主要构建部分或文档分组

档案样式工作区中的示例：

• 表面：经典文献、理论文献、最终判决、仅限州的简历
• 能力：时间线重建、模糊度跟踪、判决综合
• 零件：源数据包集、工作调查文档、存储的项目架

请勿将Shape用于：

• 通用注释
• 问题
• 阶段性进展
• 符号级或功能级实现细节
• 没有结构性后果的原始建筑评论

形状故意保持分离：

• plan 旨在实现稳定的身份
• shape 是当前的结构形式
• memory 是笔记、历史、问题、决定和未解决的压力
• phases 是执行进度

自然形状显示：

• 继续一个复杂的项目
• 在结构工程之前，了解项目是如何组合在一起的
• 仅检查表面、仅检查功能、仅检查零件或完整地图

Natural Shape写道：

• 新表面
• 增加能力或实质性重新界定范围
• 添加或重新定义主要部分
• 项目整合方式的有意义变化