1. 为什么 Inbound 外部读取总在握手这一步卡住如果你正在用 Obsidian 攒知识库又想让自己写的 Node.js MCP 服务能直接读里面的 Markdown那大概率会撞上同一个坑客户端显示已连接但工具列表是空的或者调用read_notes直接超时。这不是你代码写错了而是 MCP 的 Inbound 外部读取在协议握手阶段没谈拢。MCP 全称 Model Context Protocol你可以把它理解成 AI 客户端和本地数据源之间的一套“点菜协议”。Inbound 指的是外部请求进入你的服务端也就是客户端主动来读你的 Obsidian 笔记。协议握手就是双方第一次见面时交换能力清单你支持哪些方法、走 stdio 还是 HTTP、初始化参数对不对。这一步没走完后面所有读取都是空谈。这篇面向两类人一是用 Obsidian 做第二大脑、想让 AI 直接检索笔记的开发者二是用 Node.js 写 MCP Server、需要把本地文件暴露成标准接口的工程师。我会给出config.toml和settings.json两份可复制骨架演示怎么用 TaoToken 统一 Key 和 API 通道接入最后做一次握手连通性验证确认外部读取链路真的通了。整套流程我在本地跑过踩的坑会一并写出来。2. TaoToken 在 MCP 链路里的位置先说清楚 TaoToken 在这里扮演什么角色。MCP Server 本身只负责读文件、返回内容它不产生智能。真正要“理解”笔记的是背后的大模型。问题在于你写 Node.js 服务时如果每个模型都单独配一套 Key、一套 base_url代码里会散落一堆环境变量换模型就得改配置。TaoToken 提供的是统一 Key 和统一 API 通道。你申请一个 Key就能通过同一个入口调用不同模型MCP 服务里只需要维护一份凭证。官网在 https://taotoken.net API 入口是 https://taotoken.net/api 注意 API 地址不带查询参数直接填进配置即可。对 Inbound 外部读取来说这个统一通道的价值在于你的 Node.js MCP Server 在握手完成后需要把读到的笔记内容发给模型做总结或检索这一步的请求就走 TaoToken。Key 只配一次模型名按需切换不用动服务端代码。需要提前准备的Node.js 环境建议 LTS 版本node -v能出结果Obsidian 已安装且有一个真实的知识库目录一个支持 MCP 的客户端比如 Cherry Studio、Cursor 或 Claude DesktopTaoToken 的 API Key在控制台创建如果你还没建 Key可以先去 https://taotoken.net/api-keys 生成一个后面配置里会用到。3. 可复制的配置骨架这一节是核心两份配置文件直接抄改路径和 Key 就行。3.1 config.tomlMCP 服务端声明config.toml用来描述你的 MCP Server 基本信息包括传输方式、启动命令、以及调用模型时的通道。放在项目根目录。# MCP Server 基础声明 [mcp] name obsidian-inbound-reader version 0.1.0 protocol mcp transport stdio # 服务端启动入口 [server] command node args [./src/server.js] cwd /Users/yourname/projects/mcp-obsidian # 外部读取能力声明握手时返回给客户端 [capabilities.resources] list true read true [capabilities.tools] enabled true # 模型通道统一走 TaoToken [llm] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model deepseek-v3 # Obsidian 知识库根目录绝对路径 [vault] root /Users/yourname/Documents/MyVault include_ext [.md]几个关键点。transport stdio表示走标准输入输出这是本地 MCP 最常用的方式客户端会拉起你的 Node 进程通过管道通信。capabilities段是握手时双方核对的能力清单resources.list和resources.read对应列出文件和读取内容两个动作缺一个客户端就可能不显示工具。api_key_env指向环境变量名不要把 Key 明文写进 toml。3.2 settings.json客户端侧接入客户端这边用settings.json注册这个 MCP Server。不同客户端字段略有差异下面这份是通用结构Cherry Studio 和 Cursor 都能对应上。{ mcpServers: { obsidian-inbound: { command: node, args: [./src/server.js], cwd: /Users/yourname/projects/mcp-obsidian, env: { TAOTOKEN_API_KEY: sk-你的Key, VAULT_ROOT: /Users/yourname/Documents/MyVault }, type: stdio } } }command和args必须和config.toml里的[server]段一致否则客户端拉起的进程和你声明的不是同一个。env里注入 Key 和知识库路径Node 服务启动时用process.env.TAOTOKEN_API_KEY读取。type填stdio和传输方式对齐。注意路径里如果有空格JSON 里不用转义但 toml 里建议用引号包起来。Windows 下路径写成C:\\Users\\...双反斜杠。3.3 Node.js 服务端握手代码光有配置不够服务端得真的实现握手逻辑。下面是最小可运行骨架用官方 SDK。// src/server.js import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import fs from fs/promises; import path from path; const VAULT_ROOT process.env.VAULT_ROOT; const server new Server( { name: obsidian-inbound-reader, version: 0.1.0 }, { capabilities: { resources: {}, tools: {} } } ); // 握手后客户端会调用这个列出资源 server.setRequestHandler(resources/list, async () { const files await fs.readdir(VAULT_ROOT); return { resources: files .filter((f) f.endsWith(.md)) .map((f) ({ uri: obsidian://${f}, name: f, mimeType: text/markdown, })), }; }); // 读取具体文件内容 server.setRequestHandler(resources/read, async (req) { const fileName req.params.uri.replace(obsidian://, ); const fullPath path.join(VAULT_ROOT, fileName); const content await fs.readFile(fullPath, utf-8); return { contents: [{ uri: req.params.uri, mimeType: text/markdown, text: content }], }; }); const transport new StdioServerTransport(); await server.connect(transport);setRequestHandler注册的就是握手后客户端能调用的方法。resources/list返回文件清单resources/read返回内容。这两个 handler 注册成功Inbound 外部读取的协议层才算完整。4. 验证握手与外部读取配置写完得确认链路真的通了。分三步验证。第一步单独跑服务端确认进程能起来。export TAOTOKEN_API_KEYsk-你的Key export VAULT_ROOT/Users/yourname/Documents/MyVault node ./src/server.js如果没有任何报错、进程挂起等待输入说明 stdio 传输正常。MCP 服务端启动后不会打印东西它在等客户端发 JSON-RPC 消息这是正常现象。第二步在客户端里看连接状态。打开 Cherry Studio 或 Cursor 的 MCP 设置页找到你注册的obsidian-inbound状态灯应该是绿色。如果显示红色点开日志看具体报错常见的是路径不对或 Key 没注入。第三步实际发一次读取请求。在对话界面确认工具列表里出现了resources/list和resources/read然后输入请列出我知识库根目录下的 Markdown 文件读取其中最近修改的一篇总结它的核心观点。观察客户端是否调用了工具、返回了真实笔记内容。如果模型能说出你笔记里的具体信息说明 Inbound 外部读取链路完全打通。这一步走通后面接 Coding Plan 做长期编码任务或者接模型对话做检索都顺了。5. 握手阶段常见报错排查这一节列几个我实际遇到过的坑对照排查。工具列表为空状态灯却是绿色。这是最迷惑的情况。绿色只代表进程拉起来了不代表能力协商成功。检查capabilities段是否声明了resources以及服务端有没有注册对应的setRequestHandler。少一个客户端拿不到能力清单工具就是空的。报错spawn node ENOENT。客户端找不到 node 命令。原因通常是客户端启动时的 PATH 和你终端里的不一样。解决办法是在settings.json的command里写 node 的绝对路径用which node查出来填进去。握手超时日志显示initialize timeout。服务端启动太慢或者启动时抛了异常但没退出。检查server.js顶部有没有同步报错比如 import 路径写错。另外确认cwd指向的目录真实存在。读取返回空内容。握手没问题但VAULT_ROOT路径不对或者路径指向了 Obsidian 的配置目录而不是笔记目录。用ls $VAULT_ROOT确认能看到.md文件。Key 无效导致模型调用失败。握手和读取是本地行为不经过模型所以工具能列出但总结失败时问题在 TaoToken 通道。确认TAOTOKEN_API_KEY环境变量在服务端进程里能读到base_url 填的是https://taotoken.net/api不要多加斜杠或参数。提示排查时优先看客户端日志MCP 的报错信息基本都在那里比终端输出详细。6. 把这条链路用起来握手通了之后你的 Obsidian 知识库就变成了一个标准 MCP 数据源。接下来可以做的事把resources/read扩展成支持目录递归让 AI 能检索整个库或者在服务端加一个tools/call方法封装搜索逻辑让模型按关键词找笔记。如果你打算长期跑编码类或 Agent 类任务建议把模型通道切到 Coding Plan统一 Key 管理更省心入口在 https://taotoken.net/coding-plan 。日常验证模型是否正常响应可以直接用模型对话页面测一下地址是 https://taotoken.net/chat 。接入文档在 https://taotoken.net/doc 里面有各语言的调用示例Node.js 的写法可以直接对照。我自己的习惯是每次改完 MCP 服务端代码先单独node server.js跑一遍确认不崩再回客户端看状态灯最后发一条真实读取请求。三步都过才算这次改动没破坏握手。这套流程跑顺之后加新工具、换模型都只是改配置的事不用再动协议层。
第九天：协议握手 —— Inbound 外部读取，用 TaoToken 打通 MCP 与 Obsidian 的 Node.js 配置骨架
1. 为什么 Inbound 外部读取总在握手这一步卡住如果你正在用 Obsidian 攒知识库又想让自己写的 Node.js MCP 服务能直接读里面的 Markdown那大概率会撞上同一个坑客户端显示已连接但工具列表是空的或者调用read_notes直接超时。这不是你代码写错了而是 MCP 的 Inbound 外部读取在协议握手阶段没谈拢。MCP 全称 Model Context Protocol你可以把它理解成 AI 客户端和本地数据源之间的一套“点菜协议”。Inbound 指的是外部请求进入你的服务端也就是客户端主动来读你的 Obsidian 笔记。协议握手就是双方第一次见面时交换能力清单你支持哪些方法、走 stdio 还是 HTTP、初始化参数对不对。这一步没走完后面所有读取都是空谈。这篇面向两类人一是用 Obsidian 做第二大脑、想让 AI 直接检索笔记的开发者二是用 Node.js 写 MCP Server、需要把本地文件暴露成标准接口的工程师。我会给出config.toml和settings.json两份可复制骨架演示怎么用 TaoToken 统一 Key 和 API 通道接入最后做一次握手连通性验证确认外部读取链路真的通了。整套流程我在本地跑过踩的坑会一并写出来。2. TaoToken 在 MCP 链路里的位置先说清楚 TaoToken 在这里扮演什么角色。MCP Server 本身只负责读文件、返回内容它不产生智能。真正要“理解”笔记的是背后的大模型。问题在于你写 Node.js 服务时如果每个模型都单独配一套 Key、一套 base_url代码里会散落一堆环境变量换模型就得改配置。TaoToken 提供的是统一 Key 和统一 API 通道。你申请一个 Key就能通过同一个入口调用不同模型MCP 服务里只需要维护一份凭证。官网在 https://taotoken.net API 入口是 https://taotoken.net/api 注意 API 地址不带查询参数直接填进配置即可。对 Inbound 外部读取来说这个统一通道的价值在于你的 Node.js MCP Server 在握手完成后需要把读到的笔记内容发给模型做总结或检索这一步的请求就走 TaoToken。Key 只配一次模型名按需切换不用动服务端代码。需要提前准备的Node.js 环境建议 LTS 版本node -v能出结果Obsidian 已安装且有一个真实的知识库目录一个支持 MCP 的客户端比如 Cherry Studio、Cursor 或 Claude DesktopTaoToken 的 API Key在控制台创建如果你还没建 Key可以先去 https://taotoken.net/api-keys 生成一个后面配置里会用到。3. 可复制的配置骨架这一节是核心两份配置文件直接抄改路径和 Key 就行。3.1 config.tomlMCP 服务端声明config.toml用来描述你的 MCP Server 基本信息包括传输方式、启动命令、以及调用模型时的通道。放在项目根目录。# MCP Server 基础声明 [mcp] name obsidian-inbound-reader version 0.1.0 protocol mcp transport stdio # 服务端启动入口 [server] command node args [./src/server.js] cwd /Users/yourname/projects/mcp-obsidian # 外部读取能力声明握手时返回给客户端 [capabilities.resources] list true read true [capabilities.tools] enabled true # 模型通道统一走 TaoToken [llm] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model deepseek-v3 # Obsidian 知识库根目录绝对路径 [vault] root /Users/yourname/Documents/MyVault include_ext [.md]几个关键点。transport stdio表示走标准输入输出这是本地 MCP 最常用的方式客户端会拉起你的 Node 进程通过管道通信。capabilities段是握手时双方核对的能力清单resources.list和resources.read对应列出文件和读取内容两个动作缺一个客户端就可能不显示工具。api_key_env指向环境变量名不要把 Key 明文写进 toml。3.2 settings.json客户端侧接入客户端这边用settings.json注册这个 MCP Server。不同客户端字段略有差异下面这份是通用结构Cherry Studio 和 Cursor 都能对应上。{ mcpServers: { obsidian-inbound: { command: node, args: [./src/server.js], cwd: /Users/yourname/projects/mcp-obsidian, env: { TAOTOKEN_API_KEY: sk-你的Key, VAULT_ROOT: /Users/yourname/Documents/MyVault }, type: stdio } } }command和args必须和config.toml里的[server]段一致否则客户端拉起的进程和你声明的不是同一个。env里注入 Key 和知识库路径Node 服务启动时用process.env.TAOTOKEN_API_KEY读取。type填stdio和传输方式对齐。注意路径里如果有空格JSON 里不用转义但 toml 里建议用引号包起来。Windows 下路径写成C:\\Users\\...双反斜杠。3.3 Node.js 服务端握手代码光有配置不够服务端得真的实现握手逻辑。下面是最小可运行骨架用官方 SDK。// src/server.js import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import fs from fs/promises; import path from path; const VAULT_ROOT process.env.VAULT_ROOT; const server new Server( { name: obsidian-inbound-reader, version: 0.1.0 }, { capabilities: { resources: {}, tools: {} } } ); // 握手后客户端会调用这个列出资源 server.setRequestHandler(resources/list, async () { const files await fs.readdir(VAULT_ROOT); return { resources: files .filter((f) f.endsWith(.md)) .map((f) ({ uri: obsidian://${f}, name: f, mimeType: text/markdown, })), }; }); // 读取具体文件内容 server.setRequestHandler(resources/read, async (req) { const fileName req.params.uri.replace(obsidian://, ); const fullPath path.join(VAULT_ROOT, fileName); const content await fs.readFile(fullPath, utf-8); return { contents: [{ uri: req.params.uri, mimeType: text/markdown, text: content }], }; }); const transport new StdioServerTransport(); await server.connect(transport);setRequestHandler注册的就是握手后客户端能调用的方法。resources/list返回文件清单resources/read返回内容。这两个 handler 注册成功Inbound 外部读取的协议层才算完整。4. 验证握手与外部读取配置写完得确认链路真的通了。分三步验证。第一步单独跑服务端确认进程能起来。export TAOTOKEN_API_KEYsk-你的Key export VAULT_ROOT/Users/yourname/Documents/MyVault node ./src/server.js如果没有任何报错、进程挂起等待输入说明 stdio 传输正常。MCP 服务端启动后不会打印东西它在等客户端发 JSON-RPC 消息这是正常现象。第二步在客户端里看连接状态。打开 Cherry Studio 或 Cursor 的 MCP 设置页找到你注册的obsidian-inbound状态灯应该是绿色。如果显示红色点开日志看具体报错常见的是路径不对或 Key 没注入。第三步实际发一次读取请求。在对话界面确认工具列表里出现了resources/list和resources/read然后输入请列出我知识库根目录下的 Markdown 文件读取其中最近修改的一篇总结它的核心观点。观察客户端是否调用了工具、返回了真实笔记内容。如果模型能说出你笔记里的具体信息说明 Inbound 外部读取链路完全打通。这一步走通后面接 Coding Plan 做长期编码任务或者接模型对话做检索都顺了。5. 握手阶段常见报错排查这一节列几个我实际遇到过的坑对照排查。工具列表为空状态灯却是绿色。这是最迷惑的情况。绿色只代表进程拉起来了不代表能力协商成功。检查capabilities段是否声明了resources以及服务端有没有注册对应的setRequestHandler。少一个客户端拿不到能力清单工具就是空的。报错spawn node ENOENT。客户端找不到 node 命令。原因通常是客户端启动时的 PATH 和你终端里的不一样。解决办法是在settings.json的command里写 node 的绝对路径用which node查出来填进去。握手超时日志显示initialize timeout。服务端启动太慢或者启动时抛了异常但没退出。检查server.js顶部有没有同步报错比如 import 路径写错。另外确认cwd指向的目录真实存在。读取返回空内容。握手没问题但VAULT_ROOT路径不对或者路径指向了 Obsidian 的配置目录而不是笔记目录。用ls $VAULT_ROOT确认能看到.md文件。Key 无效导致模型调用失败。握手和读取是本地行为不经过模型所以工具能列出但总结失败时问题在 TaoToken 通道。确认TAOTOKEN_API_KEY环境变量在服务端进程里能读到base_url 填的是https://taotoken.net/api不要多加斜杠或参数。提示排查时优先看客户端日志MCP 的报错信息基本都在那里比终端输出详细。6. 把这条链路用起来握手通了之后你的 Obsidian 知识库就变成了一个标准 MCP 数据源。接下来可以做的事把resources/read扩展成支持目录递归让 AI 能检索整个库或者在服务端加一个tools/call方法封装搜索逻辑让模型按关键词找笔记。如果你打算长期跑编码类或 Agent 类任务建议把模型通道切到 Coding Plan统一 Key 管理更省心入口在 https://taotoken.net/coding-plan 。日常验证模型是否正常响应可以直接用模型对话页面测一下地址是 https://taotoken.net/chat 。接入文档在 https://taotoken.net/doc 里面有各语言的调用示例Node.js 的写法可以直接对照。我自己的习惯是每次改完 MCP 服务端代码先单独node server.js跑一遍确认不崩再回客户端看状态灯最后发一条真实读取请求。三步都过才算这次改动没破坏握手。这套流程跑顺之后加新工具、换模型都只是改配置的事不用再动协议层。
