AI导哈

会话共享服务

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

  • by remarqUK
  • JavaScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 remarqUK/contextflowMCP

使用说明

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

跑

node server.mjs

或者：

npm start

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

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

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

  • 如果 MCP_SHARED_CONTEXT_FOLDER 设置后，文件变为 <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：上下文根文件的绝对路径（用于导出 <root>.sessions/ 和 <root>.sessions-index.json)
  • MCP_SHARED_CONTEXT_FOLDER：包含上下文根文件的文件夹(<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

相关 MCP