MCP 服务器

一个模型上下文协议 (MCP) 服务器的实现，为 AI 代理和 LLM 提供各种工具，包括由 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

# 创建服务器
mcp = FastMCP("MCP Server")

# 使用装饰器添加工具
@mcp.tool()
def search(query: str, num_results: int = 5) -> dict:
    """搜索网页"""
    # 实现...
    return results

# 添加资源
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """获取问候语"""
    return f"Hello, {name}!"

# 添加提示
@mcp.prompt()
def search_prompt(query: str) -> str:
    """创建搜索提示"""
    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 服务器：

# 服务器设置
MCP_SERVER__HOST=0.0.0.0
MCP_SERVER__PORT=8000

# SearXNG 设置
MCP_SEARXNG__INSTANCE_URL=http://localhost:8080
MCP_SEARXNG__TIMEOUT=5

# 日志设置
MCP_LOG__LEVEL=INFO

# 数据目录
MCP_DATA_DIR=./data

与 Claude Desktop 一起使用

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

# 直接安装简单的示例服务器
mcp install examples/server.py

# 或者使用 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 (推荐)

# 构建 Docker 镜像
docker build -t mcp-server .

# 运行服务器和 SearXNG
docker-compose up

直接安装

# 确保您已安装 Python 3.13
python --version  # 应该显示 Python 3.13.x

# 如果您没有安装 uv，请安装它
pip install uv

# 创建一个虚拟环境并安装依赖项
uv venv --python=python3.13
uv install

# 运行服务器
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:
    """我的自定义工具描述"""
    # 实现工具功能
    return {"result": f"Processed {param1} with {param2}"}

使用原始架构

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

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• 模型上下文协议，用于协议规范
• SearXNG，用于搜索引擎功能

运行项目的命令

python -m mcp_server start --config config.env