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 测试台 / HTTP API | http://localhost:12345 |
| MCP Streamable HTTP | http://localhost:12346/mcp |
| HTTP 健康检查 | http://localhost:12345/healthz |
| MCP 健康检查 | http://localhost:12346/healthz |
打开 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）：
| 变量 | 覆盖字段 |
|---|---|
SERVICE_NAME |
service.name |
SERVICE_VERSION |
service.version |
K8s 多实例部署时推荐通过 Deployment 注入 SERVICE_NAME，避免镜像里写死。
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file llm_toolforge-0.8.1.tar.gz.
File metadata
- Download URL: llm_toolforge-0.8.1.tar.gz
- Upload date:
- Size: 7.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c27df95be7398fae0f16b2504de7aef973600ef887e9b26ec227bfabc51fd17d
|
|
| MD5 |
c22bece25014aaae5b80c316455d1f23
|
|
| BLAKE2b-256 |
8a6ef84a9d2aec607a516ed49228be75ae7371a53ab02ca9236214f40fe0bfaf
|
File details
Details for the file llm_toolforge-0.8.1-py3-none-any.whl.
File metadata
- Download URL: llm_toolforge-0.8.1-py3-none-any.whl
- Upload date:
- Size: 6.5 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d234b221ffc678572f72547e321ef0b95aec3d7af4a31d59c8eaeab5d3ae2d94
|
|
| MD5 |
fdf5edadb0d1ffd8dcef6749321f2156
|
|
| BLAKE2b-256 |
d1cd457086be60a8feccdb786459388efe0b9e1f87782b628e40009f8ec2f6ae
|
