1. 项目概述一个连接AI与实时信息的桥梁最近在折腾AI应用开发特别是围绕OpenAI的Assistant API和Claude的Tool Use功能时我一直在思考一个问题如何让这些强大的AI模型摆脱其知识库的“时间枷锁”获取到最新、最实时的网络信息无论是查询最新的产品发布、追踪某个新闻事件的进展还是获取实时的股价或天气都需要一个可靠的外部信息源。这就是我注意到uju777/mcp-server-naver-search这个项目的契机。本质上它是一个MCPModel Context Protocol服务器专门为AI模型提供了调用Naver韩国最大的搜索引擎进行网络搜索的能力。简单来说你可以把它理解为一个“翻译官”或“适配器”。AI模型如GPT-4、Claude 3本身无法直接打开浏览器搜索网页但它们可以通过标准的MCP协议向这个服务器发送一个搜索请求例如“帮我找一下最近三天关于三星Galaxy S24的评测文章”。这个服务器接收到请求后会去模拟用户行为实际访问Naver搜索将返回的搜索结果包括标题、链接、摘要等整理成结构化的数据再通过MCP协议回传给AI模型。这样AI在生成回答时就能引用这些新鲜的、实时的信息极大地提升了回答的准确性和时效性。这个项目非常适合两类开发者一是正在构建需要联网搜索功能的AI智能体Agent或聊天机器人的开发者二是希望扩展Claude Desktop、Cursor等已集成MCP客户端的工具能力的深度用户。通过集成这个服务器你可以轻松地为你的AI应用赋予“浏览互联网”的眼睛而且聚焦于韩语和韩国市场信息这是Google Search API等通用方案有时难以精准覆盖的领域。2. MCP协议与Naver搜索的价值解析2.1 为什么是MCPModel Context Protocol在深入代码之前我们必须先理解MCP是什么以及它为何成为AI工具生态中的重要一环。MCP是由Anthropic提出的一种开放协议旨在标准化AI模型与外部工具、数据源之间的通信方式。你可以把它想象成AI世界的“USB标准”或“插件接口规范”。在MCP架构下存在几个核心角色MCP客户端Client通常是AI模型本身或其运行环境如Claude Desktop、Cursor IDE、自建的AI应用。它负责发起工具调用请求。MCP服务器Server就像本项目是提供具体能力的服务端。它暴露一个或多个“工具Tools”给客户端调用。工具Tools服务器提供的具体功能例如naver_search。每个工具都有明确的输入参数和输出格式。其工作流程非常清晰客户端通过标准化的JSON-RPC消息告诉服务器“请调用naver_search工具参数是query‘某关键词’。” 服务器执行搜索然后将结构化的结果封装好通过同样的通道返回给客户端。这种设计的巨大优势在于解耦和标准化。AI应用开发者无需为每一个外部API如搜索、数据库、计算编写特定的、脆硬的集成代码只需要让AI模型学会调用MCP工具即可。而工具提供者服务器开发者则可以专注于把单一功能做深做透无需关心上游是哪个AI模型在调用。uju777/mcp-server-naver-search正是这样一个专注于“Naver搜索”单一功能的MCP服务器。它让任何兼容MCP的AI客户端都能立即获得搜索Naver的能力。2.2 选择Naver搜索的独特优势与场景你可能会问已经有那么多通用的搜索引擎API为什么还要专门做一个Naver的这恰恰是这个项目的精妙之处它解决的是特定市场下的精准需求。核心优势韩语及韩国本地化搜索的绝对优势Naver是韩国市场份额超过70%的国民搜索引擎。对于韩语关键词的处理、对韩国本地网站如.naver.com, .co.kr的收录和排序Naver的理解远超Google。如果你要查询韩国本地的新闻、博客Naver Blog、知识问答Naver Knowledge iN、购物Naver Shopping或地图信息Naver的结果相关性和时效性是无与伦比的。规避通用搜索API的限制许多免费的通用搜索API有速率限制、结果数量限制或者对商业用途收费高昂。而通过模拟浏览器访问Naver尽管需要谨慎处理反爬虫策略在某些低频、个人使用的场景下可能是一种灵活补充。为AI智能体提供区域化能力如果你在开发一个主要服务韩国用户或者需要处理大量韩语信息的AI智能体那么直接集成Naver搜索作为其“信息感官”远比让它使用可能带有“全球化偏见”的通用搜索要高效和准确。典型应用场景韩国市场调研AI助手自动搜索并总结韩国社交媒体上对某品牌或产品的舆论。韩语学习伴侣查询最新的韩语流行语、新闻事件为语言学习者提供真实语境材料。本地化客服机器人快速查找韩国本地的商家信息、营业时间、政策公告来回答用户查询。研究工具追踪韩国科技、娱乐、金融领域的动态并自动生成简报。注意使用此类模拟用户访问的服务器进行搜索必须严格遵守Naver的服务条款Robots协议尊重robots.txt文件并控制请求频率避免对目标服务器造成负担防止IP被封锁。本项目更适合用于个人学习、研究或低频度的合法数据获取。3. 项目架构与核心代码拆解3.1 技术栈与依赖分析这个项目通常基于Node.js环境构建这是构建轻量级网络服务和工具服务器的常见选择。我们来看其核心依赖这能帮助我们理解它的工作原理modelcontextprotocol/sdk这是MCP协议的官方JavaScript SDK。它是项目的基石用于创建MCP服务器实例、定义工具Tools、处理来自客户端的请求和发送响应。所有与MCP协议相关的通信逻辑都封装在此SDK中。puppeteer或playwright或axioscheerio这是执行实际搜索任务的核心。具体方案取决于实现方式无头浏览器方案Puppeteer/Playwright这种方式最接近真实用户。它能执行JavaScript渲染完整页面适合搜索结果页动态加载严重的场景。但开销较大启动慢。HTTP请求HTML解析方案Axios Cheerio这种方式更轻量、更快。直接向Naver搜索的URL发送HTTP GET请求然后使用Cheerio一个类似jQuery的库来解析返回的HTML提取搜索结果。这要求Naver的搜索结果页是相对静态的或者开发者能够逆向分析出包含数据的请求接口。可选依赖可能包括dotenv管理环境变量如代理设置、rate-limiter请求限流、logger日志记录等用于增强服务器的健壮性和可维护性。项目的package.json文件是理解其技术选型的入口。选择无头浏览器还是轻量级解析是一个关键的架构决策直接影响到服务器的性能、资源消耗和隐蔽性。3.2 核心工具Tool定义剖析MCP服务器的核心是向客户端声明自己提供了哪些“工具”。在src/index.js或server.js这样的主文件中我们会看到类似以下的核心代码结构import { Server } from modelcontextprotocol/sdk; import { doNaverSearch } from ./search.js; // 假设的搜索执行函数 const server new Server( { name: naver-search-server, version: 1.0.0 }, { capabilities: { tools: {} } } ); // 定义 naver_search 工具 server.setRequestHandler(tools/list, async () { return { tools: [ { name: naver_search, description: 使用Naver搜索引擎进行网络搜索并返回结构化结果。, inputSchema: { type: object, properties: { query: { type: string, description: 要搜索的关键词或短语。 }, maxResults: { type: number, description: 希望返回的最大结果数量例如10。, default: 10 } // 可能还有其他参数如 language, region 等 }, required: [query] } } ] }; });这段代码是服务器的“能力宣言”。它告诉MCP客户端“我这里有一个叫naver_search的工具你可以用。你需要给我一个query字符串参数我还能接受一个可选的maxResults数字参数。” 输入模式inputSchema的定义至关重要它使得AI模型能够理解如何正确地调用这个工具。3.3 搜索请求处理与结果解析逻辑当客户端调用naver_search工具时服务器会收到一个tools/call请求。处理函数是项目的核心业务逻辑所在server.setRequestHandler(tools/call, async (request) { if (request.params.name naver_search) { const { query, maxResults 10 } request.params.arguments; try { // 调用实际的搜索函数 const searchResults await doNaverSearch(query, maxResults); return { content: [ { type: text, text: JSON.stringify(searchResults, null, 2) // 返回格式化的JSON结果 } ] }; } catch (error) { return { content: [ { type: text, text: 搜索失败: ${error.message} } ], isError: true }; } } // ... 处理其他工具 });这里的doNaverSearch函数是“脏活累活”发生的地方。我们以Axios Cheerio方案为例深入其内部// search.js import axios from axios; import * as cheerio from cheerio; export async function doNaverSearch(query, maxResults) { // 1. 构建搜索URL。注意需要对查询字符串进行编码。 const encodedQuery encodeURIComponent(query); const searchUrl https://search.naver.com/search.naver?wherewebquery${encodedQuery}; // 2. 发送HTTP请求可添加User-Agent等头部模拟浏览器 const headers { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) ... }; const response await axios.get(searchUrl, { headers }); // 3. 使用Cheerio加载HTML const $ cheerio.load(response.data); const results []; // 4. 解析搜索结果。这是最需要根据Naver页面结构调整的部分。 // Naver的网页搜索结果通常包裹在特定的CSS类中例如 .total_wrap .api_txt_lines 等。 // 这里的选择器是示例实际需要开发者通过浏览器开发者工具分析确定。 $(.total_area .total_tit).each((index, element) { if (index maxResults) return false; // 达到数量限制则停止 const title $(element).text().trim(); const link $(element).attr(href); // 摘要可能在其他相邻元素中 const snippet $(element).closest(.total_group).find(.api_txt_lines).text().trim(); results.push({ title, link, snippet, rank: index 1 }); }); // 5. 返回结构化数据 return { query, totalEstimated: results.length, // 注意从HTML很难获取精确总数这通常是个估算 items: results }; }实操心得选择器调试是关键解析HTML页面最大的挑战在于目标网站Naver的页面结构可能会发生变化。今天有效的CSS选择器明天可能就失效了。因此在实现和后期维护中必须使用浏览器的开发者工具F12仔细分析Naver搜索结果页的DOM结构。选择器应尽可能具有唯一性和稳定性避免使用可能频繁变化的类名或ID。实现时需加入健壮的错误处理即使某个结果元素解析失败也不应导致整个搜索崩溃可以记录日志并跳过该结果。考虑将选择器配置化放在一个单独的配置文件中这样当页面结构变化时无需修改核心代码只需更新配置即可。4. 从零开始部署与集成实践4.1 本地开发环境搭建与测试假设你已经有了Node.js建议版本16和npm环境让我们一步步将这个服务器跑起来并手动测试它。步骤一获取项目代码git clone https://github.com/uju777/mcp-server-naver-search.git cd mcp-server-naver-search步骤二安装依赖npm install这会安装modelcontextprotocol/sdk、axios、cheerio等项目依赖。步骤三研究启动方式查看package.json中的scripts字段。通常会有{ scripts: { start: node src/index.js, dev: nodemon src/index.js } }这意味着你可以通过npm start来启动服务器。步骤四启动MCP服务器npm start # 或 npm run dev (如果配置了热重载)如果一切正常服务器会启动并监听某个端口例如3000或者更常见的是MCP服务器使用stdio标准输入输出进行通信。你可能会看到类似“Naver Search MCP server started”的日志。步骤五使用MCP客户端进行测试为了验证服务器是否正常工作我们需要一个MCP客户端。一个简单的方法是使用modelcontextprotocol/sdk自带的测试工具或者编写一个简单的测试脚本。这里提供一个极简的测试脚本test_client.js// test_client.js - 一个简单的MCP客户端测试 import { Client } from modelcontextprotocol/sdk; import { spawn } from child_process; // 1. 启动服务器子进程 (假设服务器入口是 src/index.js) const serverProcess spawn(node, [src/index.js]); // 2. 创建MCP客户端并连接到子进程的 stdin/stdout const client new Client( { name: test-client, version: 1.0.0 }, { capabilities: {} } ); await client.connect(serverProcess.stdin, serverProcess.stdout); // 3. 列出可用工具 const tools await client.listTools(); console.log(可用工具:, tools); // 4. 调用 naver_search 工具 if (tools.tools.some(t t.name naver_search)) { const result await client.callTool({ name: naver_search, arguments: { query: 오늘 날씨, maxResults: 3 } }); console.log(搜索结果:, JSON.stringify(result, null, 2)); } // 5. 断开连接并关闭服务器 await client.close(); serverProcess.kill();运行node test_client.js你应该能看到服务器返回的工具列表和搜索“오늘 날씨”今日天气的结果。4.2 与主流AI平台集成实战让这个服务器发挥价值的最终步骤是将其集成到真正的AI应用中去。以下是两个主要场景的集成方法。场景一集成到Claude DesktopClaude Desktop是官方支持MCP的典型应用。集成通常通过编辑一个配置文件来完成。找到Claude Desktop的MCP配置文件。其位置因操作系统而异macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件添加你的Naver搜索服务器。你需要指定服务器的启动命令。假设你的项目在D:\projects\mcp-server-naver-search。{ mcpServers: { naver-search: { command: node, args: [ D:\\projects\\mcp-server-naver-search\\src\\index.js ], env: { // 可以在这里设置环境变量如代理等 } } // ... 可以配置其他MCP服务器 } }重启Claude Desktop。重启后Claude应该就能识别到这个新工具。当你和Claude对话时它会在认为需要搜索时自动调用naver_search工具并将结果融入回答中。场景二在自定义AI应用中使用以OpenAI Assistant API为例如果你使用OpenAI的Assistant API构建自己的AI智能体你需要做两件事一是运行MCP服务器二是让Assistant知道这个工具。启动MCP服务器作为后台进程。你可以使用pm2或forever等进程管理工具来保持其运行。pm2 start src/index.js --name mcp-naver-search为你的Assistant配置Function Calling函数调用。虽然OpenAI Assistant原生支持Function Calling而非MCP但思路相通。你需要将MCP服务器的能力“翻译”成OpenAI的Function格式。实际上你可以创建一个中间层服务一个简单的Web API这个服务接收Assistant的Function Call请求然后将其转换为对本地MCP服务器的调用。中间层API示例使用Express:// api-proxy.js import express from express; import { Client } from modelcontextprotocol/sdk; import { spawn } from child_process; const app express(); app.use(express.json()); let mcpClient; // 启动并连接MCP服务器 async function initMCP() { const serverProcess spawn(node, [path/to/your/server/index.js]); mcpClient new Client({ name: proxy-client, version: 1.0.0 }, {}); await mcpClient.connect(serverProcess.stdin, serverProcess.stdout); } app.post(/call-naver-search, async (req, res) { const { query, maxResults } req.body; try { const result await mcpClient.callTool({ name: naver_search, arguments: { query, maxResults } }); res.json({ success: true, data: result }); } catch (error) { res.status(500).json({ success: false, error: error.message }); } }); initMCP().then(() { app.listen(3001, () console.log(MCP代理API运行在3001端口)); });在OpenAI Assistant中定义对应的Function:# Python示例 from openai import OpenAI client OpenAI() assistant client.beta.assistants.create( nameResearch Assistant, instructions你是一个助手可以使用Naver搜索来获取最新信息。, modelgpt-4-turbo, tools[ { type: function, function: { name: naver_search, description: 使用Naver搜索引擎搜索网络信息。, parameters: { type: object, properties: { query: {type: string, description: 搜索关键词}, maxResults: {type: integer, description: 返回结果数默认10} }, required: [query] } } } ] )当Assistant需要搜索时它会触发这个Function Call你的应用后端需要捕获这个调用然后请求你刚刚搭建的中间层API (/call-naver-search)获取结果后再返回给Assistant继续处理。重要提示在实际生产环境中直接暴露一个能执行任意搜索的接口存在安全风险如恶意搜索、高频请求导致IP被封。务必在前端或中间层添加身份验证、请求频率限制、查询词过滤等安全措施。5. 高级配置、优化与避坑指南5.1 应对反爬虫策略与提升稳定性任何模拟用户访问的网络爬虫都会面临反爬虫机制的挑战。Naver作为大型网站必然有相应的防护措施。直接使用上述基础代码高频访问很可能很快会遭遇访问限制如返回验证码、封锁IP。以下是一些应对策略和优化建议设置合理的请求间隔Rate Limiting这是最基本的道德和技术要求。在搜索函数中加入延迟模拟人类浏览的间隔。可以使用setTimeout或rate-limiter库。import { RateLimiter } from rate-limiter; const limiter new RateLimiter({ tokensPerInterval: 1, interval: 2000 }); // 每2秒1个请求 async function doNaverSearchWithLimit(query) { await limiter.removeTokens(1); return await doNaverSearch(query); }轮换User-Agent使用单一的User-Agent容易被识别。可以维护一个常见的浏览器User-Agent列表每次请求随机选择一个。const userAgents [ Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ..., Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 ..., // ... 更多 ]; const headers { User-Agent: userAgents[Math.floor(Math.random() * userAgents.length)] };使用代理IP池对于需要大量抓取的情况使用代理IP是避免本地IP被封的有效手段。可以将代理配置为环境变量或在代码中集成代理服务商的API。// 使用环境变量中的代理 const httpsAgent new HttpsProxyAgent(process.env.HTTPS_PROXY); const response await axios.get(url, { headers, httpsAgent, timeout: 10000 // 设置超时 });处理异常和重试网络请求总可能失败。实现一个带有指数退避的重试机制。async function fetchWithRetry(url, retries 3, delay 1000) { for (let i 0; i retries; i) { try { return await axios.get(url, { timeout: 8000 }); } catch (error) { if (i retries - 1) throw error; console.warn(请求失败${delay}ms后重试... (${i 1}/${retries})); await new Promise(resolve setTimeout(resolve, delay)); delay * 2; // 指数退避 } } }解析失败的回退策略如前所述页面结构可能变化。在解析逻辑中使用try...catch包裹对每个结果条目的解析。如果主要的选择器失效可以尝试备用选择器或者至少返回一个包含原始链接和错误信息的结果而不是让整个搜索崩溃。5.2 结果后处理与格式化增强从HTML中解析出的原始数据往往比较粗糙直接返回给AI模型可能不是最优的。我们可以增加一个后处理层来提升结果质量结果去重有时同一内容会以不同链接出现。可以根据标题和摘要的相似度如计算Jaccard相似度或使用文本哈希进行去重。摘要优化Naver返回的摘要可能包含省略号或无关字符。可以进行简单的清洗如去除多余空格、换行符截取到完整句子。结果排序与过滤除了默认的Naver排序你还可以根据业务逻辑进行二次排序例如优先显示特定域名如.go.kr政府网站.ac.kr教育机构的结果或者过滤掉广告链接通常链接域名包含ad.naver.com等特征。丰富结果信息如果可能可以尝试进一步抓取结果页面的元描述meta description或关键图片使返回的数据更丰富。结构化输出确保最终返回给MCP客户端的数据结构清晰、稳定。例如{ query: 검색어, requestedAt: 2024-01-01T10:30:00Z, items: [ { title: 결과 제목, url: https://..., displayUrl: example.com/..., // 美化后的URL snippet: 결과 요약문..., source: 네이버 블로그, // 识别来源类型 date: 2023-12-31 // 如果页面中有日期信息 } ] }5.3 性能监控与日志记录对于一个长期运行的服务良好的可观测性至关重要。结构化日志使用winston或pino等日志库记录每次搜索请求的查询词、耗时、结果数量、是否成功等信息。这有助于监控使用情况和排查问题。import winston from winston; const logger winston.createLogger({ /* 配置 */ }); async function doNaverSearch(query) { const startTime Date.now(); try { const results await performSearch(query); const duration Date.now() - startTime; logger.info(Search succeeded, { query, duration, resultCount: results.length }); return results; } catch (error) { logger.error(Search failed, { query, error: error.message }); throw error; } }健康检查端点如果你的服务器以HTTP服务形式运行而非仅stdio可以添加一个简单的/health端点返回服务器状态便于容器编排如Docker, Kubernetes或监控系统检查。指标收集可以考虑集成像Prometheus这样的监控系统暴露搜索次数、平均延迟、错误率等指标以便进行更专业的性能分析和告警。6. 常见问题排查与扩展思路6.1 实战问题速查表在开发和运行过程中你可能会遇到以下典型问题。这里提供一个快速排查指南问题现象可能原因排查步骤与解决方案服务器启动失败提示端口占用或依赖错误1. 端口被其他进程占用。2. Node.js版本不兼容。3. 依赖包安装不完整或冲突。1. 检查并更改端口号或关闭占用端口的进程。2. 确认项目要求的Node.js版本查看.nvmrc或package.json中的engines字段。3. 删除node_modules和package-lock.json重新运行npm install。MCP客户端连接失败或无法列出工具1. 服务器启动命令或路径错误。2. 服务器代码存在语法错误提前退出。3. MCP协议版本不兼容。1. 检查客户端配置中的command和args路径是否正确。2. 查看服务器启动日志确认是否有未捕获的异常。3. 分别检查客户端和服务器使用的modelcontextprotocol/sdk版本确保兼容。搜索请求超时或无响应1. 网络连接问题如需要代理访问Naver。2. Naver服务器响应慢或暂时不可用。3. 解析逻辑陷入死循环或性能瓶颈。1. 在代码中为HTTP请求设置合理的超时如10秒并考虑配置代理。2. 实现重试机制并记录失败日志。3. 检查解析循环确保有明确的退出条件对于大量结果考虑分页或限制解析深度。搜索返回空结果或结果数量极少1. Naver页面结构已更新CSS选择器失效。2. 请求被识别为爬虫返回了验证码页面或空白页。3. 查询词编码错误。1. 使用浏览器开发者工具重新分析Naver搜索结果页更新选择器。2. 检查返回的HTML内容看是否包含验证码相关元素。增加请求头如Accept-Language降低请求频率。3. 确保encodeURIComponent被正确使用。返回的结果包含乱码或编码错误网页字符编码如UTF-8, EUC-KR与解析设置不一致。在Axios请求中设置responseType: arraybuffer然后使用iconv-lite库根据Content-Type头或HTML meta标签检测并转换编码。集成到Claude Desktop后Claude不调用工具1. Claude Desktop配置未生效。2. 工具描述不够清晰AI无法判断何时使用。3. 服务器响应格式不符合MCP规范。1. 重启Claude Desktop检查其日志文件通常有日志输出位置。2. 优化工具的description和参数描述使其更精确。3. 使用test_client.js验证服务器返回的JSON结构是否符合MCP SDK的预期。6.2 功能扩展与二次开发方向mcp-server-naver-search项目提供了一个优秀的起点你可以基于它进行扩展打造更强大的信息获取工具多搜索引擎聚合不局限于Naver。可以扩展工具使其支持Google、Bing、Daum等。可以设计一个universal_search工具内部根据参数或配置路由到不同的搜索引擎实现并对结果进行合并和去重排序。垂直搜索支持Naver不仅有网页搜索还有图片、视频、新闻、学术、购物等垂直搜索。可以为每个垂直频道创建独立的工具如naver_image_search,naver_news_search提供更精准的结果。结果摘要与翻译在返回结果前可以调用本地或云端的摘要模型如使用Ollama运行本地LLM对抓取到的网页正文进行摘要。或者对于韩语结果可以集成翻译API提供中文或英文摘要方便非韩语用户使用。缓存层对于相同的搜索查询结果在短时间内变化不大。可以引入一个缓存层如使用Redis或内存缓存将搜索结果缓存一段时间例如5分钟以减少对Naver的请求次数并提升响应速度。认证与授权如果你要将此服务提供给团队或多用户使用需要添加API密钥认证。可以在MCP服务器启动时读取密钥或者在中间层代理处进行验证。容器化部署使用Docker将服务器及其依赖打包成镜像可以极大地简化在不同环境下的部署。编写Dockerfile和docker-compose.yml便于一键部署。这个项目的魅力在于它像一颗种子。你理解了MCP协议如何工作掌握了与外部服务交互和解析数据的方法就可以将这套模式复制到无数其他场景——连接数据库、查询天气、控制智能家居、调用企业内部API。它为你打开了一扇门让你能够亲手为AI模型锻造各式各样的“工具”极大地拓展其能力的边界。
基于MCP协议构建Naver搜索服务器，为AI智能体赋能实时信息获取
发布时间：2026/5/17 1:12:07
1. 项目概述一个连接AI与实时信息的桥梁最近在折腾AI应用开发特别是围绕OpenAI的Assistant API和Claude的Tool Use功能时我一直在思考一个问题如何让这些强大的AI模型摆脱其知识库的“时间枷锁”获取到最新、最实时的网络信息无论是查询最新的产品发布、追踪某个新闻事件的进展还是获取实时的股价或天气都需要一个可靠的外部信息源。这就是我注意到uju777/mcp-server-naver-search这个项目的契机。本质上它是一个MCPModel Context Protocol服务器专门为AI模型提供了调用Naver韩国最大的搜索引擎进行网络搜索的能力。简单来说你可以把它理解为一个“翻译官”或“适配器”。AI模型如GPT-4、Claude 3本身无法直接打开浏览器搜索网页但它们可以通过标准的MCP协议向这个服务器发送一个搜索请求例如“帮我找一下最近三天关于三星Galaxy S24的评测文章”。这个服务器接收到请求后会去模拟用户行为实际访问Naver搜索将返回的搜索结果包括标题、链接、摘要等整理成结构化的数据再通过MCP协议回传给AI模型。这样AI在生成回答时就能引用这些新鲜的、实时的信息极大地提升了回答的准确性和时效性。这个项目非常适合两类开发者一是正在构建需要联网搜索功能的AI智能体Agent或聊天机器人的开发者二是希望扩展Claude Desktop、Cursor等已集成MCP客户端的工具能力的深度用户。通过集成这个服务器你可以轻松地为你的AI应用赋予“浏览互联网”的眼睛而且聚焦于韩语和韩国市场信息这是Google Search API等通用方案有时难以精准覆盖的领域。2. MCP协议与Naver搜索的价值解析2.1 为什么是MCPModel Context Protocol在深入代码之前我们必须先理解MCP是什么以及它为何成为AI工具生态中的重要一环。MCP是由Anthropic提出的一种开放协议旨在标准化AI模型与外部工具、数据源之间的通信方式。你可以把它想象成AI世界的“USB标准”或“插件接口规范”。在MCP架构下存在几个核心角色MCP客户端Client通常是AI模型本身或其运行环境如Claude Desktop、Cursor IDE、自建的AI应用。它负责发起工具调用请求。MCP服务器Server就像本项目是提供具体能力的服务端。它暴露一个或多个“工具Tools”给客户端调用。工具Tools服务器提供的具体功能例如naver_search。每个工具都有明确的输入参数和输出格式。其工作流程非常清晰客户端通过标准化的JSON-RPC消息告诉服务器“请调用naver_search工具参数是query‘某关键词’。” 服务器执行搜索然后将结构化的结果封装好通过同样的通道返回给客户端。这种设计的巨大优势在于解耦和标准化。AI应用开发者无需为每一个外部API如搜索、数据库、计算编写特定的、脆硬的集成代码只需要让AI模型学会调用MCP工具即可。而工具提供者服务器开发者则可以专注于把单一功能做深做透无需关心上游是哪个AI模型在调用。uju777/mcp-server-naver-search正是这样一个专注于“Naver搜索”单一功能的MCP服务器。它让任何兼容MCP的AI客户端都能立即获得搜索Naver的能力。2.2 选择Naver搜索的独特优势与场景你可能会问已经有那么多通用的搜索引擎API为什么还要专门做一个Naver的这恰恰是这个项目的精妙之处它解决的是特定市场下的精准需求。核心优势韩语及韩国本地化搜索的绝对优势Naver是韩国市场份额超过70%的国民搜索引擎。对于韩语关键词的处理、对韩国本地网站如.naver.com, .co.kr的收录和排序Naver的理解远超Google。如果你要查询韩国本地的新闻、博客Naver Blog、知识问答Naver Knowledge iN、购物Naver Shopping或地图信息Naver的结果相关性和时效性是无与伦比的。规避通用搜索API的限制许多免费的通用搜索API有速率限制、结果数量限制或者对商业用途收费高昂。而通过模拟浏览器访问Naver尽管需要谨慎处理反爬虫策略在某些低频、个人使用的场景下可能是一种灵活补充。为AI智能体提供区域化能力如果你在开发一个主要服务韩国用户或者需要处理大量韩语信息的AI智能体那么直接集成Naver搜索作为其“信息感官”远比让它使用可能带有“全球化偏见”的通用搜索要高效和准确。典型应用场景韩国市场调研AI助手自动搜索并总结韩国社交媒体上对某品牌或产品的舆论。韩语学习伴侣查询最新的韩语流行语、新闻事件为语言学习者提供真实语境材料。本地化客服机器人快速查找韩国本地的商家信息、营业时间、政策公告来回答用户查询。研究工具追踪韩国科技、娱乐、金融领域的动态并自动生成简报。注意使用此类模拟用户访问的服务器进行搜索必须严格遵守Naver的服务条款Robots协议尊重robots.txt文件并控制请求频率避免对目标服务器造成负担防止IP被封锁。本项目更适合用于个人学习、研究或低频度的合法数据获取。3. 项目架构与核心代码拆解3.1 技术栈与依赖分析这个项目通常基于Node.js环境构建这是构建轻量级网络服务和工具服务器的常见选择。我们来看其核心依赖这能帮助我们理解它的工作原理modelcontextprotocol/sdk这是MCP协议的官方JavaScript SDK。它是项目的基石用于创建MCP服务器实例、定义工具Tools、处理来自客户端的请求和发送响应。所有与MCP协议相关的通信逻辑都封装在此SDK中。puppeteer或playwright或axioscheerio这是执行实际搜索任务的核心。具体方案取决于实现方式无头浏览器方案Puppeteer/Playwright这种方式最接近真实用户。它能执行JavaScript渲染完整页面适合搜索结果页动态加载严重的场景。但开销较大启动慢。HTTP请求HTML解析方案Axios Cheerio这种方式更轻量、更快。直接向Naver搜索的URL发送HTTP GET请求然后使用Cheerio一个类似jQuery的库来解析返回的HTML提取搜索结果。这要求Naver的搜索结果页是相对静态的或者开发者能够逆向分析出包含数据的请求接口。可选依赖可能包括dotenv管理环境变量如代理设置、rate-limiter请求限流、logger日志记录等用于增强服务器的健壮性和可维护性。项目的package.json文件是理解其技术选型的入口。选择无头浏览器还是轻量级解析是一个关键的架构决策直接影响到服务器的性能、资源消耗和隐蔽性。3.2 核心工具Tool定义剖析MCP服务器的核心是向客户端声明自己提供了哪些“工具”。在src/index.js或server.js这样的主文件中我们会看到类似以下的核心代码结构import { Server } from modelcontextprotocol/sdk; import { doNaverSearch } from ./search.js; // 假设的搜索执行函数 const server new Server( { name: naver-search-server, version: 1.0.0 }, { capabilities: { tools: {} } } ); // 定义 naver_search 工具 server.setRequestHandler(tools/list, async () { return { tools: [ { name: naver_search, description: 使用Naver搜索引擎进行网络搜索并返回结构化结果。, inputSchema: { type: object, properties: { query: { type: string, description: 要搜索的关键词或短语。 }, maxResults: { type: number, description: 希望返回的最大结果数量例如10。, default: 10 } // 可能还有其他参数如 language, region 等 }, required: [query] } } ] }; });这段代码是服务器的“能力宣言”。它告诉MCP客户端“我这里有一个叫naver_search的工具你可以用。你需要给我一个query字符串参数我还能接受一个可选的maxResults数字参数。” 输入模式inputSchema的定义至关重要它使得AI模型能够理解如何正确地调用这个工具。3.3 搜索请求处理与结果解析逻辑当客户端调用naver_search工具时服务器会收到一个tools/call请求。处理函数是项目的核心业务逻辑所在server.setRequestHandler(tools/call, async (request) { if (request.params.name naver_search) { const { query, maxResults 10 } request.params.arguments; try { // 调用实际的搜索函数 const searchResults await doNaverSearch(query, maxResults); return { content: [ { type: text, text: JSON.stringify(searchResults, null, 2) // 返回格式化的JSON结果 } ] }; } catch (error) { return { content: [ { type: text, text: 搜索失败: ${error.message} } ], isError: true }; } } // ... 处理其他工具 });这里的doNaverSearch函数是“脏活累活”发生的地方。我们以Axios Cheerio方案为例深入其内部// search.js import axios from axios; import * as cheerio from cheerio; export async function doNaverSearch(query, maxResults) { // 1. 构建搜索URL。注意需要对查询字符串进行编码。 const encodedQuery encodeURIComponent(query); const searchUrl https://search.naver.com/search.naver?wherewebquery${encodedQuery}; // 2. 发送HTTP请求可添加User-Agent等头部模拟浏览器 const headers { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) ... }; const response await axios.get(searchUrl, { headers }); // 3. 使用Cheerio加载HTML const $ cheerio.load(response.data); const results []; // 4. 解析搜索结果。这是最需要根据Naver页面结构调整的部分。 // Naver的网页搜索结果通常包裹在特定的CSS类中例如 .total_wrap .api_txt_lines 等。 // 这里的选择器是示例实际需要开发者通过浏览器开发者工具分析确定。 $(.total_area .total_tit).each((index, element) { if (index maxResults) return false; // 达到数量限制则停止 const title $(element).text().trim(); const link $(element).attr(href); // 摘要可能在其他相邻元素中 const snippet $(element).closest(.total_group).find(.api_txt_lines).text().trim(); results.push({ title, link, snippet, rank: index 1 }); }); // 5. 返回结构化数据 return { query, totalEstimated: results.length, // 注意从HTML很难获取精确总数这通常是个估算 items: results }; }实操心得选择器调试是关键解析HTML页面最大的挑战在于目标网站Naver的页面结构可能会发生变化。今天有效的CSS选择器明天可能就失效了。因此在实现和后期维护中必须使用浏览器的开发者工具F12仔细分析Naver搜索结果页的DOM结构。选择器应尽可能具有唯一性和稳定性避免使用可能频繁变化的类名或ID。实现时需加入健壮的错误处理即使某个结果元素解析失败也不应导致整个搜索崩溃可以记录日志并跳过该结果。考虑将选择器配置化放在一个单独的配置文件中这样当页面结构变化时无需修改核心代码只需更新配置即可。4. 从零开始部署与集成实践4.1 本地开发环境搭建与测试假设你已经有了Node.js建议版本16和npm环境让我们一步步将这个服务器跑起来并手动测试它。步骤一获取项目代码git clone https://github.com/uju777/mcp-server-naver-search.git cd mcp-server-naver-search步骤二安装依赖npm install这会安装modelcontextprotocol/sdk、axios、cheerio等项目依赖。步骤三研究启动方式查看package.json中的scripts字段。通常会有{ scripts: { start: node src/index.js, dev: nodemon src/index.js } }这意味着你可以通过npm start来启动服务器。步骤四启动MCP服务器npm start # 或 npm run dev (如果配置了热重载)如果一切正常服务器会启动并监听某个端口例如3000或者更常见的是MCP服务器使用stdio标准输入输出进行通信。你可能会看到类似“Naver Search MCP server started”的日志。步骤五使用MCP客户端进行测试为了验证服务器是否正常工作我们需要一个MCP客户端。一个简单的方法是使用modelcontextprotocol/sdk自带的测试工具或者编写一个简单的测试脚本。这里提供一个极简的测试脚本test_client.js// test_client.js - 一个简单的MCP客户端测试 import { Client } from modelcontextprotocol/sdk; import { spawn } from child_process; // 1. 启动服务器子进程 (假设服务器入口是 src/index.js) const serverProcess spawn(node, [src/index.js]); // 2. 创建MCP客户端并连接到子进程的 stdin/stdout const client new Client( { name: test-client, version: 1.0.0 }, { capabilities: {} } ); await client.connect(serverProcess.stdin, serverProcess.stdout); // 3. 列出可用工具 const tools await client.listTools(); console.log(可用工具:, tools); // 4. 调用 naver_search 工具 if (tools.tools.some(t t.name naver_search)) { const result await client.callTool({ name: naver_search, arguments: { query: 오늘 날씨, maxResults: 3 } }); console.log(搜索结果:, JSON.stringify(result, null, 2)); } // 5. 断开连接并关闭服务器 await client.close(); serverProcess.kill();运行node test_client.js你应该能看到服务器返回的工具列表和搜索“오늘 날씨”今日天气的结果。4.2 与主流AI平台集成实战让这个服务器发挥价值的最终步骤是将其集成到真正的AI应用中去。以下是两个主要场景的集成方法。场景一集成到Claude DesktopClaude Desktop是官方支持MCP的典型应用。集成通常通过编辑一个配置文件来完成。找到Claude Desktop的MCP配置文件。其位置因操作系统而异macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件添加你的Naver搜索服务器。你需要指定服务器的启动命令。假设你的项目在D:\projects\mcp-server-naver-search。{ mcpServers: { naver-search: { command: node, args: [ D:\\projects\\mcp-server-naver-search\\src\\index.js ], env: { // 可以在这里设置环境变量如代理等 } } // ... 可以配置其他MCP服务器 } }重启Claude Desktop。重启后Claude应该就能识别到这个新工具。当你和Claude对话时它会在认为需要搜索时自动调用naver_search工具并将结果融入回答中。场景二在自定义AI应用中使用以OpenAI Assistant API为例如果你使用OpenAI的Assistant API构建自己的AI智能体你需要做两件事一是运行MCP服务器二是让Assistant知道这个工具。启动MCP服务器作为后台进程。你可以使用pm2或forever等进程管理工具来保持其运行。pm2 start src/index.js --name mcp-naver-search为你的Assistant配置Function Calling函数调用。虽然OpenAI Assistant原生支持Function Calling而非MCP但思路相通。你需要将MCP服务器的能力“翻译”成OpenAI的Function格式。实际上你可以创建一个中间层服务一个简单的Web API这个服务接收Assistant的Function Call请求然后将其转换为对本地MCP服务器的调用。中间层API示例使用Express:// api-proxy.js import express from express; import { Client } from modelcontextprotocol/sdk; import { spawn } from child_process; const app express(); app.use(express.json()); let mcpClient; // 启动并连接MCP服务器 async function initMCP() { const serverProcess spawn(node, [path/to/your/server/index.js]); mcpClient new Client({ name: proxy-client, version: 1.0.0 }, {}); await mcpClient.connect(serverProcess.stdin, serverProcess.stdout); } app.post(/call-naver-search, async (req, res) { const { query, maxResults } req.body; try { const result await mcpClient.callTool({ name: naver_search, arguments: { query, maxResults } }); res.json({ success: true, data: result }); } catch (error) { res.status(500).json({ success: false, error: error.message }); } }); initMCP().then(() { app.listen(3001, () console.log(MCP代理API运行在3001端口)); });在OpenAI Assistant中定义对应的Function:# Python示例 from openai import OpenAI client OpenAI() assistant client.beta.assistants.create( nameResearch Assistant, instructions你是一个助手可以使用Naver搜索来获取最新信息。, modelgpt-4-turbo, tools[ { type: function, function: { name: naver_search, description: 使用Naver搜索引擎搜索网络信息。, parameters: { type: object, properties: { query: {type: string, description: 搜索关键词}, maxResults: {type: integer, description: 返回结果数默认10} }, required: [query] } } } ] )当Assistant需要搜索时它会触发这个Function Call你的应用后端需要捕获这个调用然后请求你刚刚搭建的中间层API (/call-naver-search)获取结果后再返回给Assistant继续处理。重要提示在实际生产环境中直接暴露一个能执行任意搜索的接口存在安全风险如恶意搜索、高频请求导致IP被封。务必在前端或中间层添加身份验证、请求频率限制、查询词过滤等安全措施。5. 高级配置、优化与避坑指南5.1 应对反爬虫策略与提升稳定性任何模拟用户访问的网络爬虫都会面临反爬虫机制的挑战。Naver作为大型网站必然有相应的防护措施。直接使用上述基础代码高频访问很可能很快会遭遇访问限制如返回验证码、封锁IP。以下是一些应对策略和优化建议设置合理的请求间隔Rate Limiting这是最基本的道德和技术要求。在搜索函数中加入延迟模拟人类浏览的间隔。可以使用setTimeout或rate-limiter库。import { RateLimiter } from rate-limiter; const limiter new RateLimiter({ tokensPerInterval: 1, interval: 2000 }); // 每2秒1个请求 async function doNaverSearchWithLimit(query) { await limiter.removeTokens(1); return await doNaverSearch(query); }轮换User-Agent使用单一的User-Agent容易被识别。可以维护一个常见的浏览器User-Agent列表每次请求随机选择一个。const userAgents [ Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ..., Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 ..., // ... 更多 ]; const headers { User-Agent: userAgents[Math.floor(Math.random() * userAgents.length)] };使用代理IP池对于需要大量抓取的情况使用代理IP是避免本地IP被封的有效手段。可以将代理配置为环境变量或在代码中集成代理服务商的API。// 使用环境变量中的代理 const httpsAgent new HttpsProxyAgent(process.env.HTTPS_PROXY); const response await axios.get(url, { headers, httpsAgent, timeout: 10000 // 设置超时 });处理异常和重试网络请求总可能失败。实现一个带有指数退避的重试机制。async function fetchWithRetry(url, retries 3, delay 1000) { for (let i 0; i retries; i) { try { return await axios.get(url, { timeout: 8000 }); } catch (error) { if (i retries - 1) throw error; console.warn(请求失败${delay}ms后重试... (${i 1}/${retries})); await new Promise(resolve setTimeout(resolve, delay)); delay * 2; // 指数退避 } } }解析失败的回退策略如前所述页面结构可能变化。在解析逻辑中使用try...catch包裹对每个结果条目的解析。如果主要的选择器失效可以尝试备用选择器或者至少返回一个包含原始链接和错误信息的结果而不是让整个搜索崩溃。5.2 结果后处理与格式化增强从HTML中解析出的原始数据往往比较粗糙直接返回给AI模型可能不是最优的。我们可以增加一个后处理层来提升结果质量结果去重有时同一内容会以不同链接出现。可以根据标题和摘要的相似度如计算Jaccard相似度或使用文本哈希进行去重。摘要优化Naver返回的摘要可能包含省略号或无关字符。可以进行简单的清洗如去除多余空格、换行符截取到完整句子。结果排序与过滤除了默认的Naver排序你还可以根据业务逻辑进行二次排序例如优先显示特定域名如.go.kr政府网站.ac.kr教育机构的结果或者过滤掉广告链接通常链接域名包含ad.naver.com等特征。丰富结果信息如果可能可以尝试进一步抓取结果页面的元描述meta description或关键图片使返回的数据更丰富。结构化输出确保最终返回给MCP客户端的数据结构清晰、稳定。例如{ query: 검색어, requestedAt: 2024-01-01T10:30:00Z, items: [ { title: 결과 제목, url: https://..., displayUrl: example.com/..., // 美化后的URL snippet: 결과 요약문..., source: 네이버 블로그, // 识别来源类型 date: 2023-12-31 // 如果页面中有日期信息 } ] }5.3 性能监控与日志记录对于一个长期运行的服务良好的可观测性至关重要。结构化日志使用winston或pino等日志库记录每次搜索请求的查询词、耗时、结果数量、是否成功等信息。这有助于监控使用情况和排查问题。import winston from winston; const logger winston.createLogger({ /* 配置 */ }); async function doNaverSearch(query) { const startTime Date.now(); try { const results await performSearch(query); const duration Date.now() - startTime; logger.info(Search succeeded, { query, duration, resultCount: results.length }); return results; } catch (error) { logger.error(Search failed, { query, error: error.message }); throw error; } }健康检查端点如果你的服务器以HTTP服务形式运行而非仅stdio可以添加一个简单的/health端点返回服务器状态便于容器编排如Docker, Kubernetes或监控系统检查。指标收集可以考虑集成像Prometheus这样的监控系统暴露搜索次数、平均延迟、错误率等指标以便进行更专业的性能分析和告警。6. 常见问题排查与扩展思路6.1 实战问题速查表在开发和运行过程中你可能会遇到以下典型问题。这里提供一个快速排查指南问题现象可能原因排查步骤与解决方案服务器启动失败提示端口占用或依赖错误1. 端口被其他进程占用。2. Node.js版本不兼容。3. 依赖包安装不完整或冲突。1. 检查并更改端口号或关闭占用端口的进程。2. 确认项目要求的Node.js版本查看.nvmrc或package.json中的engines字段。3. 删除node_modules和package-lock.json重新运行npm install。MCP客户端连接失败或无法列出工具1. 服务器启动命令或路径错误。2. 服务器代码存在语法错误提前退出。3. MCP协议版本不兼容。1. 检查客户端配置中的command和args路径是否正确。2. 查看服务器启动日志确认是否有未捕获的异常。3. 分别检查客户端和服务器使用的modelcontextprotocol/sdk版本确保兼容。搜索请求超时或无响应1. 网络连接问题如需要代理访问Naver。2. Naver服务器响应慢或暂时不可用。3. 解析逻辑陷入死循环或性能瓶颈。1. 在代码中为HTTP请求设置合理的超时如10秒并考虑配置代理。2. 实现重试机制并记录失败日志。3. 检查解析循环确保有明确的退出条件对于大量结果考虑分页或限制解析深度。搜索返回空结果或结果数量极少1. Naver页面结构已更新CSS选择器失效。2. 请求被识别为爬虫返回了验证码页面或空白页。3. 查询词编码错误。1. 使用浏览器开发者工具重新分析Naver搜索结果页更新选择器。2. 检查返回的HTML内容看是否包含验证码相关元素。增加请求头如Accept-Language降低请求频率。3. 确保encodeURIComponent被正确使用。返回的结果包含乱码或编码错误网页字符编码如UTF-8, EUC-KR与解析设置不一致。在Axios请求中设置responseType: arraybuffer然后使用iconv-lite库根据Content-Type头或HTML meta标签检测并转换编码。集成到Claude Desktop后Claude不调用工具1. Claude Desktop配置未生效。2. 工具描述不够清晰AI无法判断何时使用。3. 服务器响应格式不符合MCP规范。1. 重启Claude Desktop检查其日志文件通常有日志输出位置。2. 优化工具的description和参数描述使其更精确。3. 使用test_client.js验证服务器返回的JSON结构是否符合MCP SDK的预期。6.2 功能扩展与二次开发方向mcp-server-naver-search项目提供了一个优秀的起点你可以基于它进行扩展打造更强大的信息获取工具多搜索引擎聚合不局限于Naver。可以扩展工具使其支持Google、Bing、Daum等。可以设计一个universal_search工具内部根据参数或配置路由到不同的搜索引擎实现并对结果进行合并和去重排序。垂直搜索支持Naver不仅有网页搜索还有图片、视频、新闻、学术、购物等垂直搜索。可以为每个垂直频道创建独立的工具如naver_image_search,naver_news_search提供更精准的结果。结果摘要与翻译在返回结果前可以调用本地或云端的摘要模型如使用Ollama运行本地LLM对抓取到的网页正文进行摘要。或者对于韩语结果可以集成翻译API提供中文或英文摘要方便非韩语用户使用。缓存层对于相同的搜索查询结果在短时间内变化不大。可以引入一个缓存层如使用Redis或内存缓存将搜索结果缓存一段时间例如5分钟以减少对Naver的请求次数并提升响应速度。认证与授权如果你要将此服务提供给团队或多用户使用需要添加API密钥认证。可以在MCP服务器启动时读取密钥或者在中间层代理处进行验证。容器化部署使用Docker将服务器及其依赖打包成镜像可以极大地简化在不同环境下的部署。编写Dockerfile和docker-compose.yml便于一键部署。这个项目的魅力在于它像一颗种子。你理解了MCP协议如何工作掌握了与外部服务交互和解析数据的方法就可以将这套模式复制到无数其他场景——连接数据库、查询天气、控制智能家居、调用企业内部API。它为你打开了一扇门让你能够亲手为AI模型锻造各式各样的“工具”极大地拓展其能力的边界。
