1. scratchpad-mcp 是什么给 Claude 加一层 SQLite 临时记忆如果你用 Claude 做长链路任务大概率遇到过这种尴尬同一个文件被反复读取上一轮刚看过的内容下一轮又得重新塞进上下文token 哗哗地烧模型还容易「记岔」。scratchpad-mcp 就是冲着这个痛点来的——它是一个基于 MCPModel Context Protocol的持久化草稿区服务用 Node.js 启动、SQLite 落盘让 Claude 这类代理把「临时记忆」写到本地数据库里需要时按版本、按游标读回来而不是每次都把整份文件重新灌进上下文。一句话概括它的定位AI 代理的持久化、令牌高效存储层。它不负责推理也不替代你的编辑器只干一件事——把代理的工作文档、操作日志、摘要缓存管起来并且用「自上次查看后有何变化」这种结构化差异返回而不是甩一整坨内容给你。它适合谁我梳理了三类第一类是跑 Claude Code、Cline 这类编码代理的开发者。代理在改一个几百行的文件时每次都要重读全文scratchpad-mcp 可以只返回行级 diff代理推理变化内容更省 token。第二类是做多轮对话或 Agent 编排的人。多轮之间上下文容易丢把中间状态写进 scratchpad下一轮用read_file带since_version拉差异上下文保持得更稳。第三类是单机单用户的个人开发者。它的安全模型就是「每用户每服务器进程」agent_id是明文参数、没有身份验证天生适合单租户部署不适合多租户待机。核心能力可以拆成几块版本化写入每次写入自动留版本保留最近 10 个、仅追加日志基于游标分页每页 100 条、按需摘要对长文件用 Claude Haiku 生成摘要并按版本缓存、每代理命名空间一个实例服务多个代理不串状态、行级差异格式、单文件 SQLite 存储。存储后端就是一个scratchpad.db默认在项目根目录也能用环境变量改路径。理解了这层定位后面配置和验证就顺了。它本质是个本地 MCP serverClaude 通过 MCP 协议调用它暴露的工具工具列表包括write_file、read_file、append_log、read_log、list_files、delete_file、summarize_file、get_usage_stats。下面我按「先备好通道、再写配置、再验证、再排障」的顺序走一遍。2. 前置准备Node.js 环境与 TaoToken 统一通道在写 MCP 配置之前有两件事要先落地本地运行时以及模型调用的 endpoint。scratchpad-mcp 本身是 Node.js 服务环境要求 Node.js 20 和 npm而它里面唯一会调用外部模型的地方是summarize_file需要ANTHROPIC_API_KEY。如果你希望把这类模型调用统一收口可以把 endpoint 指到 TaoToken 的统一通道这样 key 和地址管理都在一处换模型也不用改一堆配置。先说本地环境。Node.js 版本别低于 20低版本在 ESM 和部分内置模块上会出问题。装好后确认一下node -v npm -v正常应该输出 v20.x 或更高。如果版本不对去 Node 官网下 LTS 包重装即可这一步没有玄学。再说模型通道。scratchpad-mcp 的summarize_file走的是 Anthropic 风格的接口默认读ANTHROPIC_API_KEY。你可以直接在 TaoToken 控制台生成一个 key然后把 Base URL 指向统一通道。TaoToken 的 API 地址是https://taotoken.net/api官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。生成 key 的页面在控制台的 API Keys 区接入文档在 doc 区这两个链接后面 CTA 会再给一次。这里要强调一个容易踩的点summarize_file是可选能力。如果你暂时不做长文件摘要完全可以先不配ANTHROPIC_API_KEY服务照样能启动write_file、read_file、append_log这些核心工具都不依赖它。只有当你调用summarize_file时才会真正发起模型请求。所以第一次跑通建议先不配 key把读写链路验证完再补摘要能力。关于安全模型文档写得很直白agent_id是明文工具参数没有身份验证设计为每用户每服务器进程适合单租户部署。这意味着你别把它暴露到公网也别指望它做多租户隔离。SQL 层面所有参数都是参数化的没有注入风险路径校验会拒绝..、前导/、空格以及[a-zA-Z0-9/_.-]以外的字符。这些约束你在传path参数时要心里有数比如别传带空格的路径。把这两件事备齐就可以进入配置环节了。我建议的顺序是先 clone 构建再写 Claude Desktop 的 MCP 配置最后启动验证。3. 可复制配置Claude Desktop 的 mcpServers 片段这一节给你能直接抄的配置。scratchpad-mcp 的接入方式是在 Claude Desktop 的配置文件里加一个mcpServers条目command用nodeargs指向构建产物dist/index.jsenv里放可选的环境变量。先安装和构建。假设你把仓库放在C:\tools\scratchpad-mcpWindows或~/tools/scratchpad-mcpmacOS/Linuxgit clone this repo cd scratchpad-mcp npm install npm run build构建完成后产物在dist/index.js。接下来是 Claude Desktop 的配置。Windows 下配置文件通常在%APPDATA%\Claude\claude_desktop_config.jsonmacOS 在~/Library/Application Support/Claude/claude_desktop_config.json。写入下面这段{ mcpServers: { scratchpad: { command: node, args: [C:\\path\\to\\scratchpad-mcp\\dist\\index.js], env: { ANTHROPIC_API_KEY: sk-ant-..., SCRATCHPAD_DB_PATH: C:\\path\\to\\scratchpad.db } } } }几个字段说明一下。command是node前提是 node 在系统 PATH 里如果不在得写 node 的绝对路径。args数组里是dist/index.js的绝对路径Windows 下反斜杠要转义成\\。env里ANTHROPIC_API_KEY只在你要用summarize_file时才需要不用摘要可以删掉这一行SCRATCHPAD_DB_PATH是自定义数据库路径不写就默认项目根目录的scratchpad.db。如果你要把模型调用收口到 TaoToken 统一通道除了 key还要让服务知道 Base URL。Anthropic SDK 一般读ANTHROPIC_BASE_URL这类环境变量你可以在env里补上{ mcpServers: { scratchpad: { command: node, args: [/Users/you/tools/scratchpad-mcp/dist/index.js], env: { ANTHROPIC_API_KEY: 你的 TaoToken Key, ANTHROPIC_BASE_URL: https://taotoken.net/api, SCRATCHPAD_DB_PATH: /Users/you/tools/scratchpad.db } } } }这里三件套要写全Base URL是https://taotoken.net/apiKey用你在控制台生成的Model ID在summarize_file内部指定默认走 Haiku 类模型具体以服务实现为准。如果你用的是 Cline 或 CC Switch 这类工具配置思路一致都是把 MCP server 的启动命令和 env 填进去区别只在配置文件位置和字段名。改完配置要重启 Claude DesktopMCP server 才会重新加载。重启后可以在对话里让它列出可用工具看到write_file、read_file这些就说明挂载成功。下面进入验证环节。4. 验证请求一次写入、读取与差异确认配置挂上不等于链路通得实际跑一次读写。我建议按「写 → 读全文 → 改 → 读差异 → 看统计」这个顺序验证每一步都能确认一个能力点。第一步写入一个文件。让 Claude 调用write_file参数是agent_id、path、content{ agent_id: demo-agent, path: notes/plan.md, content: 第一行初始化\n第二行待办\n第三行结束 }agent_id是命名空间同一个实例下不同 agent 互不干扰。path要符合路径校验规则别带空格和..。写入成功后服务会自动版本化保留最近 10 个版本。第二步读全文。调用read_file只传agent_id和path{ agent_id: demo-agent, path: notes/plan.md }应该返回你刚写的三行内容。这一步确认基础读写通了。第三步改内容再读差异。再调一次write_file把第二行改掉{ agent_id: demo-agent, path: notes/plan.md, content: 第一行初始化\n第二行已完成\n第三行结束 }然后调read_file带上since_version指向上一版{ agent_id: demo-agent, path: notes/plan.md, since_version: 1 }返回的应该是行级 diff结构类似{ diff: [ { op: equal, lines: [第一行初始化] }, { op: remove, lines: [第二行待办] }, { op: add, lines: [第二行已完成] }, { op: equal, lines: [第三行结束] } ] }看到remove和add成对出现说明版本化差异生效了。这正是它省 token 的关键——代理不用重读全文只看变化行。第四步追加日志并分页读。调append_log{ agent_id: demo-agent, path: notes/plan.md, entry: 完成第二行修改 }它会返回新条目 ID。再用read_log带since_entry游标读每页 100 条。这一步验证仅追加日志和游标分页。第五步看统计。调get_usage_stats传agent_id返回该代理的总字节数、文件数、日志数和总操作数。如果数字对得上说明整条链路都通了。如果你配了 TaoToken 通道可以再调一次summarize_file验证模型调用{ agent_id: demo-agent, path: notes/plan.md }它对超过 8000 字符的长文件才走摘要短文件可能直接返回或提示无需摘要。想验证模型通道可以写一个长文件再试。成功返回摘要说明 Base URL 和 Key 都生效了。5. 常见报错排查401、local proxy failed 与 reading choices跑不通的时候报错信息往往指向很具体的问题。我把几类高频错误和对应排查列出来你对照着看。401 未授权。这个基本出现在summarize_file调用时说明ANTHROPIC_API_KEY无效或没配。先确认 key 有没有写进env再确认 key 本身没过期。如果你走 TaoToken 通道检查ANTHROPIC_BASE_URL是不是https://taotoken.net/api以及 key 是不是在控制台 API Keys 页面生成的。401 不会影响write_file这些本地工具所以如果你只做读写验证却报 401那多半是误触了摘要工具。local proxy failed。这类错误通常和网络出口或 Base URL 配置有关。先确认ANTHROPIC_BASE_URL拼写正确、没有多余斜杠再确认本机网络能正常访问该地址。如果你没配 Base URL 却报这个检查是不是环境里残留了其他代理变量。注意这里说的是配置层面的地址问题不涉及任何网络工具的使用建议。reading choices 相关报错。这通常出现在模型返回结构不符合预期时比如摘要接口返回的 JSON 里没有choices字段。排查方向确认 Base URL 指向的是兼容 Anthropic 接口的通道而不是 OpenAI 风格接口确认 Model ID 是服务支持的模型。如果换了模型后突然报这个多半是模型名写错或该模型不走这个接口。OAuth 相关报错。如果你用的是 Claude Code 或带 OAuth 的客户端可能遇到 token 过期或授权失效。这类问题一般重新登录授权即可和 scratchpad-mcp 本身无关。但如果 OAuth 报错和 MCP 挂载同时出现先确认 MCP server 进程有没有正常启动——node dist/index.js手动跑一下看有没有抛异常。服务启动即退出。手动执行node dist/index.js如果报模块找不到说明npm run build没成功重新构建。如果报数据库路径不可写检查SCRATCHPAD_DB_PATH指向的目录是否存在、有没有写权限。路径被拒绝。传了带空格、..或前导/的path服务会直接拒绝。改成notes/plan.md这种干净相对路径即可。版本对不上。since_version传了一个不存在的版本号可能返回空差异或报错。先用list_files看文件元数据确认当前版本范围。排查的核心思路是先分清是本地工具问题还是模型调用问题。本地工具报错看路径、看数据库、看进程模型调用报错看 key、看 Base URL、看 Model ID。把这两类分开定位会快很多。6. 把链路固定下来从验证到日常使用验证通过之后建议把配置固化别每次手动折腾。几个实用习惯分享给你。第一数据库路径固定到一个专门目录别用默认的项目根目录。项目一多scratchpad.db散落各处不好管。用SCRATCHPAD_DB_PATH统一指到~/scratchpad/data.db这类位置备份和清理都方便。第二agent_id按用途命名比如coding-agent、doc-agent别所有任务共用一个。命名空间隔离是它的核心设计用好了多任务互不串状态。第三长文件才用summarize_file短文件没必要。摘要按版本缓存同一版本重复调用不会重复计费但跨版本会重新生成。控制好写入频率能省不少模型调用。第四日志用游标分页读别一次拉全量。read_log每页 100 条配合since_entry增量读代理回放历史更高效。第五定期用get_usage_stats看配额。每代理文件配额 1000 个、日志配额 10 万条、总存储 100 MB接近上限时清理旧文件。单次写入上限 1 MB、单条日志 64 KB超了会被拒。如果你要把模型调用长期收口TaoToken 的 Coding Plan 适合长期编码和 Agent 场景模型对话页面适合临时验证模型是否通API Keys 和接入文档适合排障和接入。这几个入口按需取用排障与接入API Keys 在https://taotoken.net/api-keys接入文档在https://taotoken.net/doc验证模型是否通模型对话在https://taotoken.net/chat长期编码与 AgentCoding Plan 在https://taotoken.net/coding-plan把 scratchpad-mcp 挂上、把 endpoint 指到统一通道、把读写验证跑一遍这套临时记忆层就算落地了。后面代理再跑长任务token 消耗和上下文稳定性都会有肉眼可见的改善。