1. 文档散落一地的痛我懂为什么需要本地知识库检索系统你有没有过这种体验写代码时想查自己三个月前写的接口文档得先打开文件管理器翻三层目录找到那个api-spec-v3-final-真的最终版.md复制一段切回 AI 对话框粘贴然后问“这个字段什么意思”。问完发现少复制了一段又切回去找。一天下来复制粘贴的次数比敲代码还多。这就是典型的碎片化信息黑洞。你的知识散落在 Markdown 笔记、PDF 报告、Word 文档、代码注释、README 里AI 看不到它们只能靠你当“人肉搬运工”。更麻烦的是当你把一堆文档拖进对话框模型受限于上下文长度要么读不完要么“迷失在中部”——开头结尾记得住中间的关键信息被忽略。MCPModel Context Protocol解决的就是这个问题。它让 AI 工具能够以标准化方式调用你本地的检索能力。你不再需要手动复制而是让模型自己决定“我需要查一下知识库”然后通过 MCP 协议调用你写的搜索工具毫秒级拿到最相关的文档片段自动注入到当前对话上下文里。这套方案适合谁适合所有本地文档超过 50 篇、经常需要跨文档查资料的人。开发者、产品经理、研究人员、写作者都算。你不需要把文档上传到任何云端所有索引和检索都在本机完成隐私可控。我试过把 200 多篇技术笔记和 PDF 报告接入这套系统现在问 AI “我之前记录的 Redis 持久化配置注意事项”它直接返回我半年前写的那段笔记连文件名和行号都标出来了。整个过程不到 300 毫秒。下面我会从零开始带你搭一套可运行的本地知识库检索系统。核心组件有三个TaoToken 统一 API 通道负责模型调用MCP Server负责检索逻辑本地向量库负责存储和语义匹配。每一步都有可复制的配置和代码。2. TaoToken 前置准备统一 Key 与 API 通道配置在动手写 MCP Server 之前先把模型调用的通道打通。为什么需要 TaoToken因为你的 MCP Server 在检索到文档片段后可能需要调用 Embedding 模型把文本转向量或者调用对话模型做 Reranking。如果每个模型都单独配 Key、单独管 Base URL维护成本很高。TaoToken 提供统一的 API 入口一个 Key 走通所有模型调用。2.1 获取 API Key 与确认 Base URL首先访问 TaoToken 官网注册账号然后在控制台的 API Keys 页面创建一个新 Key。建议给这个 Key 起个名字叫mcp-knowledge-local方便后续排查。创建完成后你会拿到一串以sk-开头的密钥。把它保存到本地环境变量里不要硬编码在代码中# Linux / macOS export TAOTOKEN_API_KEYsk-你的密钥 # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的密钥TaoToken 的 API Base URL 是https://taotoken.net/api注意这个地址后面不加任何路径具体端点由 SDK 或 HTTP 客户端拼接。比如调用对话模型时完整地址是https://taotoken.net/api/v1/chat/completions。2.2 验证 Key 是否可用在写复杂代码之前先用一条 curl 命令确认 Key 能正常工作curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }如果返回的 JSON 里有choices字段且内容包含OK说明通道正常。如果返回 401检查 Key 是否复制完整、环境变量是否生效。如果返回local proxy failed说明网络层有问题检查你的网络配置是否能访问taotoken.net。2.3 在 MCP Server 中读取 KeyMCP Server 通常以子进程方式运行环境变量需要显式传递。在后续的配置文件中我们会把TAOTOKEN_API_KEY写进env字段。这样 Server 启动时就能读到不需要额外加载.env文件。如果你用的是 Claude Code 或 Cline 这类支持 MCP 的客户端它们的配置文件里都有env段落直接填进去即可。下面第三节会给出完整配置。3. 可复制配置MCP Server 与知识库索引脚本这一节是核心。我会先给出 MCP Server 的完整配置片段再给出知识库索引脚本最后说明如何把两者串起来。3.1 MCP Server 配置文件JSON 格式假设你用的是 Claude Code 或 Cline它们的 MCP 配置通常放在~/.claude/claude_desktop_config.json或项目根目录的.mcp.json里。以下是一个完整的配置片段路径和字段名与官方文档一致{ mcpServers: { local-knowledge: { command: node, args: [/Users/yourname/mcp-knowledge-bridge/dist/index.js], env: { TAOTOKEN_API_KEY: sk-你的密钥, TAOTOKEN_BASE_URL: https://taotoken.net/api, KNOWLEDGE_DIR: /Users/yourname/Documents/knowledge-base, LANCEDB_PATH: /Users/yourname/mcp-knowledge-bridge/.lancedb } } } }三个关键点command指向 Node 可执行文件args指向编译后的 Server 入口env里放 TaoToken 的 Key 和 Base URL以及知识库目录和向量库路径。KNOWLEDGE_DIR是你存放所有文档的根目录LANCEDB_PATH是向量数据落盘的位置。如果你用的是 Codex它的auth.json配置方式不同但核心三件套一样Base URL 填https://taotoken.net/apiKey 填sk-开头的密钥Model ID 填你实际调用的模型名如gpt-4o-mini或text-embedding-3-small。3.2 知识库索引脚本TypeScript这个脚本负责扫描KNOWLEDGE_DIR下的所有.md、.txt、.pdf文件分块后调用 TaoToken 的 Embedding 接口生成向量写入 LanceDB。import * as fs from fs; import * as path from path; import * as lancedb from lancedb/lancedb; import pdf from pdf-parse; const KNOWLEDGE_DIR process.env.KNOWLEDGE_DIR || ./knowledge-base; const LANCEDB_PATH process.env.LANCEDB_PATH || ./.lancedb; const API_KEY process.env.TAOTOKEN_API_KEY!; const BASE_URL process.env.TAOTOKEN_BASE_URL || https://taotoken.net/api; const CHUNK_SIZE 500; const CHUNK_OVERLAP 50; async function getEmbedding(text: string): Promisenumber[] { const res await fetch(${BASE_URL}/v1/embeddings, { method: POST, headers: { Authorization: Bearer ${API_KEY}, Content-Type: application/json, }, body: JSON.stringify({ model: text-embedding-3-small, input: text, }), }); const data await res.json(); return data.data[0].embedding; } function chunkText(text: string): string[] { const chunks: string[] []; let start 0; while (start text.length) { const end Math.min(start CHUNK_SIZE, text.length); chunks.push(text.slice(start, end)); start CHUNK_SIZE - CHUNK_OVERLAP; } return chunks; } async function indexFile(filePath: string) { const ext path.extname(filePath).toLowerCase(); let content ; if (ext .pdf) { const buffer fs.readFileSync(filePath); const parsed await pdf(buffer); content parsed.text; } else if ([.md, .txt].includes(ext)) { content fs.readFileSync(filePath, utf-8); } else { return; } const chunks chunkText(content); const db await lancedb.connect(LANCEDB_PATH); const table await db.openTable(documents).catch(() null); const records []; for (const chunk of chunks) { const vector await getEmbedding(chunk); records.push({ filename: path.basename(filePath), filepath: filePath, text: chunk, vector, }); } if (table) { await table.add(records); } else { await db.createTable(documents, records); } console.log(Indexed ${records.length} chunks from ${filePath}); } async function walkDir(dir: string) { const entries fs.readdirSync(dir, { withFileTypes: true }); for (const entry of entries) { const fullPath path.join(dir, entry.name); if (entry.isDirectory()) { await walkDir(fullPath); } else { await indexFile(fullPath); } } } walkDir(KNOWLEDGE_DIR).then(() console.log(Indexing complete.));运行方式npx ts-node index.ts首次运行会遍历所有文档并生成向量200 篇文档大约需要 2-3 分钟。之后新增文档时重新运行即可LanceDB 支持增量追加。3.3 MCP Server 主逻辑检索工具Server 的核心是暴露一个search_local_docs工具接收查询字符串返回最相关的文档片段。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { ListToolsRequestSchema, CallToolRequestSchema, } from modelcontextprotocol/sdk/types.js; import * as lancedb from lancedb/lancedb; const LANCEDB_PATH process.env.LANCEDB_PATH || ./.lancedb; const API_KEY process.env.TAOTOKEN_API_KEY!; const BASE_URL process.env.TAOTOKEN_BASE_URL || https://taotoken.net/api; const server new Server( { name: local-knowledge-expert, version: 1.0.0 }, { capabilities: { tools: {} } } ); async function getEmbedding(text: string): Promisenumber[] { const res await fetch(${BASE_URL}/v1/embeddings, { method: POST, headers: { Authorization: Bearer ${API_KEY}, Content-Type: application/json, }, body: JSON.stringify({ model: text-embedding-3-small, input: text, }), }); const data await res.json(); return data.data[0].embedding; } server.setRequestHandler(ListToolsRequestSchema, async () ({ tools: [ { name: search_local_docs, description: 在本地知识库中进行语义搜索返回最相关的文档片段, inputSchema: { type: object, properties: { query: { type: string, description: 搜索关键词或问题描述 }, topK: { type: number, description: 返回结果数量, default: 3 }, }, required: [query], }, }, ], })); server.setRequestHandler(CallToolRequestSchema, async (request) { const { name, arguments: args } request.params; if (name ! search_local_docs) throw new Error(Tool not found); const query args?.query as string; const topK (args?.topK as number) || 3; const queryVector await getEmbedding(query); const db await lancedb.connect(LANCEDB_PATH); const table await db.openTable(documents); const results await table .search(queryVector) .limit(topK) .toArray(); const formatted results .map((r: any) [来源: ${r.filename}]\n内容: ${r.text}\n---) .join(\n); return { content: [{ type: text, text: formatted }] }; }); const transport new StdioServerTransport(); await server.connect(transport);编译后把dist/index.js的路径填进第 3.1 节的配置文件重启客户端即可。4. 验证请求与成功结果毫秒级上下文注入实测配置完成后怎么确认整套系统跑通了分三步验证。4.1 验证 MCP Server 是否被客户端识别在 Claude Code 里输入/mcp命令或者在 Cline 的 MCP 面板里查看应该能看到local-knowledge这个 Server 处于 connected 状态。如果显示 failed检查args路径是否正确、Node 版本是否 ≥ 18。4.2 手动触发一次检索在对话里直接问一个你知识库里有的问题比如“我之前记录的 Redis 持久化配置注意事项”。模型会自动调用search_local_docs工具你会在工具调用日志里看到类似输出[来源: redis-notes.md] 内容: RDB 持久化默认每 900 秒至少 1 个 key 变化时触发快照... --- [来源: redis-notes.md] 内容: AOF 持久化 appendfsync everysec 是折中方案... ---从发起查询到返回结果实测在 200-400 毫秒之间。这个延迟主要花在 Embedding 接口调用上向量检索本身在 LanceDB 里是亚毫秒级的。4.3 验证上下文注入效果关键看模型是否真的用了检索到的内容。你可以问一个只有你文档里才有的细节比如“我笔记里写的那个 Redis 最大内存配置是多少”。如果模型回答出具体数值说明上下文注入成功。如果模型说“我不知道”检查两个地方一是search_local_docs是否被调用二是返回的片段是否包含答案。一个实用技巧在 MCP Server 返回内容前加一行console.error打印查询和结果数量这样在客户端日志里能看到每次检索的命中情况。注意用console.error而不是console.log因为 Stdio 传输下console.log会污染协议消息。5. 本篇常见错排查401、local proxy failed、reading choices搭建过程中最容易踩的坑集中在几个报错上我逐个拆解。5.1 401 Unauthorized这是最常见的。原因通常是 Key 没传对。检查顺序第一env里的TAOTOKEN_API_KEY是否以sk-开头且没有多余空格第二MCP Server 启动时是否真的读到了这个环境变量可以在代码开头加console.error(process.env.TAOTOKEN_API_KEY?.slice(0, 8))确认第三如果用的是 Codex 的auth.json确认字段名是api_key而不是apiKey。5.2 local proxy failed这个报错说明请求根本没到达 TaoToken 的服务器。检查TAOTOKEN_BASE_URL是否写成了https://taotoken.net/api注意末尾没有斜杠。如果你在代码里拼接路径时写成了${BASE_URL}/v1/embeddings实际请求地址是https://taotoken.net/api/v1/embeddings这是正确的。如果写成${BASE_URL}v1/embeddings就会变成https://taotoken.net/apiv1/embeddings导致失败。5.3 reading choices 报错这个报错通常出现在解析模型返回时。如果你调用的是对话模型做 Reranking返回结构里应该有choices数组。报错说明返回的 JSON 结构不符合预期可能是模型名写错了或者接口返回了错误信息。建议在解析前先打印完整响应体const data await res.json(); console.error(JSON.stringify(data, null, 2));这样能看到实际返回了什么。常见原因是模型 ID 拼写错误比如把gpt-4o-mini写成了gpt-4-mini。5.4 OAuth 相关报错如果你用的是 Claude Code 的 OAuth 登录模式MCP Server 的环境变量可能不会自动继承。解决方法是在配置文件的env里显式写全三件套TAOTOKEN_API_KEY、TAOTOKEN_BASE_URL、KNOWLEDGE_DIR。不要依赖 shell 的export因为 MCP Server 是客户端拉起的子进程环境变量隔离。5.5 检索结果为空如果工具被调用了但返回空检查 LanceDB 表里是否有数据。可以用一个简单的脚本查一下const db await lancedb.connect(LANCEDB_PATH); const table await db.openTable(documents); console.log(await table.countRows());如果行数为 0说明索引脚本没跑成功。回头检查KNOWLEDGE_DIR路径是否正确、文件后缀是否在支持列表里。6. 从检索到推理让 AI 真正“读过你的笔记”整套系统跑通后你的工作流会变成这样在 AI 对话框里直接问“帮我找一下之前写的那个关于消息队列选型的对比”模型自动调用search_local_docs300 毫秒内返回你三个月前写的笔记片段然后基于这些片段给出回答。你不需要打开任何文件管理器不需要复制任何东西。如果想进一步优化有两个方向。一是父子块检索索引时同时存小片段和大段落检索命中子块后返回父块给模型更完整的上下文。二是Reranking向量检索返回 10 条后用 TaoToken 调一个轻量级对话模型对这 10 条做相关性排序只取前 3 条注入。这样能显著降低噪音。如果你需要长期在编码场景里用这套能力可以考虑 TaoToken 的 Coding Plan它针对高频 Agent 调用做了通道优化。模型对话调试可以在模型对话页面直接测试。API Key 管理在 API Keys 页面。接入文档在 doc 页面有更详细的参数说明。最后说一个实用技巧把KNOWLEDGE_DIR指向你的 Obsidian 或 Logseq 仓库根目录每次写完笔记后跑一次索引脚本AI 就永远读的是最新版本。索引脚本可以挂到 Git hook 或文件监听上实现自动更新。这样你只管写检索和注入交给系统。