AI导哈

AI代理工具服务器

一个为AI代理和大型语言模型提供多种工具的服务，包括基于SearXNG的搜索能力和文件系统操作。

  • by avinash-singh-io
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 avinash539/mcp-server

使用说明

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装饰器方法（推荐）

使用FastMCP装饰器的简化方法 mcp_server/server.py:

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 用于服务器管理

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

工具

搜索

通过SearXNG使用可定制的过滤功能执行网络搜索。

输入：

  • query （string）：搜索词
  • num_results （number，可选）：要返回的结果数（默认值：5，最大值：20）
  • language （字符串，可选）：结果的语言代码（例如“en”、“fr”）
  • time_range （字符串，可选）：结果的时间范围（日、周、月、年）
  • search_category （字符串，可选）：要搜索的类别（一般、图像、新闻、视频）

文件系统

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

操作：

  • 读取文件

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

  • 写入文件

    • path （string）：写入文件的路径
    • content （string）：要写的内容
    • encoding （字符串，可选）：要使用的编码（默认值：“utf-8”）
    • binary （boolean，可选）：是否以二进制模式写入（默认值：false）
    • append （boolean，可选）：是否追加到文件（默认值：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许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

运行项目的命令

python-m mcpserver启动--配置config.env

相关 MCP