MCP Tool Server (

MCP 工具服务（mcp_server.py）

mcp_server.py 脚本是一个异步服务，旨在通过各种通信传输方式将 Python 函数公开为“工具”。它使用 FastMCP 框架来管理工具并处理客户端交互。该服务内置了一些工具，并支持从 Python 文件或目录动态加载自定义工具。

功能

• 多种传输方式：支持通过以下方式通信：
  • stdio：标准输入/输出，适用于直接通过命令行交互或与其他进程集成。
  • sse：服务器发送事件，允许 Web 客户端订阅工具输出（监听 http://<host>:<port>/sse）。
• 内置工具：
  • echo：返回调用时传入的参数。
  • health：报告服务的运行状态（返回“ready”）。
• 自定义工具加载：
  • 从指定的 .py 文件或包含 .py 文件的目录中，动态加载 Python 函数作为工具。
  • 每个工具文件必须恰好定义一个要公开为工具的函数。
  • 支持在工具文件中导入模块。
• 可配置日志记录：
  • 默认向控制台输出 INFO 级别的消息。
  • 支持将服务应用程序和底层 MCP SDK 的详细 DEBUG 级别日志记录到指定文件。
• 异步：基于 asyncio 构建，可高效处理并发操作。

前提条件

• Python 3.x
• mcp Python 包（具体使用的是 mcp.server.fastmcp）。请确保已在 Python 环境中安装此包。

命令行用法

概要

python mcp_server.py [tools_paths...] [--log FILENAME] [--transport {stdio,sse}] [--port PORT]

选项

• tools_paths（位置参数，可为零个或多个）

  • Python 工具文件的路径，或包含 Python 工具文件的目录路径。
  • 如果提供目录，服务会搜索其中的 *.py 文件（排除名称以下划线开头的文件）。
  • 示例：./my_tool.py ./utils_directory
  • 默认值：无（如果未提供路径，则仅提供内置工具）。

• --log FILENAME

  • 将详细日志（应用程序和 MCP SDK 的 DEBUG 级别）记录到指定文件。
  • 包含工具调用、响应和内部操作的完整详情。
  • 控制台仍会显示 INFO 级别的消息。

• --transport {stdio|sse}

  • 要使用的通信传输方式。
  • stdio：使用标准输入/输出。
  • sse：使用服务器发送事件。服务默认监听 0.0.0.0。
  • 默认值：stdio

• --port PORT

  • SSE 传输使用的端口号。
  • 默认值：8080

工具加载

自定义工具是服务可以公开的 Python 函数。

• 定义：每个用作工具模块的 Python 文件（.py）都应恰好定义一个函数。此函数将注册为工具。函数名称将作为工具名称。
• 发现：
  • 如果提供 .py 文件的路径，服务会尝试从该文件加载工具。
  • 如果提供目录路径，服务会扫描目录中的 .py 文件（忽略 __init__.py 等文件，以及任何名称以下划线开头的文件），并尝试从每个有效文件加载工具。
• 导入：工具文件可以根据需要导入其他模块。加载期间，服务会临时将工具所在目录添加到 sys.path，以便进行本地导入。

示例

1. 创建自定义工具

创建一个 Python 文件，例如 calculator.py：

# calculator.py
def add(a: int, b: int) -> int:
    """
    Adds two integers and returns the result.
    """
    print(f"Tool 'add' called with a={a}, b={b}") # Example of internal tool logging
    return a + b

2. 运行服务

a) 仅使用内置工具（stdio 传输）：

python mcp_server.py

服务将启动，你可以通过标准输入/输出与 echo 和 health 工具交互（具体细节取决于 FastMCP 客户端交互协议）。

b) 使用自定义工具（stdio 传输）：

python mcp_server.py calculator.py

现在，calculator.py 中的 add 工具也可用。

c) 使用工具目录并启用详细日志记录（stdio 传输）：

假设你有一个名为 my_tools 的目录，其中包含 calculator.py 和其他工具文件：

mkdir my_tools
mv calculator.py my_tools/
# You can add more .py tool files to my_tools/

python mcp_server.py my_tools --log server.log

服务将从 my_tools 目录加载所有有效工具。详细日志将写入 server.log，INFO 消息则输出到控制台。

d) 使用 SSE 传输：

python mcp_server.py calculator.py --transport sse --port 8888

服务将启动，并在 http://0.0.0.0:8888/sse 上监听 SSE 连接。客户端可以连接到此端点，与 echo、health 和 add 工具交互。

与服务交互（概念说明）

你与工具交互的方式取决于所选的传输方式和 FastMCP 客户端实现。

• 使用 stdio 时：通常需要向服务的标准输入发送类似 JSON-RPC 的消息，并从其标准输出接收响应。

  // stdio 概念性输入示例（实际格式取决于 FastMCP）
  // {"jsonrpc": "2.0", "method": "add", "params": {"a": 5, "b": 3}, "id": 1}
  

• 使用 sse 时：客户端会连接到 /sse 端点。随后，服务会推送工具调用和响应的消息。

日志记录

• 控制台：默认情况下，INFO 级别的消息会打印到 stdout。这包括服务启动消息、已注册的工具和基本活动信息。
• 文件日志（--log 选项）：
  • 为 mcp_server.py 和 mcp SDK 启用 DEBUG 级别日志记录。
  • 日志内容非常详细，包括：
    • 详细的工具调用参数和结果。
    • 服务内部操作。
    • MCP SDK 的调试消息。
  • 日志文件采用类似以下格式：%(asctime)s - %(name)s - %(levelname)s - %(message)s。

关闭

按 Ctrl+C 可正常关闭服务。