llm-toolforge

面向大模型与 Agent 的 Python 工具服务框架：编写一次工具逻辑，同时提供 HTTP API、流式调用、异步任务、MCP Server 和 Web 测试台。

为什么使用 LLM ToolForge

LLM ToolForge 用于把 Python 能力快速封装成可被大模型、Agent、业务系统和 MCP 客户端调用的工具服务。框架负责接口、校验、执行、日志和部署，工具作者主要关注输入定义与业务逻辑。

主要能力：

• 一份工具实现，多种接入方式：HTTP API 与 MCP Streamable HTTP。
• 同步、SSE 流式与异步调用：适配短任务、长任务和后台任务。
• Generator 执行隔离：同步工具进入有界线程池，异步工具进入独立持久运行域， 不占用 API/MCP 主事件循环。
• 自动接口契约：根据工具输入和输出模型生成校验模型、OpenAPI 与 MCP Schema。
• Web 测试台：浏览器中查看工具、填写参数、测试 HTTP/MCP、查看日志与负载。
• 基础设施集成：内置 MySQL、SQLite、Redis、对象存储，以及 Alibaba、豆包、OpenAI、Gemini 的统一 AI Chat 能力。
• 生产运行能力：并发限制、排队与过载保护、请求超时、健康检查、调用日志和多副本配置。
• 项目脚手架：通过 CLI 创建项目和可直接运行的示例工具。

框架图

安装

python -m pip install llm-toolforge

从源码参与开发：

git clone https://github.com/lissettecarlr/llm-toolforge.git
cd llm-toolforge
python -m pip install -e ".[test]"

验证安装：

toolforge --help

快速开始

1. 创建项目

toolforge new project my-tool-service
cd my-tool-service

脚手架会生成：

my-tool-service/
├── config.yaml
├── Dockerfile
├── requirements.txt
├── README.md
├── docs/
└── tools/

config.yaml 默认开启 HTTP 与 MCP 鉴权，并为当前项目生成独立的随机 Authorization token。请妥善保管该文件，不要将真实 token 提交到公共仓库。

2. 创建第一个工具

toolforge new tool current_time

生成的工具可以直接运行，默认功能是查询指定时区的当前时间。之后可以修改：

tools/current_time/
├── __init__.py
├── generator.py
└── static/tester.html

3. 校验并启动

toolforge config validate
toolforge run

默认地址：

打开 Web 测试台后，将 config.yaml 中完整的 authorization 值粘贴到页面右上角的“API 密钥”输入框。

4. 调用 HTTP 工具

假设 config.yaml 中的值为：

authorization: "Bearer your-generated-token"

调用脚手架生成的时间工具：

curl -X POST "http://localhost:12345/current-time" \
  -H "Authorization: Bearer your-generated-token" \
  -H "Content-Type: application/json" \
  -d '{"timezone":"Asia/Shanghai"}'

流式调用只需增加 stream=true：

curl -N -X POST "http://localhost:12345/current-time?stream=true" \
  -H "Authorization: Bearer your-generated-token" \
  -H "Content-Type: application/json" \
  -d '{"timezone":"Asia/Shanghai"}'

部署

toolforge new project 会在项目目录下生成 Dockerfile

docker build -t llm-toolforge-example:v0.1.0 .

docker run --rm \
  -v "$(pwd)/config.yaml:/app/config.yaml" \
  -e SERVICE_NAME=llm-toolforge-example \
  -p 12345:12345 \
  -p 12346:12346 \
  llm-toolforge-example:v0.1.0

运行自动化测试

参与框架开发时，先在项目根目录安装源码及测试依赖：

python -m pip install -e ".[test]"

以后每次修改代码后，在项目根目录运行：

python -m pytest

环境变量

少量字段可由环境变量覆盖（优先级高于 config.yaml）：

K8s 多实例部署时推荐通过 Deployment 注入 SERVICE_NAME，避免镜像里写死。