MCP Server

MCP 服务

一种模型上下文协议（MCP）服务实现，为 AI Agent 和大模型提供各种工具，包括由 SearXNG 提供支持的搜索功能和文件系统操作。

功能

• 网络搜索：使用 SearXNG 执行可自定义参数的网络搜索
• 文件系统操作：在安全控制下读取、写入和管理文件
• 可扩展架构：遵循 MCP 协议添加自定义工具
• Docker 支持：使用 Docker 和 docker-compose 轻松部署
• 命令行界面：通过 CLI 轻松管理
• 资源和提示词：全面支持 MCP 规范中的资源和提示词

要求

• Python 3.13（必需）
• MCP SDK ≥ 1.6.0
• 用于依赖管理的 UV 包管理器
• Docker（可选，用于容器化部署）

实现方式

本项目展示了两种实现 MCP 服务的方式：

1. FastMCP 装饰器方式（推荐）

在 mcp_server/server.py 中使用 FastMCP 装饰器的简化方式：

from mcp.server.fastmcp import FastMCP

# Create server
mcp = FastMCP("MCP Server")

# Add a tool using decorator
@mcp.tool()
def search(query: str, num_results: int = 5) -> dict:
    """Search the web"""
    # Implementation...
    return results

# Add a resource
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a greeting"""
    return f"Hello, {name}!"

# Add a prompt
@mcp.prompt()
def search_prompt(query: str) -> str:
    """Create a search prompt"""
    return f"Please search for: {query}"

2. 原始架构（高级）

mcp_server/core/ 中的原始架构提供了更复杂的实现，包括：

• 用于管理工具注册的 ToolRegistry
• 用于实现工具的 MCPTool 抽象基类
• 用于服务管理的单例 MCPServer

这种方式为复杂应用提供了更大的灵活性，但需要编写更多样板代码。

工具

search

通过 SearXNG 执行可自定义筛选条件的网络搜索。

输入：

• query（字符串）：搜索词
• num_results（数字，可选）：返回结果数量（默认值：5，最大值：20）
• language（字符串，可选）：结果的语言代码（例如，"en"、"fr"）
• time_range（字符串，可选）：结果的时间范围（day、week、month、year）
• search_category（字符串，可选）：搜索类别（general、images、news、videos）

filesystem

在安全访问控制下读取、写入和管理文件。

操作：

• 读取文件

  • path（字符串）：要读取的文件路径
  • encoding（字符串，可选）：使用的编码（默认值："utf-8"）
  • binary（布尔值，可选）：是否以二进制模式读取（默认值：false）

• 写入文件

  • path（字符串）：文件写入路径
  • content（字符串）：要写入的内容
  • encoding（字符串，可选）：使用的编码（默认值："utf-8"）
  • binary（布尔值，可选）：是否以二进制模式写入（默认值：false）
  • append（布尔值，可选）：是否追加到文件（默认值：false）

• 列出文件

  • path（字符串，可选）：要列出的目录（默认值：当前目录）
  • recursive（布尔值，可选）：是否递归列出（默认值：false）
  • pattern（字符串，可选）：用于匹配文件名的模式

配置

环境变量

使用环境变量配置 MCP 服务：

# Server settings
MCP_SERVER__HOST=0.0.0.0
MCP_SERVER__PORT=8000

# SearXNG settings
MCP_SEARXNG__INSTANCE_URL=http://localhost:8080
MCP_SEARXNG__TIMEOUT=5

# Logging settings
MCP_LOG__LEVEL=INFO

# Data directory
MCP_DATA_DIR=./data

与 Claude Desktop 搭配使用

选项 1：安装简单示例服务

# Install the simple example server directly
mcp install examples/server.py

# Or test with the MCP Inspector
mcp dev examples/server.py

选项 2：Docker 配置

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8000:8000",
        "-e",
        "MCP_SEARXNG__INSTANCE_URL=http://host.docker.internal:8080",
        "mcp-server"
      ]
    }
  }
}

你需要单独运行一个 SearXNG 实例：

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8080:8080",
        "-e", 
        "BASE_URL=http://localhost:8080/",
        "searxng/searxng"
      ]
    }
  }
}

安装

Docker（推荐）

# Build the Docker image
docker build -t mcp-server .

# Run the server and SearXNG
docker-compose up

直接安装

# Ensure you have Python 3.13 installed
python --version  # Should show Python 3.13.x

# Install uv if you don't have it
pip install uv

# Create a virtual environment and install dependencies
uv venv --python=python3.13
uv install

# Run the server
python -m mcp_server start

客户端示例

客户端示例请参阅 examples/ 目录：

• examples/client.py：使用 ClientSession API 的现代客户端
• examples/simple_client.py：使用直接 API 调用的简单客户端

使用自定义工具扩展

使用 FastMCP 方式

from mcp_server.server import mcp

@mcp.tool()
def my_custom_tool(param1: str, param2: int = 10) -> dict:
    """My custom tool description"""
    # Implement tool functionality
    return {"result": f"Processed {param1} with {param2}"}

使用原始架构

有关如何使用原始架构添加自定义工具的说明，请参阅开发者指南。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 Model Context Protocol 提供协议规范
• 感谢 SearXNG 提供搜索引擎功能

运行项目的命令

python -m mcp_server start --config config.env