toolfuncs — 把任意带类型的 Python 函数变成 Python / CLI / MCP 三接口工具

技能简介

toolfuncs 是一款用极简范式把带类型注解的 Python 函数自动暴露成三种接口——import 直接调用的 Python facade、可执行脚本调用、本地 FastMCP server——的工具库。和传统"一个函数三种 wrapper"不同，toolfuncs 用同一份代码 + entry point 同时跑通这三套接口，安装即工具、零注册、零构建。它从根本上解决了"AI 代理要 MCP 接口、脚本要用 CLI 接口、Python 应用要直接 import 调用"三个世界里重复实现同一段工具逻辑的痛点。

核心能力

• 一处定义、三处可用：写一个普通 Python 函数 + 类型注解 + docstring → 它既能 import toolfuncs.app_name.func_name() 调用，也能 app-name func-name CLI 调，还能 mcp:// 暴露给 Cursor / Claude Code / Codex。
• Cyclopts CLI 后端：基于 Cyclopts，零样板代码生成 argparse / click / typer 替代品，自动支持 --help、类型校验、子命令嵌套、shell 补全。
• 本地 FastMCP server：把 App 暴露成 stdio FastMCP server，uvx、pipx install、console-script 都自动生成接入。
• uv-launch 托管安装：uv-launch install app-name "app-name @ file:///..." 一条命令完成依赖准备 + 启动器校验和 + console script 生成，不需要手工写 executable。
• 静态发现（不 import）：通过 entry point + 安装目录 + RECORD ownership + 强校验和定位工具，不触发 import、不启动解释器、不准备依赖、不联网。
• 直接 Python 加载保留 native 语义：toolfuncs.sdk.discover(path=...) 返回 Catalog，直接调用返回真实对象和真实异常，而不是 RPC 代理。
• 目录级 facade 隔离：目录级 Python 调用会把目标包的发行版安装到调用者解释器，用其原始 venv，避免依赖地狱。
• toolfuncs doctor：本地校验模块注册的命令、生成 help 一致性、与 venv 内依赖版本兼容性。
• import_path 本地脚本契约保留：不自动 import 包级 console wrapper，避免污染 path 解析。
• PEP 723 一致性：单文件 # /// script 块（requires-python / dependencies）可执行即工具，与 uv tool run 行为一致。

安装配置

环境前置：Python ≥ 3.11，安装 pip 或 uv / pipx。

# 1. 安装 toolfuncs（任选一）
uv tool install toolfuncs
# 或者：pipx install toolfuncs

# 2. 验证版本
toolfuncs --version

# 3. 校验你已装的工具模块（任意已发包的 toolfunc 都可查）
toolfuncs doctor /path/to/agent-apps

# 4. 在你的项目 pyproject.toml 加 entry point，发布即可获得三接口
# [project]
# name = "agent-apps"
# version = "0.1.0"
# dependencies = ["toolfuncs>=1, dict[str, JsonValue]:
       """Describe one conversation.
       Parameters
       ----------
       conversation: Conversation identifier to inspect.
       """
       return {"conversation": conversation}

2. 同步暴露为 CLI + MCP：在 pyproject.toml 注册 toolfuncs entry point + console_scripts 两个 entry，重新 uv tool install agent-apps，无需其他动作。

3. Python 调用方：import agent_apps.tools; agent_apps.tools.describe_conversation("example") 直接拿原生对象。

4. CLI 调用方：agent-apps describe example 调用同一函数。

5. MCP 调用方：在 Cursor / Claude Code / Codex 里把 agent-apps 配进 MCP，自动获得 describe_conversation 工具。

6. 多环境部署：用 uv-launch install 在每台机器装命令环境，生成 launcher 校验和稳定的 immutable generation。

7. 故障排查：toolfuncs doctor /path/to/installation 会标出不匹配的 console_script / toolfuncs entry point / 生成的 help 错误。

适用场景

• 为 AI 代理暴露内部工具：把企业内部的鉴权查询 / 工单系统 / 数据库 schema 查询包装成 MCP server，接入 Cursor / Claude Code。
• CLI 工具可被 AI 直接调用：原来需要手写 CLI 的内部工具，自然同时获得 MCP 接口。
• Python 包内调用 + shell 调用需同源：避免 Python 端实现的工具和 CLI 端实现不一致（如参数解析差异）。
• 本地优先 / 离线工作流：无云 server、无长连接，stdio MCP 即可。
• 多环境隔离运维：每台机器 uv-launch 装一套相同 hash 的命令环境，避免 venv 漂移。
• AI 代理工具市场：发布到 PyPI + 注册 entry point 后，Cursor / Codex 自动发现。

适用人群

• Python 后端 / 平台工程师：想给团队 AI 助手（Cursor / Claude Code）暴露内部 API。
• CLI 工具作者：希望同一个工具既给 shell 用、也给 LLM 用。
• 企业内部工具 owner：把 jira / confluence / DB / 内部爬虫等统一成 MCP 接口给全员。
• 资深 Python 开发者：偏好类型注解 + strict typing + Cyclopts CLI 范式。
• AI 代理运维工程师：在多台开发机部署同一组工具，需要 launcher 校验和稳定。

工作原理

toolfuncs 的核心抽象是 App，一个 module-level 容器，承载所有 @app.tool 装饰的函数。

• 声明式注册：装饰器在 import 时把工具元数据（含类型注解 + docstring 第一行作为描述）写到 App 内部 catalog，不立即执行函数体。
• 三种接口编译：
  • Python facade：entry point 指向的 app 对象，调用 app.tool.name(...) 返回原生对象，保留函数签名和异常类型。
  • Cyclopts CLI：自动把 docstring + 类型注解映射成 argparse 兼容的 CLI，强制类型校验，提供 shell 补全脚本。
  • FastMCP server：entry point 同时被 stdio MCP 协议认识，启动时 introspect App 生成 tools/list JSON-RPC schema。
• 静态发现：通过 entry point 跳过 import 直接拿模块路径，记录 RECORDS ownership 和 launcher checksum，避免 import 副作用触发依赖安装或网络。
• 多 venv 桥接：通过 uvx 在调用者 venv 中按 entry point 的发行版精确运行，不污染调用者依赖——返回 native 对象而非 RPC 代理。
• uv-launch launcher 校验：每次安装生成 hash + ownership，跨机器一致；不一致会失败并提示重新安装，确保所有机器调用行为完全一致。

官方链接

• GitHub 仓库：https://github.com/nimashoghi/toolfuncs
• Issues：https://github.com/nimashoghi/toolfuncs/issues
• PyPI 项目页：toolfuncs（搜索 pip install toolfuncs）
• 许可协议：参见 GitHub 仓库（开源协议）
• 关键依赖：
  • Cyclopts（CLI 解析）
  • FastMCP（MCP 协议 stdio 实现）
  • uv（安装/运行器）