内容
# MagpieMcp
基于.NET 10构建的网络搜索和网页抓取MCP（模型上下文协议）服务器，使用SearXNG作为网络搜索功能。
## 概述
MagpieMcp是一个模型上下文协议（MCP）服务器，通过安全、隔离的环境提供网络搜索和内容抓取功能。它使用SearXNG作为搜索后端，提供具有可配置设置的隐私保护的网络搜索。
## 功能
- **MCP 服务器**：为AI助手实现MCP协议
- **SearXNG 集成**：隐私保护的网络搜索后端
- **网页抓取工具**：安全的URL验证和净化内容抓取
- **模块化架构**：可配置的工具流程，具有服务组合
- **安全容器化**：基于Docker的部署，具有安全加固
- **资源隔离**：服务之间的网络级隔离
- **.NET 10**：使用最新的.NET框架构建
## 架构
```
┌─────────────┐
│ AI 客户端 │
└──────┬──────┘
│ MCP 请求
↓
┌─────────────┐
│ MagpieMcp │
│ （API） │
└──────┬──────┘
│ HTTP
↓
┌─────────────┐
│ SearXNG │
│ （搜索） │
└─────────────┘
```
## 先决条件
- Docker/Podman（用于容器化部署）
- .NET 10 SDK（用于本地开发）
## 安装
### 设置
* 修改searxng/settings.yml中的secret_key。
* 根据您的偏好更改端口和IP地址。
### 使用Docker Compose
1. 克隆仓库：
```bash
git clone <仓库网址>
cd MagpieMcp
```
2. 启动服务：
```bash
docker-compose -f docker-compose.yml up -d --build
```
或
```bash
podman-compose -f podman-compose.yml up -d --build
```
这将启动：
- **mcp-api**：端口5066上的MCP服务器
- **searxng**：搜索后端（仅限内部使用）
### 本地开发
1. 恢复依赖项：
```bash
dotnet restore
```
2. 构建项目：
```bash
dotnet build
```
3. 运行API：
```bash
dotnet run --project MagpieMcp.Api
```
4. 从compose运行searxng（使用docker-compose.override.yml在localhost上公开）：
```bash
./run_searxng_compose.sh
```
## 配置
### MCP客户端配置
配置您的MCP客户端（例如Claude Desktop）以连接到MagpieMcp：
```json
{
"mcpServers": {
"magpiemcp": {
"type": "http",
"url": "http://localhost:5066"
}
}
}
```
### 工具配置
服务器在`appsettings.json`中提供了两种主要工具的配置，服务类型如下：
**支持的服务类型：**
- **OnlyExternalUrlService**：验证外部URL并阻止私有/内部主机
- **HttpService**：对URL发出HTTP请求（支持UrlTemplate和Headers配置）
- **HtmlSanitizationService**：净化HTML内容
- **HtmlReadabilityExtractionService**：从HTML中提取可读内容
- **HtmlToMarkdownService**：将HTML转换为Markdown格式
- **SearXngJsonToMarkdownService**：将SearXNG JSON搜索结果处理为Markdown
- **InjectionSanitizationService**：防止提示注入攻击
**HttpService 配置参数：**
- **UrlTemplate**：用于构造HTTP请求的模板（支持{0}占位符用于输入）
- **Headers**：包含在请求中的HTTP头字典
注意：管道中的其他服务不需要配置参数 - 它们根据其功能使用默认行为运行。
**web_search**：使用配置的后端执行网络搜索
```json
{
"Name": "web_search",
"PreProcessSteps": [
{
"ServiceType": "HttpService",
"UrlTemplate": "http://localhost:8080/search?q={0}&format=json"
}
],
"PostProcessSteps": [
{
"ServiceType": "SearXngJsonToMarkdownService"
},
{
"ServiceType": "InjectionSanitizationService"
}
]
}
```
**web_fetch**：抓取网络内容并进行安全验证和处理
```json
{
"Name": "web_fetch",
"PreProcessSteps": [
{
"ServiceType": "OnlyExternalUrlService"
},
{
"ServiceType": "HttpService",
"UrlTemplate": "{0}"
}
],
"PostProcessSteps": [
{
"ServiceType": "HtmlSanitizationService"
},
{
"ServiceType": "HtmlReadabilityExtractionService"
},
{
"ServiceType": "HtmlToMarkdownService"
},
{
"ServiceType": "InjectionSanitizationService"
}
]
}
```
### SearXNG 设置
编辑`searxng/settings.yml`以自定义搜索行为：
```yaml
use_default_settings: true
server:
secret_key: "your-secret-key" # 为生产环境更改此设置
search:
safe_search: 1
default_lang: "en"
formats:
- html
- json
```
## 安全功能
Docker配置包括几项安全措施：
- **只读文件系统**： `/app` 和 `/etc` 以只读方式挂载
- **非root用户**：以非root用户运行
- **能力下降**： `cap_drop: ALL`
- **无新权限**： `security_opt: no-new-privileges:true`
- **资源限制**：CPU和内存约束
- **网络隔离**：API的内部网络，SearXNG出口的独立网络
## 用法
一旦运行，您就可以通过AI助手使用MCP服务器：
1. 启动MCP服务器
2. 使用搜索或抓取请求查询AI助手
3. 助手将使用MagpieMcp执行网络搜索或内容抓取
## 开发
### 项目结构
```
MagpieMcp/
├── MagpieMcp.Api/ # 主要API项目
├── MagpieMcp.Api.Tests/ # 测试项目
├── searxng/ # SearXNG配置
├── docker-compose.yml # Docker服务
├── Dockerfile # 构建配置
└── .mcp.json # MCP客户端配置
```
模块化架构使用工具服务流水线：
- **工具服务**：可配置的处理步骤（URL验证、HTTP抓取、HTML净化等）
- **配置**：使用预处理和后处理步骤定义工具
- **服务组合**：每个工具可以使用不同服务类型的多个处理阶段
### 运行测试
```bash
dotnet test --project MagpieMcp.Api.Tests
```
测试套件包括：
- **集成测试** 用于模块化工具服务流水线
- **搜索集成测试** 用于网络搜索功能
## 运行脚本
提供了几个帮助脚本：
- `run_config_compose.sh`：检查配置
- `run_full_compose.sh`：启动完整堆栈
- `run_searxng_compose.sh`：仅启动SearXNG用于调试
