Contextflow MCP

ContextFlowMCP

ContextFlowMCP是一个小型MCP服务器（stdio），允许多个助手通过每个会话的JSONL文件共享进度，并具有共享会话索引以快速列出。

维护人员：参见 MAINTAINER.md 用于架构和修改指导。

这是一个示例工作流：

• 克劳德写了一封交接信
• 双子座读了一遍，然后继续
• Codex阅读了相同的会议背景，并从他们中断的地方继续

它揭示了什么

• append_shared_note：在工作时添加进度注释
• write_shared_handoff：为下一位助理写一份结构化的交接单
• read_shared_context：从共享会话存储中读取最近的笔记/切换
• get_latest_handoff：快速获取最近的切换
• list_sessions：列出可恢复的工作会议(session_id)就像一个简历选择器
• choose_session：从列表中选择会话（按索引或 session_id)
• resume_session：加载所选的最新切换+最新条目 session_id
• MCP提示命令： new_session, resume_#，以及 resume_by_id 用于会话选择

它还公开了只读MCP资源，如 shared-context://raw, shared-context://latest，以及 shared-context://info.

交互式选择器（MCP原生）

不需要额外的脚本。

在Claude/Codex中，键入 / 并从以下选项中选择MCP提示 contextflow:

• new_session （第一种选择）
• resume_1, resume_2, ...（现有会议）

使用箭头键滚动并按Enter键。

行为：

• new_session 总是第一
• 如果你在Git仓库中， new_session 将当前分支用作 session_id
• 所选会话将成为活动会话，工具可以省略 session_id

可选的本地选择器脚本（行为相同）：

node pick-session.mjs

存储格式

• 每个只追加一个JSONL文件 session_id （储存于 .sessions/)
• 条目无 session_id 存储在专用 (no-session-id) 会话文件
• 每一行都是一个JSON对象(note 或 handoff)
• 共享会话索引文件(.sessions-index.json)保持快速 list_sessions 基于提示的会话选择器
• 使用简单的锁文件对多个MCP服务器进程安全(.lock)

跑

node server.mjs

或者：

npm start

重要提示：将所有客户端指向同一存储根目录

每个客户端（Gemini/Claude/Cox）都必须解析到相同的上下文根路径，以便它们共享相同的会话文件目录和索引。

零配置首次运行行为（当 MCP_SHARED_CONTEXT_FILE 未设置）：

• 如果 MCP_SHARED_CONTEXT_FOLDER 设置后，文件变为 /.mcp-shared-context.jsonl.
• 否则，服务器会检查常见的Codex/Claude/Gemini配置文件 MCP_SHARED_CONTEXT_FILE.
• 如果仍然找不到，它将检查现有上下文文件的常用用户配置文件夹(.mcp-shared-context.jsonl, shared-context.jsonl, agent-context.jsonl).
• 如果找不到任何东西，则返回到 ~/.mcp-shared-context.jsonl.

遗留注释：

• 如果上下文根中存在旧的单文件JSONL，但还不存在会话文件，则服务器会在第一次索引重建时将其迁移到每个会话文件中。

推荐的环境变量：

• MCP_SHARED_CONTEXT_FILE：上下文根文件的绝对路径（用于导出 .sessions/ 和 .sessions-index.json)
• MCP_SHARED_CONTEXT_FOLDER：包含上下文根文件的文件夹(/.mcp-shared-context.jsonl)
• MCP_SHARED_CONTEXT_PROJECT （可选）：用于筛选的逻辑项目键（默认为 shared)
• MCP_SHARED_CONTEXT_ACTIVE_SESSION_FILE （可选）：存储当前活动会话id的文件（默认为 active-session.txt 在上下文根旁边）

安全/性能护栏（可选）：

• MCP_SHARED_CONTEXT_MAX_CONTEXT_FILE_BYTES （默认值 52428800)
• MCP_SHARED_CONTEXT_MAX_INBOUND_FRAME_BYTES （默认值 2097152)
• MCP_SHARED_CONTEXT_MAX_INBOUND_LINE_BYTES （默认值 2097152)
• MCP_SHARED_CONTEXT_MAX_INPUT_BUFFER_BYTES （默认值 4194304)
• MCP_SHARED_CONTEXT_MAX_NOTE_TEXT_CHARS （默认值 20000)
• MCP_SHARED_CONTEXT_MAX_HANDOFF_SUMMARY_CHARS （默认值 20000)
• MCP_SHARED_CONTEXT_MAX_ARRAY_ITEMS （默认值 200)
• MCP_SHARED_CONTEXT_MAX_ARRAY_ITEM_CHARS （默认值 1000)

示例值：

MCP_SHARED_CONTEXT_FILE=/absolute/path/to/shared/agent-context.jsonl

MCP_SHARED_CONTEXT_FOLDER=/absolute/path/to/shared

MCP配置模式（标准）

使用客户端的MCP服务器配置，并添加一个运行此文件的stdio服务器条目。

{
  "mcpServers": {
    "contextflow": {
      "command": "node",
      "args": ["/absolute/path/to/contextflow-mcp/server.mjs"],
      "env": {
        "MCP_SHARED_CONTEXT_FILE": "/absolute/path/to/shared/agent-context.jsonl"
      }
    }
  }
}

笔记：

• Claude、Gemini和Codex客户端的确切配置文件位置/形状不同。
• 关键要求是相同的stdio命令和相同的解析上下文根路径。

建议所有助理的工作流程

1. 使用MCP提示命令(new_session, resume_#，或 resume_by_id)设置活动会话。
2. 呼叫 resume_session （你可以省略 session_id 如果设置了活动会话）。
3. 呼叫 append_shared_note 随着你的进步。
4. 以电话结束 write_shared_handoff 随着 summary, next_steps，以及拦截器/问题。

工具调用示例

写一条注释：

{
  "agent": "claude",
  "text": "Investigated failing auth flow. Root cause appears to be missing cookie SameSite config.",
  "session_id": "bugfix-auth-cookie",
  "task": "Fix auth cookie regression"
}

兼容性： append_shared_note 也接受 content 作为别名 text.

写一个交接：

{
  "agent": "claude",
  "summary": "Found the regression in cookie configuration. No code changes yet.",
  "next_steps": [
    "Update cookie options in auth middleware",
    "Run login flow manually",
    "Add regression test for SameSite setting"
  ],
  "open_questions": [
    "Should staging use Secure cookies behind proxy in local dev?"
  ],
  "files": [
    "src/auth/middleware.ts"
  ],
  "session_id": "bugfix-auth-cookie",
  "task": "Fix auth cookie regression"
}

阅读最近的上下文：

{
  "limit": 10,
  "session_id": "bugfix-auth-cookie"
}

列出可恢复的会话：

{
  "limit": 20,
  "format": "json"
}

选择会话（按列表索引）：

{
  "index": 1,
  "limit": 20,
  "format": "json"
}

恢复所选会话：

{
  "session_id": "bugfix-auth-cookie",
  "limit": 20,
  "format": "json"
}

快速验证

npm run self-test
npm test

npm run self-test 检查核心JSONL解析/格式化逻辑。 npm test 运行模式兼容性和安全防护的集成测试。

贡献

欢迎拉取请求。从...开始 CONTRIBUTING.md 和 MAINTAINER.md，然后运行：

node --check server.mjs
node --check pick-session.mjs
npm run self-test
npm test

协作文档

• 贡献者指南： CONTRIBUTING.md
• 行为准则： CODE_OF_CONDUCT.md
• 安全策略： SECURITY.md
• 支持指南： SUPPORT.md
• 变更日志： CHANGELOG.md
• 许可证： LICENSE