Ez Py MCP Tools

简单的Python MCP工具

• 为模型上下文协议（MCP）服务器创建一组自定义工具的简单方法。
• 目前，该项目被用作本地MCP服务器 LmStudio （或 奥拉玛)；主要用于开源模型。
• 它允许你编写简单的Python脚本，这些脚本将显示为适当的代理工具（带有命名空间和指令）。
• 此代码尚未在macOS之外进行测试；它应该在Linux上工作正常。很抱歉，我没有Windows操作系统的机器可以测试。

但是为什么呢？

• 尽管本地OSS模型的性能不如今天的托管商业模型；它们与1-2年前的托管商业模式差不多。
• 1-2年后，OSS模型将与当今最好的商业模型相提并论。你可以购买的运行这些放在桌子上的模型的硬件也会如此。
• OSS模型带给你的商业模型没有的一件事是：完全的隐私和安全。在你自己的硬件上运行，除了电力，你什么都不用花。
• 商业模型内置了所有工具。对于像询问当前时间这样简单的事情。OSS模型离不开你，它提供了获取时间的工具。
• 这就是这个项目的目标：使工具创建变得简单，以增强OSS模型的能力。
• 试着问这个问题 What's the current time? 在启用这些工具之前。法学硕士无法回答。启用此工具后，您甚至可以问以下问题： What's the current time in Hawaii?

推荐设置（Docker）

从GitHub中提取此项目后：

• 使用Docker构建和运行（推荐），以避免主机Python/env差异。
• 创建 ./user.data.json 首先（您可以从以下位置复制 ./user.data.json.example).
• 用以下方式构建图像 make docker-build.
• 使用以下命令打印Docker MCP配置 make mcp_config 并将其粘贴到您的MCP主机（LM Studio/Ollama/McpHost）中。
• 别担心， *.data.json 文件已在 微笑。 &永远不会（意外或故意）登记入住。
• 你也可以从 ./user.data.json.example 并将其复制到 ./user.data.json:

{
  "name": {
    "first": "Jane",
    "middle": "Q",
    "last": "Public"
  },
  "birthday": "1990-01-31",
  "email": "jane@example.com",
  "phone": "+1-555-123-4567",
  "addresses": [
    "123 Main St, Springfield, IL 62701, US"
  ],
  "timezone": "America/Chicago"
}

PDF工具和临时文件共享

PDF实用程序包括两组处理中文件的方法 /tmp/ezpy_tools/pdf/:

*_save_to_file() -Base64文件输入

这些方法接受base64编码的输入并将结果保存到 /tmp/ezpy_tools/pdf/:

• from_html_save_to_file(base64_html) → 保存到 /tmp/ezpy_tools/pdf/{uuid}.pdf
• from_png_save_to_file(base64_png) → 保存到 /tmp/ezpy_tools/pdf/{uuid}.pdf
• to_html_save_to_file(base64_pdf) → 保存到 /tmp/ezpy_tools/pdf/{uuid}.html
• to_png_save_to_file(base64_pdf, page_number=1) → 保存到 /tmp/ezpy_tools/pdf/{uuid}.png

*_from_tmp_to_tmp_dir() -文件输入到文件

这些方法从中的文件读取 /tmp/ezpy_tools/pdf/ 并将结果保存回 /tmp/ezpy_tools/pdf/:

• from_html_from_tmp_to_tmp_dir(file_path) → 读取HTML，保存PDF
• from_png_from_tmp_to_tmp_dir(file_path) → 读取PNG，保存PDF
• to_html_from_tmp_to_tmp_dir(file_path) → 读取PDF，保存HTML
• to_png_from_tmp_to_tmp_dir(file_path, page_number=1) → 读取PDF，保存PNG

用于PDF工具的Docker卷装载

在Docker中使用PDF方法时，将temp目录挂载为共享卷：

# Run with tmp directory mounted for PDF file sharing
docker run --rm -i \
  -v "$PWD/user.data.json:/app/user.data.json:ro" \
  -v "/tmp/ezpy_tools/pdf:/tmp/ezpy_tools/pdf" \
  ezpy-tools

