Sequential Thinking Working Notes

MCP Sequential Thinking

一个本地 MCP 服务，用于记录可在之后继续使用的工作笔记：针对棘手任务的证据、决策、风险和后续行动，持久存储在 SQLite 中，并可在任何重启后读取。它只记录调用方写入的内容；不会生成、评判或改进推理，也绝不会要求提供隐藏的思维链。

快速开始

python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
python -m pip install -e .
python scripts/stdio_smoke.py                  # restart demo: write, restart, read back

客户端配置（Claude Desktop、Cursor 等）：

{"mcpServers":{"working-notes":{
  "command":"/absolute/path/to/.venv/bin/mcp-sequential-thinking",
  "env":{"MCP_STORAGE_DIR":"/absolute/path/to/notes"}}}}

在 Windows 上使用 .venv\Scripts\mcp-sequential-thinking.exe。

典型会话：

{"tool":"create_session","arguments":{"title":"Choose a local store","request_id":"create-1"}}
{"tool":"add_step","arguments":{"session_id":"<id>","content":"Two writers need unique positions.","kind":"evidence","request_id":"step-1"}}
{"tool":"add_step","arguments":{"session_id":"<id>","content":"Use SQLite.","kind":"decision","request_id":"step-2"}}
{"tool":"read_session","arguments":{"session_id":"<id>"}}

重启后找不到 ID？list_sessions 可按标题查找会话。

工具

工具	用途
create_session	根据标题开始一个会话。
add_step	添加笔记；kind 可以是 note（默认）、observation、evidence、assumption、option、risk、decision 或 next_action。
list_sessions	按标题或状态查找会话。
read_session	view="resume"（默认）：显示活动笔记，决策优先。view="steps"：显示带筛选条件的完整历史记录。
finalize_session	保存调用方的结果和证据 ID；此后不能再添加步骤。
delete_session	删除会话的数据库记录（导出文件和备份仍会保留）。
export_session / import_session	导出或导入单个会话的 JSON 归档，文件限定在 MCP_STORAGE_DIR/exports 中。

笔记之间的链接。 parent_step_id 记录来源，supersedes_step_id 替换较早的笔记（继续查看时会隐藏该笔记，完整历史记录中则会保留），而 branch_from_step_id 用于开始一个命名分支。所有引用都限定在同一会话内。

重试。 每次写入都需要一个 request_id。使用相同 ID 和相同输入重复调用会返回原始结果；使用相同 ID 和不同输入则会返回 IDEMPOTENCY_CONFLICT。finalize_session 和 delete_session 还需要 expected_version。

分页和限制。 读取默认返回 20 条记录和 12,000 个字符 （limit ≤ 100，max_chars 为 1,000–50,000）。持续传递 cursor，直到其值为 null，并在分页期间保持相同的 view。 truncated 表示内容已缩短。如果笔记过大，无法在单个响应中返回，则会返回其首个片段；继续使用 step_id 和 content_offset 获取内容，直到 next_content_offset 为 null。

错误会设置 isError=true，并附带稳定的错误代码和简短提示，例如 INVALID_INPUT（附带 Fields: …）、UNKNOWN_SESSION、INVALID_REFERENCE、 CONFLICT（附带 current_version）、SESSION_FINALIZED、IDEMPOTENCY_CONFLICT、 STORAGE_BUSY（使用相同的 request_id 重试）、PATH_OUTSIDE_EXPORTS、 RESPONSE_LIMIT。

附加到笔记的来源由调用方提供，不会被获取或验证。

旧版工具（已弃用）

process_thought、generate_summary 和 clear_history，以及未指定 session_id 的 export_session / import_session，都在单个共享的 legacy 会话上运行。 这些工具仍为现有客户端保留；每个结果都包含 deprecation_notice。 新任务请使用会话 API。

• 阶段：问题定义、研究、分析、综合、结论 （不区分大小写）。除非设置了 --strict-stages，否则顺序警告仅供参考。
• main_line_progress 仅统计主线笔记，并以 total_thoughts 为基准； 它不代表任务完成度。
• 旧版导入会替换旧版历史记录。
• read_session(session_id="legacy") 可读取该历史记录；旧版分支 X 在其中显示为 legacy-X。

存储和运行

mcp-sequential-thinking              # stdio server
mcp-sequential-thinking --health     # diagnostic check
mcp-sequential-thinking --ephemeral  # in memory only, lost on exit

• 数据以明文 SQLite 格式（WAL、synchronous FULL、5 秒忙碌超时）存储在 ~/.mcp_sequential_thinking（或 MCP_STORAGE_DIR）中。请使用本地磁盘；不支持 NFS/SMB 和多台主机。
• 多个 stdio 服务可以共享同一个存储。本地 stdio 信任操作系统用户；会话 ID 不具备授权作用。HTTP/SSE 仍处于实验阶段。
• 删除并不等同于安全擦除。没有自动保留策略。
• 首次启动时，现有的 0.6 JSONL 历史记录会在单个事务中迁移到 SQLite，并保留 ID 和内容；源文件的备份会留在原处。 请先停止旧版 0.6 服务。新写入数据后不支持降级。

备份和恢复（所有会话，包括重试键）：

python -m mcp_sequential_thinking.backup create  /path/to/storage /path/to/snapshot.sqlite3
python -m mcp_sequential_thinking.backup restore /path/to/NEW-storage /path/to/snapshot.sqlite3

恢复需要使用一个新目录。切勿在数据库文件仍处于运行状态时进行复制，否则会遗漏其 WAL。

已测试的客户端

客户端	操作系统	日期
Python MCP SDK 2.0.0 和最新版本，Python 3.10–3.14	Linux、Windows	每次 CI 运行
Claude Desktop	Linux	2026-10-21

开发

uv run --extra dev ruff check .
uv run --extra dev ruff format --check .
uv run --extra dev mypy --strict mcp_sequential_thinking
uv run --extra dev pytest --cov=mcp_sequential_thinking --cov-fail-under=85
rm -rf dist && uv run --extra dev --with build --with twine --with jsonschema python scripts/check_artifacts.py

制品检查会在隔离环境中构建并安装 wheel，然后执行真实的重启往返测试。创建 GitHub release 后，发布流程会通过 Trusted Publishing 发布经过测试的制品；版本号定义在 mcp_sequential_thinking/_version.py 中。详情请参阅 CHANGELOG.md。