使用说明
搜索mcp
欢迎搜索mcp！这是一个个人模型上下文协议（MCP）服务器，旨在提供一套强大的搜索和数据检索工具。它使用TypeScript构建，并利用MCP SDK与AI代理或其他MCP兼容客户端无缝集成。
概述
该项目实现了一个MCP服务器，该服务器公开了几个用于与web内容、代码存储库和URL交互的工具。每个工具都使用Zod用清晰的模式定义，并且可以很容易地被MCP客户端调用。
特性
服务器目前提供以下工具：
- 网络搜索： 使用DuckDuckGo执行网络搜索。
- GitHub代码搜索： 在公共GitHub存储库中搜索代码片段。
- 获取URL： 检索网页内容并将其转换为干净的Markdown。
使用的技术
- 运行时间： Bun（或Node.js）
- 语言： TypeScript
- 协议： 模型上下文协议（通过
@modelcontextprotocol/sdk) - 架构验证： 萨德
- 测试： Vitest
- 核心服务和图书馆：
- 网络搜索：
duck-duck-scrape - GitHub搜索：
@octokit/rest - URL获取和Markdown转换：
@mozilla/readability,turndown,jsdom - MCP服务器：
@modelcontextprotocol/sdk/server
- 网络搜索：
设置和使用
先决条件
- Bun（推荐：
curl -fsSL https://bun.sh/install | bash)或Node.js - Git
安装
- 克隆存储库：
git clone <your-repository-url> # Replace with your actual repo URL once created cd search-mcp - 安装依赖项：
bun install # OR if using npm # npm install
运行服务器
（您需要创建一个主脚本，例如。， index.ts 或 src/index.ts，以构建和启动服务器。下面是一个可能看起来像什么的基本示例：）
示例 src/index.ts:
import { buildServer } from './mcp/server.js';
const port = process.env.PORT || 3000;
const server = buildServer();
server.listen(port, () => {
console.log(`MCP server '${server.name}' v${server.version} listening on port ${port}`);
console.log('Available tools:', server.getToolNames().join(', '));
});
然后运行：
bun run src/index.ts
# OR if using npm and you have a start script in package.json (e.g., "start": "bun src/index.ts")
# npm start
运行测试
npm test
# or
bun test
发出请求（API使用情况）
要与MCP服务器交互并使用其工具，您需要遵循一个两步过程：
- 初始化会话： 与服务器建立会话。
- 调用工具： 使用已建立的会话调用可用工具。
所有交互都是通过 POST 请求 /mcp 运行服务器的端点（例如。， http://localhost:3000/mcp).
1.初始化会话
发送a POST 请求 /mcp 端点带有JSON-RPC“初始化”消息。此请求不需要 mcp-session-id 头球
示例 curl 命令：
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"clientInfo": {
"name": "my-readme-client",
"version": "0.1.0"
},
"capabilities": {
"tools": {}
}
},
"id": "init-example-1"
}' \
http://localhost:3000/mcp
- 这
Accept标头是服务器传输所必需的。 - 服务器将作出响应，在服务器的控制台输出中，您将看到一行如下：
MCP Session initialized: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. - 复制此会话ID。 此会话中的所有后续工具调用都需要它。
2.调用工具
一旦你有了一个活动的会话ID，你就可以通过发送另一个会话ID来调用任何可用的工具 POST 请求 /mcp 终点。这一次，你 必须 包括 mcp-session-id 头球
示例 curl 命令（呼叫 search-web):
替换 YOUR_SESSION_ID_HERE 使用您在初始化步骤中获得的实际会话ID。
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: YOUR_SESSION_ID_HERE" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search-web",
"arguments": {
"query": "What is the Model Context Protocol?",
"limit": 1
}
},
"id": "tool-call-example-1"
}' \
http://localhost:3000/mcp
mcp-session-id：您的活动会话ID。method：应该是"tools/call".params.name：要执行的工具的名称（例如。，"search-web","search-github","fetch-url").params.arguments：包含该工具所需特定参数的对象。
服务器将以JSON-RPC格式响应工具执行的结果。
工具API
所有工具都通过模型上下文协议公开。
1.网络搜索
- 工具名称：
search-web - 说明： 100%免费DuckDuckGo搜索（无需API密钥）。
- 参数：
query（字符串，必填）：搜索查询。- 例子：
"latest advancements in AI"
- 例子：
limit（整数，可选，最小值：1，最大值：30，默认值：10）：返回的最大结果数。- 例子：
5
- 例子：
- 退货： 一个JSON字符串，表示一组搜索结果，每个结果通常包含一个标题、URL和代码段。
2.GitHub代码搜索
- 工具名称：
search-github - 说明： 公共GitHub代码中的高级搜索（REST v3）。
- 参数：
query（string，必填）：使用GitHub高级搜索语法的搜索查询。- 例子：
"repo:microsoft/vscode language:ts QuickPick"
- 例子：
perPage（整数，可选，最小值：1，最大值：100，默认值：20）：每页返回的结果数。- 例子：
15
- 例子：
- 退货： JSON字符串，表示用于代码搜索的GitHub API响应，包括项目和总数。
3.获取URL
- 工具名称：
fetch-url - 说明： 下载网页，提取可读内容，并将其转换为干净的Markdown。
- 参数：
url（字符串，URL格式，必填）：要获取的HTTP/HTTPS URL。- 例子：
"https://example.com/article"
- 例子：
- 退货： 包含所获取页面内容的Markdown表示的字符串。
搜索愉快！