带PDF临时目录的MCP配置

{
  "mcpServers": {
    "ezpy_tools_docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/absolute/path/to/tools/user.data.json:/app/user.data.json:ro",
        "-v",
        "/tmp/ezpy_tools/pdf:/tmp/ezpy_tools/pdf",
        "ezpy-tools"
      ]
    }
  }
}

本地开发

对于本地Python开发 /tmp/ezpy_tools/pdf/ 目录是自动创建的。文件以基于UUID的文件名保存：

• *_save_to_file() 方法保存到 /tmp/ezpy_tools/pdf/{uuid}.{ext}
• *_from_tmp_to_tmp_dir() 方法从文件路径读取，保存到 /tmp/ezpy_tools/pdf/{uuid}.{ext}

文本提取工具

文本实用程序现在包括使用OCR从PDF和图像中提取强大文本的功能：

PDF文本提取

• extract_from_pdf_base64(base64_pdf) -从base64编码的PDF中提取文本（首先使用嵌入文本，然后回退到OCR）
• extract_from_pdf_path(file_path) -从给定路径的PDF文件中提取文本（例如。， /tmp/ezpy_tools/pdf/document.pdf)

图像文本提取（OCR）

• extract_from_image_base64(base64_image) -使用OCR从base64编码的图像中提取文本
• extract_from_image_path(file_path) -从给定路径的图像文件中提取文本

支持的图像格式： PNG、JPEG、GIF、BMP、TIFF、WebP、ICO、PPM、PGM、PBM以及Pillow支持的所有格式

用于文本提取的Docker配置

当使用带有文件路径的文本提取时，挂载临时目录：

docker run --rm -i \
  -v "$PWD/user.data.json:/app/user.data.json:ro" \
  -v "/tmp/ezpy_tools:/tmp/ezpy_tools" \
  ezpy-tools

安装说明

• 如果您是MCP Tooling的新手或刚刚开始人工智能工作，我建议您使用LmStudio而不是Ollama，因为LmStudio更简单、更容易上手。
• LmStudio还允许您在MLX（Apple Metal优化型号）和GGUF（NVIDIA优化型号）之间进行选择，以便更好地卸载您拥有的硬件。
• LmStudio模型搜索还显示（并允许过滤）基于工具使用、思维、视觉等模型功能。
• 建立和运行Olama的经验充其量是笨拙的。

LmStudio设置

LM Studio Screenshot

• 首选 lmstudio.ai &下载UI工具
• 使用任何支持工具使用的模型。目前（2026年2月7日），作者最喜欢的模特是 米斯特拉尔3, GPT-OSS 20B 或 GLM闪光灯 只要你有足够的VRAM并想要额外的速度。任何使用工具的模型都可以工作。
• 在撰写本文时，作者使用的是Mac Book Pro；配备M4 Max芯片，内嵌64Gb统一RAM Mistral-Small-2509（MLX）4比特 装货后还不错。适用于任何具有32G RAM或更高RAM的M系列苹果电脑。
• 模型下载完成后，将其加载到新的聊天中，然后单击🔨 （锤子图标）配置自定义MCP服务器，并从以下位置粘贴MCP配置 make mcp_config （Docker示例）；应该看起来像这样：

{
  "mcpServers": {
    "ezpy_tools_docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/absolute/path/to/tools/user.data.json:/app/user.data.json:ro",
        "ezpy-tools"
      ]
    }
  }
}

提示

• 将温度设置为低值， 0.01 以获得更好的稳定性。
• 将上下文溢出更改为 Rolling Window
• 添加以下内容 System Prompt 似乎有助于提高清晰度：

Prefer available tool for better accuracy. 
Respond with `I don't know the answer` if your confidence is lower than 70%.
Do not cache or use previous tool results.

Ollama设置

通过选择 奥拉玛，我们假设您知道自己在做什么：

• 安装 奥拉玛
• 拉动所需的Ollama模型 ollama pull '{pulled_model_name}'
• 在后台启动它： ollama serve
• 安装 McpHost （Golang项目）
• 生成默认值 McpHost 通过运行配置 make mcp_config > .mcphost.json
• 发射 McpHost 用你上面拉的模型 mcphost --model 'ollama:{pulled_model_name}'
• 这将启动一个基于控制台的聊天应用程序，其中包含配置的工具
• 问同样的问题进行测试： What's the current time?

