Opencode Web Search

MCP Web搜索服务器

一种模型上下文协议（MCP）服务器，使用DuckDuckGo提供网络搜索功能，用于OpenCode集成。

概述

该项目实现了一个允许OpenCode执行web搜索的MCP服务器。服务器使用DuckDuckGo作为搜索提供程序，并提供MCP工具集成和用于测试的回退命令行界面。

特性

• 网页搜索：使用DuckDuckGo执行搜索
• MCP集成：使用FastMCP实现完整的MCP服务器
• 健康检查：内置健康监测
• 错误处理：全面的错误处理和记录
• Docker支持：容器化部署
• 回退模式：依赖项不可用时的命令行测试

安装

先决条件

• Python 3.8+
• 点
• Docker（可选）

再进行

pip install -r requirements.txt

Docker安装

使用Docker Compose（推荐）：

docker compose build
docker compose up -d

或手动：

docker build -t web-search-server .
docker run -p 127.0.0.1:8000:8000 web-search-server

配置OpenCode

将MCP服务器配置添加到您的OpenCode配置文件中。看 OpenCode MCP服务器配置 了解详情。

创建或编辑 ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "web-search": {
      "type": "remote",
      "url": "http://localhost:8000",
      "enabled": true
    }
  }
}

用法

MCP服务器模式（带FastMCP）

当FastMCP可用时，服务器将作为完整的MCP服务器运行：

python src/server.py

命令行测试模式

没有FastMCP或测试时：

# Health check
python src/server.py

# Search query
python src/server.py "your search query here"

API

工具

web_search(query: str, max_results: int = 10) -> str

执行web搜索并以JSON格式返回结果。

参数：

• query：搜索查询字符串
• max_results：最大结果数（1-50，默认值：10）

退货： 带有搜索结果的JSON字符串

search_health() -> str

检查搜索服务的运行状况。

退货： 带有健康状态的JSON字符串

响应格式

搜索结果：

{
  "query": "search term",
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "snippet": "Result description..."
    }
  ],
  "count": 1
}

健康检查：

{
  "status": "healthy",
  "message": "Web search service is operational",
  "test_query_successful": true
}

发展

项目结构

src/
├── __init__.py
└── server.py            # Main MCP server implementation
tests/
├── test_server.py       # Unit tests
└── test_integration.py  # Integration/E2E tests
requirements.txt         # Python dependencies
Dockerfile               # Docker configuration
docker-compose.yml       # Docker Compose configuration
AGENTS.md                # Agent guidelines
project.md               # Project documentation
architecture.md          # Architecture documentation with diagrams

测试

运行单元测试：

python -m pytest tests/test_server.py -v

运行集成测试（需要服务器运行）：

docker compose up -d
python -m pytest tests/test_integration.py -v

运行所有测试：

python -m pytest tests/ -v

错误处理

服务器优雅地处理：

• 缺少依赖项（回退模式）
• 网络错误
• 无效的搜索查询
• 解析错误

配置

当前不需要配置文件。服务器使用默认设置的DuckDuckGo的HTML搜索端点。

OpenCode集成

要将此MCP服务器与OpenCode一起使用，请将以下配置添加到您的 ~/.config/opencode/opencode.json:

{
  "mcp": {
    "web-search": {
      "type": "remote",
      "url": "http://localhost:8000",
      "enabled": true
    }
  }
}

这使得 web_search OpenCode中的工具，用于通过DuckDuckGo执行网络搜索。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

贡献

欢迎投稿！请随时提交拉取请求。