mcpwebsearch

🚀 📂 MCP Web Search Server

MCP Web Search Server是一个注重隐私的网络、社交媒体和存档搜索服务器，它通过模型控制协议（MCP）提供工具，以实现对外部搜索功能的受控访问。

🚀 快速开始

# 克隆仓库（如果适用）
git clone https://github.com/undici77/MCPWebSearch.git
cd MCPWebSearch

# 运行启动脚本（如果名称不同，请进行调整）
./run.sh -d /path/to/working/directory

1️⃣ 创建并激活 Python 虚拟环境（.venv）。
2️⃣ 安装 requirements.txt 中所有必需的依赖项。
3️⃣ 启动 MCP 搜索服务器（main.py），它会在标准输入/输出上监听 JSON-RPC 消息。

📌 确保启动脚本可执行：chmod +x run.sh

✨ 主要特性

• 并行搜索：可跨多个注重隐私的网络搜索引擎进行并行搜索。
• 社交媒体查询：可在主要平台上查找公开内容。
• 存档检索：可从互联网档案馆（Wayback Machine）、archive.today、谷歌缓存等获取存档。
• 动态列表：可动态列出支持的搜索引擎和存档服务。
• 结果缓存：采用最近最少使用（LRU）淘汰策略进行结果缓存，以加快重复查询的速度。

📦 安装指南

# 克隆仓库（如果适用）
git clone https://github.com/undici77/MCPWebSearch.git
cd MCPWebSearch

# 运行启动脚本（如果名称不同，请进行调整）
./run.sh -d /path/to/working/directory

1️⃣ 创建并激活 Python 虚拟环境（.venv）。
2️⃣ 安装 requirements.txt 中所有必需的依赖项。
3️⃣ 启动 MCP 搜索服务器（main.py），它会在标准输入/输出上监听 JSON-RPC 消息。

📌 确保启动脚本可执行：chmod +x run.sh

⚙️ 命令行选项

| 选项 | 描述 | |------|------| | -d, --directory | 工作目录的路径（默认：当前进程目录）。 |

服务器本身不需要额外的命令行标志；所有配置均通过 JSON-RPC 完成。

🤝 与 LM Studio 集成

在 mcp.json 中添加一个条目，以便 LM Studio 可以自动启动服务器：

{
  "mcpServers": {
    "web-search": {
      "command": "/absolute/path/to/run.sh",
      "args": [
        "-d",
        "/absolute/path/to/working/directory"
      ],
      "env": { "WORKING_DIR": "." }
    }
  }
}

📌 使脚本可执行（chmod +x /absolute/path/to/run.sh），并在启动 LM Studio 之前运行一次 ./run.sh 以安装虚拟环境。

📚 MCP API 概述

所有通信均通过标准输入/输出遵循 JSON-RPC 2.0 协议。

initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

响应：协议版本（2024-11-05）、服务器功能（工具枚举）和基本服务器信息（name、version）。

tools/list

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

响应：一个工具定义数组（名称、描述、输入模式）。

tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { … }
  }
}

注意：工具标识符键是 name，而不是 tool。

💻 使用示例

可用工具

web_search

使用多个注重隐私的搜索引擎并行搜索网络。

| 名称 | 类型 | 是否必需 | 描述 | |------|------|----------|------| | query | 字符串 | ✅ | 搜索查询（最多 500 个字符）。 | | engine | 字符串 | ❌（默认 all） | 要使用的搜索引擎（duckduckgo、brave、startpage、ecosia、mojeek、yandex 或 all）。 | | max_results | 整数 | ❌（默认 20） | 每个搜索引擎的最大结果数（1 - 50）。 |

示例

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "web_search",
    "arguments": {
      "query": "privacy focused search engines",
      "engine": "duckduckgo",
      "max_results": 15
    }
  }
}

服务器返回一个格式化的文本块，其中包含每个选定搜索引擎的标题、URL 和摘要。

social_search

在主要社交媒体平台上搜索公开内容。

| 名称 | 类型 | 是否必需 | 描述 | |------|------|----------|------| | query | 字符串 | ✅ | 搜索查询（最多 500 个字符）。 | | platform | 字符串 | ❌（默认 all） | 要搜索的平台（twitter、reddit、youtube、github、stackoverflow、medium、pinterest、tiktok、instagram、facebook、linkedin 或 all）。 |

示例

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "social_search",
    "arguments": {
      "query": "AI ethics research",
      "platform": "reddit"
    }
  }
}

响应包含可在浏览器中打开的直接 URL。

archives_search

在多个网络存档服务中查找 URL 的存档版本。

| 名称 | 类型 | 是否必需 | 描述 | |------|------|----------|------| | url | 字符串 | ✅ | 完整的 URL（必须包含 http:// 或 https://）。 | | service | 字符串 | ❌（默认 all） | 存档服务（wayback、archive_today、google_cache、bing_cache、yandex_cache、cachedview、ghostarchive 或 all）。 | | check_availability | 布尔值 | ❌（默认 false） | 当为 true 时，服务器会查询互联网档案馆（Wayback Machine）API 以获取快照统计信息。 |

示例

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "archives_search",
    "arguments": {
      "url": "https://example.com",
      "service": "wayback",
      "check_availability": true
    }
  }
}

响应列出了存档 URL，如果请求，还会列出快照计数和时间戳。

list_engines

列出所有可用的注重隐私的搜索引擎。

| 名称 | 类型 | 是否必需 | 描述 | |------|------|----------|------| | (无参数) | — | — | — |

示例

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "list_engines",
    "arguments": {}
  }
}

服务器返回每个搜索引擎的 Markdown 格式概述和使用说明。

list_archives_services

列出所有支持的网络存档服务。

| 名称 | 类型 | 是否必需 | 描述 | |------|------|----------|------| | (无参数) | — | — | — |

示例

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "list_archives_services",
    "arguments": {}
  }
}

响应包括每个服务的描述、其 ID 和主要功能。

clear_cache

清除内部搜索结果缓存。

| 名称 | 类型 | 是否必需 | 描述 | |------|------|----------|------| | (无参数) | — | — | — |

示例

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "clear_cache",
    "arguments": {}
  }
}

服务器会回复一条确认消息。

🔧 技术细节

安全特性

• 查询清理：去除控制字符，移除 HTML 标签，并强制限制最大查询长度（500）。
• 严格的 URL 验证：仅接受具有有效域名的 http:// 或 https:// 协议的 URL。
• 阻止模式：使用正则表达式防止 <script> 注入、javascript: URI 和事件处理程序属性。
• 输入模式强制：每个工具通过 JSON-RPC inputSchema 验证必需字段。
• 速率限制：使用异步 I/O 信号量限制并发外部请求（MAX_CONCURRENT_SEARCHES）。

© 2025 Undici77 – 保留所有权利。