内容
# 互联网MCP
一款生产级别的MCP服务器，为本地LLM提供现实世界的能力。
互联网MCP使本地AI模型如 **Qwen**、**Llama**、**DeepSeek**、**Gemma** 和 **Mistral** 等能够通过简单、智能和模型友好的接口访问来自网络的可靠、最新的信息。
与典型的MCP服务器不同，后者暴露了许多底层工具，互联网MCP专注于提供 **少量高质量的工具**，同时在内部处理所有检索复杂性。LLM表达 **它想要什么**，服务器决定 **如何检索它**。
## 功能
### 工具（11）
- **`search_web`** — 搜索互联网以获取当前信息
- **`open_url`** — 获取任意网页并返回干净的Markdown
- **`get_weather`** — 获取任意地点的当前天气
- **`get_time`** — 获取任意IANA时区的当前时间和日期
- **`convert_currency`** — 实时货币兑换
- **`geocode`** — 前向和反向地理编码
- **`get_current_location`** — 基于IP的地理位置（城市、国家、坐标）
- **`get_crypto_price`** — 获取加密货币价格
- **`get_stock_price`** — 获取股票市场价格
- **`read_rss`** — 读取RSS/Atom订阅源
- **`wikipedia`** — 搜索和阅读维基百科文章
### 基础设施
- **智能缓存** — 按内容类型设置TTL（搜索、页面、文档、PDF）
- **可插拔的提供者** — SearXNG现已支持，Brave/Tavily后续支持
- **双重传输** — Stdio（本地）+ 流式HTTP（远程）
- **生产架构** — 依赖注入、类型错误、结构化日志
## 快速开始
### 先决条件
- Node.js 20+
- 一个 [SearXNG](https://docs.searxng.org/) 实例（自托管或公共）
### 通过Docker运行（独立/无需克隆）
如果您已安装Docker并且不想克隆仓库或安装Node.js依赖项，您可以使用预构建的镜像立即启动服务器：
```bash
# Linux / macOS / Git Bash
curl -O https://raw.githubusercontent.com/Rishon-MM/Internet-MCP/main/docker-compose.prod.yml
# Windows (PowerShell)
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Rishon-MM/Internet-MCP/main/docker-compose.prod.yml" -OutFile "docker-compose.prod.yml"
# 启动服务器和SearXNG
docker compose -f docker-compose.prod.yml up -d
# 停止服务器和SearXNG
docker compose -f docker-compose.prod.yml down
```
### 安装（本地开发/从源代码）
```bash
git clone https://github.com/Rishon-MM/Internet-MCP.git
cd internet-mcp
npm install
cp .env.example .env
# 编辑.env文件，填写您的SearXNG URL
```
### 运行（Stdio — 用于Claude Desktop、Open WebUI、VS Code）
```bash
npm run build
npm start
```
### 运行（HTTP — 用于远程访问）
```bash
npm run build
TRANSPORT=http npm start
# 服务器位于 http://localhost:3000/mcp
# 健康检查位于 http://localhost:3000/health
```
### 开发
```bash
npm run dev # 监视模式，热重载
npm test # 运行测试
npm run lint # 类型检查
```
## 配置
所有配置均通过环境变量进行。请参阅 [.env.example](.env.example) 以获取完整参考。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `SEARCH_PROVIDER` | `searxng` | 活动搜索提供者 |
| `SEARXNG_BASE_URL` | `http://localhost:8080` | SearXNG实例URL |
| `SEARXNG_TIMEOUT` | `5000` | SearXNG请求超时（毫秒） |
| `SEARXNG_SAFE_SEARCH` | `0` | 安全搜索级别（0-2） |
| `SEARCH_CACHE_TTL` | `300` | 搜索结果缓存TTL（秒） |
| `PAGE_CACHE_TTL` | `86400` | 网页缓存TTL（秒） |
| `DOC_CACHE_TTL` | `86400` | 文档缓存TTL（秒） |
| `PDF_CACHE_TTL` | `2592000` | PDF缓存TTL（秒） |
| `TRANSPORT` | `stdio` | 传输类型：`stdio` 或 `http` |
| `HTTP_PORT` | `3000` | HTTP服务器端口 |
| `LOG_LEVEL` | `info` | 日志级别 |
## 工具
### `search_web`
搜索互联网以获取当前信息。
```json
{
"query": "最新的MCP规范"
}
```
返回格式化后的Markdown，包含排名靠前的搜索结果，包括标题、URL和摘要。
### `open_url`
获取网页并返回干净的Markdown。
```json
{
"url": "https://modelcontextprotocol.io/specification/latest"
}
```
返回网页内容为干净的Markdown，去除导航、广告和脚本。
### `get_weather`
获取任意地点的当前天气。
```json
{
"location": "伦敦"
}
```
### `get_time`
获取任意IANA时区的当前时间和日期。
```json
{
"timezone": "America/New_York"
}
```
### `convert_currency`
按实时汇率进行货币兑换。
```json
{
"from": "USD",
"to": "EUR",
"amount": 100
}
```
### `geocode`
前向地理编码（地址 → 坐标）或反向地理编码（坐标 → 地址）。
```json
{
"query": "埃菲尔铁塔"
}
```
### `get_current_location`
获取当前地理位置。不需要输入。
```json
{}
```
使用多策略方法：
1. **Windows定位服务** （GPS、Wi-Fi、蓝牙） — 高精度，包括精度以米为单位
2. **IP地理位置** （[ipwho.is](https://ipwho.is)） — 当Windows定位服务不可用时的自动回退
结果包含一个`source`字段（`"windows"`或`"ip"`），以便LLM了解数据的可靠性。当获得Windows坐标时，会通过[Nominatim](https://nominatim.openstreetmap.org)进行反向地理编码，以获取人类可读的地址。
### `get_crypto_price`
获取当前加密货币价格。
```json
{
"coin": "比特币"
}
```
### `get_stock_price`
获取当前股票市场价格。
```json
{
"symbol": "AAPL"
}
```
### `read_rss`
读取和解析RSS/Atom订阅源。
```json
{
"url": "https://hnrss.org/frontpage"
}
```
### `wikipedia`
搜索和阅读维基百科文章。
```json
{
"query": "模型上下文协议"
}
```
## 架构
```
src/
├── index.ts # 组合根（依赖注入线路）
├── mcp/ # MCP协议层（薄）
│ ├── server.ts # 服务器 + 传输设置
│ ├── registry.ts # 工具注册
│ └── tools/ # 工具定义（11个工具）
├── core/ # 业务逻辑
│ ├── retrieval/ # 搜索 + 获取服务
│ │ ├── search/ # 搜索服务
│ │ ├── fetch/ # 获取 + 提取服务
│ │ ├── extract/ # HTML → Markdown提取器
│ │ └── cache/ # 内存LRU缓存
│ └── connectors/ # 外部数据连接器
│ ├── weather/ # Open-Meteo
│ ├── time/ # Node.js Intl API
│ ├── currency/ # 汇率
│ ├── geocode/ # Nominatim（OpenStreetMap）
│ ├── location/ # ipwho.is（IP地理位置）
│ ├── crypto/ # CoinGecko
│ ├── stocks/ # 股票价格
│ ├── rss/ # RSS/Atom订阅源
│ └── wikipedia/ # 维基百科API
├── providers/ # 外部服务适配器
│ └── searxng/ # SearXNG提供者
└── shared/ # 配置、日志记录、错误、类型
```
**关键设计原则：** MCP层是一个薄壳。所有业务逻辑都位于`core/`中。提供者可通过单个接口进行插拔。
请参阅 [docs/architecture.md](docs/architecture.md) 以获取完整的架构文档。
## Docker
### 1. 本地构建（从源代码）
如果您已克隆仓库并希望从源代码本地构建Docker镜像：
```bash
# 构建并启动Internet MCP + SearXNG
docker compose up -d
# Internet MCP: http://localhost:3000/mcp
# SearXNG: http://localhost:8080
```
## 客户端配置
### Claude Desktop
添加到您的Claude Desktop配置（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"internet-mcp": {
"command": "node",
"args": ["/path/to/internet-mcp/dist/index.js"],
"env": {
"SEARXNG_BASE_URL": "http://localhost:8080"
}
}
}
}
```
### Open WebUI / VS Code / Continue
配置为一个MCP服务器，带有指向`dist/index.js`的标准输入输出传输。
## 贡献
请参阅扩展指南。
要添加新的搜索提供者：
1. 从`src/core/search/search.types.ts`实现`SearchProvider`接口
2. 在`src/providers/provider.ts`中注册它
3. 将配置添加到`src/shared/config.ts`
### 工具指南
**重要：** 添加新工具时，请遵循以下核心原则：
- **LLM** 负责推理、格式化和分析数据。
- **工具** （检索引擎/连接器）负责执行请求并返回 **相关**、**未过滤**、**原始** 数据。
## 许可证
该项目是开源的，在 [MIT License](LICENSE) 下可用。