其他商业模式和代理商

• 作为一个标准的MCP服务器，它 应该 与所有代理商和型号（包括商用）兼容。
• 目前，此MCP服务器正在为本地运行而构建 stdio 运输。
• 你可以从开始 http 或 sse 跑步运输： uv run python mcp_server.py --transport http
• *警告：* 此MCP服务器当前没有内置身份验证。请不要跑进去 http 或 sse 协议&将其暴露给开放网络。你 *将* 被黑客攻击。
• 见人类学 MCP规格 了解更多信息。

Docker for FastMCP stdio

• 这是在生产环境中运行此项目的推荐方式，就像本地使用一样。

• 塑造形象：

make docker-build

• 在所有工具上运行Docker冒烟测试：

make docker-test

• 在中运行MCP服务器 stdio Docker模式：

docker run --rm -i \
  -v "$PWD/user.data.json:/app/user.data.json:ro" \
  ezpy-tools

• 基于Docker的MCP配置示例（LmStudio/Ollama主机） stdio:

{
  "mcpServers": {
    "ezpy_tools_docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/absolute/path/to/tools/user.data.json:/app/user.data.json:ro",
        "ezpy-tools"
      ]
    }
  }
}

• 直接在Docker中运行一个工具（例如：当前时间）：

docker run --rm \
  -v "$PWD/user.data.json:/app/user.data.json:ro" \
  ezpy-tools \
  uv run python utils.py datetime__current America/Los_Angeles

本地Python设置（开发）

• 仅当您正在积极开发/调试工具代码时，才使用此功能。
• 确保已安装Python 3.12+。
• 跑 make setup 要安装依赖项，请创建/更新 user.data.json，并打印MCP配置。

编写新工具

这很简单：

• 创建新 {name_space}.py 文件下 ./utils/ 文件夹
• 在这个python脚本中，任何公共函数都将显示为MCP工具 {name_space}__{function_name}
• 函数可以接受任意数量的输入，只要它们是基本类型。他们可以回来 None 或 dict （任何变化 Dict[K, V]).看 ./utils/ 了解详情。
• 不要忘记为Python类和函数添加适当的描述/符号，因为这些最终将成为工具指令——通过此MCP服务器向您的AI代理公开。
• 对于上面的例子，我让模型能够通过以下方式显示时间 日期时间工具 current() 功能。
• 您可以使用以下命令直接测试这些工具（无需运行MCP服务器） ./tools 命令
• 您还可以通过运行以下命令通过HTTP协议运行MCP服务器 make run
• 所有可用的Python调试器都应该与 ./utils.py 或 ./tools 符号链接

测试单个工具

./tools
# print help & all available commands (what the MCP will see too)
Run: 'ls ls ' to see functions information.
Available namespaces:

  [datetime]
    Date and time utilities.

  [ip_address]
    Public IP address & approximate location utilities.

  [math]
    Standard and scientific calculator utilities.

  [user_information]
    Current user's personal information utilities.

# see all commands under datetime namespace
./tools ls datetime
[datetime]  Date and time utilities.

  [func] datetime__configured_timezone() -> dict[str, str]
         Get the currently configured timezone.

  [func] datetime__country_timezones(country_code: str = '') -> dict[str, typing.Any]
         Get all timezones for a country using ISO 3166 country code (2 chars).

  [func] datetime__current(time_zone: str = '') -> dict[str, typing.Any]
         Get the current date and time.

# test a specific command
./tools datetime__current pdt
{
  "date_time": {
    "value": "2026-02-08 02:30:33 PM",
    "iso8601": "2026-02-08T14:30:33.478463-08:00",
    "unix_timestamp": 1770589833.478463
  },
  "timezone": {
    "name": "America/Los_Angeles",
    "code": "PST",
    "utc_offset": "-0800"
  }
}

./tools 是一个符号链接文件 ./utils.py