🚀 告别海外账号与网络限制！稳定直连全球优质大模型，限时半价接入中。 👉 点击领取海量免费额度
1. 先把目标定清楚：一个能读本地目录的 MCP 文件检索服务
MCP（Model Context Protocol）这两年从「概念演示」变成了「真能干活」的东西。它的核心价值很朴素：让模型在对话过程中，能主动调用你本机或内网的工具，而不是只靠你手动复制粘贴。文件检索就是最典型的场景——你有一堆 Markdown、日志、代码片段散在某个目录里，想让模型帮你找「哪份文档写了限流策略」「哪个配置文件定义了超时时间」，手动翻太慢，直接全量塞进上下文又太贵。
这篇要做的，是一个最小可用的 MCP 文件检索服务：它暴露一个工具，接收查询关键词，扫描指定本地目录，返回匹配文件的路径和命中片段。模型侧用 Qwen3.7 Flash，客户端用 Cline 或 Claude Desktop 二选一验证。整个链路里，TaoToken 出现在「给 MCP 客户端拿 Key」这一步——你先去 https://taotoken.net/?utm_source=taotoken_aicg_blog_generate&utm_medium=csdn&utm_campaign=generate 创建一个 Key，然后把客户端的 Base URL 指向 https://taotoken.net/api，模型请求就走通了。
适合谁：已经在用 Cline / Claude Desktop 做本地开发、想让模型读自己项目文档的人；或者想理解 MCP server 到底怎么写、怎么接的人。不需要你懂协议细节，但需要你会跑 Node 或 Python 命令。
产物清单：一个mcp.json配置、一条启动命令、一份调用日志。下面按「写服务 → 配客户端 → 验证 → 排错」的顺序来。
2. 写一个最小 MCP 文件检索服务
MCP server 的本质是一个通过 stdio（标准输入输出）和客户端通信的进程。客户端启动它，它声明自己有哪些工具，客户端把模型的工具调用请求转发过来，它执行完把结果返回。所以我们要写的，就是一个「声明工具 + 实现工具」的小程序。
我用 Node 写，因为 Cline 和 Claude Desktop 对 Node 版 MCP server 的支持最顺。先建目录：
mkdir mcp-file-search && cd mcp-file-search npm init -y npm install @modelcontextprotocol/sdk然后写server.js。核心逻辑：递归扫描目标目录，对每个文本文件做关键词匹配，返回命中的文件路径和上下文片段。
// server.js import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js"; import fs from "fs"; import path from "path"; // 要检索的根目录，通过环境变量传入，默认当前目录 const ROOT = process.env.SEARCH_ROOT || process.cwd(); const MAX_FILES = 200; // 最多扫描文件数，防止卡死 const MAX_SNIPPET = 400; // 每个命中片段最大字符数 const TEXT_EXT = new Set([ ".md", ".txt", ".js", ".ts", ".json", ".yaml", ".yml", ".py", ".go", ".java", ".sh", ".env", ".toml", ".ini", ]); function walk(dir, acc = []) { if (acc.length >= MAX_FILES) return acc; let entries; try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return acc; } for (const e of entries) { if (acc.length >= MAX_FILES) break; if (e.name.startsWith(".") || e.name === "node_modules") continue; const full = path.join(dir, e.name); if (e.isDirectory()) walk(full, acc); else if (TEXT_EXT.has(path.extname(e.name).toLowerCase())) acc.push(full); } return acc; } function search(keyword) { const files = walk(ROOT); const results = []; const lower = keyword.toLowerCase(); for (const f of files) { let content; try { content = fs.readFileSync(f, "utf-8"); } catch { continue; } const lines = content.split("\n"); for (let i = 0; i < lines.length; i++) { if (lines[i].toLowerCase().includes(lower)) { const start = Math.max(0, i - 2); const end = Math.min(lines.length, i + 3); const snippet = lines.slice(start, end).join("\n").slice(0, MAX_SNIPPET); results.push({ file: path.relative(ROOT, f), line: i + 1, snippet, }); break; // 每个文件只取第一处命中，避免刷屏 } } if (results.length >= 20) break; } return results; } const server = new Server( { name: "file-search", version: "0.1.0" }, { capabilities: { tools: {} } } ); server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: "search_files", description: "在本地目录中按关键词检索文本文件，返回文件路径、行号和上下文片段", inputSchema: { type: "object", properties: { keyword: { type: "string", description: "要检索的关键词" }, }, required: ["keyword"], }, }, ], })); server.setRequestHandler(CallToolRequestSchema, async (req) => { if (req.params.name !== "search_files") { throw new Error(`未知工具: ${req.params.name}`); } const keyword = req.params.arguments?.keyword; if (!keyword) throw new Error("缺少 keyword 参数"); const hits = search(keyword); const text = hits.length ? hits.map((h) => `[${h.file}:${h.line}]\n${h.snippet}`).join("\n---\n") : `未找到包含「${keyword}」的文件片段`; return { content: [{ type: "text", text }] }; }); const transport = new StdioServerTransport(); await server.connect(transport);几个设计取舍说明一下。MAX_FILES和MAX_SNIPPET是硬性护栏，没有它们，一个几万文件的项目目录会让检索卡到超时。跳过node_modules和隐藏目录是常识性优化。每个文件只取第一处命中，是为了让返回结果可读——模型拿到 20 条带上下文的片段，比拿到 200 条单行匹配有用得多。
启动命令就是普通的 Node 进程，但注意：MCP server 走 stdio，不要在启动时往 stdout 打印任何调试信息，否则会污染协议流。要打日志就打到 stderr：
SEARCH_ROOT=/Users/you/project node server.js这条命令你手动跑会看到它「卡住」——这是正常的，它在等 stdin 输入。真正的启动由客户端负责。
3. 在 Cline / Claude Desktop 里接入 TaoToken 与这个服务
现在到了拿 Key 的环节。MCP 客户端本身要调用模型，模型请求需要一个可用的 API 入口。你访问 https://taotoken.net/?utm_source=taotoken_aicg_blog_generate&utm_medium=csdn&utm_campaign=generate 注册后，进控制台创建 Key，具体入口在 https://taotoken.net/console 和 https://taotoken.net/api-keys。创建完把 Key 复制出来，客户端配置里会用到。
以 Claude Desktop 为例，配置文件在~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。把模型入口和 MCP server 一起写进去：
{ "mcpServers": { "file-search": { "command": "node", "args": ["/Users/you/mcp-file-search/server.js"], "env": { "SEARCH_ROOT": "/Users/you/project", "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的TaoToken Key" } } } }Cline 的配置思路一样，在 MCP 设置里新增一个 server，command 填node，args 填 server.js 的绝对路径，env 里带上SEARCH_ROOT和模型相关的 Base URL / Key。Cline 的模型配置在设置面板里单独填，Base URL 同样指向 https://taotoken.net/api。
这里有个容易踩的坑：args里的路径必须是绝对路径。客户端启动 MCP server 时的工作目录不一定是你的项目目录，用相对路径会找不到文件。同理，SEARCH_ROOT也建议写绝对路径。
配置改完，重启客户端。Claude Desktop 完全退出再打开，Cline 重新加载窗口。重启后在工具列表里应该能看到search_files。
4. 验证一次检索问答，以及失败分支怎么查
重启后，在对话框里问一个需要读本地文件才能回答的问题，比如：「帮我在项目里找一下限流相关的配置，告诉我文件路径和具体参数。」
模型会发起search_files调用，参数是{"keyword": "限流"}或类似词。一次成功的调用日志大致长这样（stderr 侧）：
[mcp] server started: file-search v0.1.0 [mcp] tool call: search_files {"keyword":"限流"} [mcp] scanned 47 files under /Users/you/project [mcp] hits: 3 [mcp] return 3 snippets (max 400 chars each)客户端侧你会看到工具调用卡片展开，里面是三条命中片段，形如：
[config/rate-limit.yaml:12] enabled: true qps: 100 burst: 200 --- [docs/architecture.md:88] 网关层对每个租户做限流，默认 100 QPS ---模型拿到这些片段后，会组织成自然语言回答你。如果它答得对，说明整条链路通了：客户端 → MCP server → 本地文件 → 模型 → 回答。
失败分支按现象分：
工具列表里没有search_files。八成是 server 启动失败。手动跑一遍node /绝对路径/server.js，看有没有报错。常见的是@modelcontextprotocol/sdk没装、Node 版本太低（建议 18+）、或者server.js里用了 ESM 语法但package.json没加"type": "module"。
工具出现了，但调用报错。看客户端日志里的 stderr。如果是缺少 keyword 参数，说明模型传参格式不对，检查inputSchema是否声明正确。如果是ENOENT，检查SEARCH_ROOT路径是否存在。
模型请求 401 / 404。这是模型入口配置问题，不是 MCP 的问题。确认 Base URL 是 https://taotoken.net/api，Key 没有多余空格，且 Key 有对应模型的权限。排障细节可以对照 https://taotoken.net/doc 里的接入说明。
检索结果为空但文件里明明有。检查文件扩展名是否在TEXT_EXT白名单里，以及关键词大小写——代码里做了toLowerCase，但中文关键词不受影响，英文关键词要注意。
5. 限制、成本与模型选择
这个服务的边界要说清楚。它做的是字面关键词匹配，不是语义检索。你搜「限流」，它不会返回写着「rate limit」的文件。想要语义能力，得在 server 里接 embedding，那是另一个量级的工程。MAX_FILES=200也意味着大仓库会漏扫，生产用建议改成按需索引或加缓存。
成本主要来自模型侧。Qwen3.7 Flash 在这个场景里够用——工具调用格式稳定，返回片段后的总结也不需要多强的推理。如果你要处理的是长文档摘要或复杂多跳检索，可以换更强的模型，具体可选范围和计费以官网为准：https://taotoken.net/?utm_source=taotoken_aicg_blog_generate&utm_medium=csdn&utm_campaign=generate 。MCP server 本身跑在本地，不产生额外费用。
一个实用技巧：把SEARCH_ROOT指向你项目的docs/或config/子目录，而不是整个仓库根目录。扫描范围小，命中更准，模型拿到的上下文也更干净。我试过直接指仓库根目录，结果node_modules虽然跳过了，但一堆构建产物和 lock 文件还是混进来，噪音很大。
最后，如果你想让这个服务长期挂着用，Cline 的 Coding Plan 模式配合 MCP 会比较顺手，配置入口在 https://taotoken.net/coding-plan 。Claude Desktop 用户则注意每次改mcp.json都要完整重启，热加载不生效。
🚀 告别海外账号与网络限制！稳定直连全球优质大模型，限时半价接入中。 👉 点击领取海量免费额度
