llm-toolforge 0.5.0

LLM工具调用框架，同时提供 HTTP API 和 MCP Server 两种接入方式

llm-toolforge

用语大模型的工具的框架，同时提供 HTTP API（FastAPI）和 MCP Server（SSE transport）两种接入方式。

---

快速开始

安装框架

pip install llm-toolforge

# 如果是克隆的代码安装，则在根目录执行
pip install -e .

# 验证
toolforge --help

安装示例工具环境

cd examples
pip install -r requirements.txt

• 编辑示例工具的配置文件

cp config.example.yaml config.yaml
# 根据注释填写配置即可

• 运行：

toolforge run

打开页面http://localhost:12345进行测试。

部署

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

同一套基础设施（Redis / MySQL）跑多个 toolset 时，必须为每个 Deployment 设置唯一的 SERVICE_NAME，否则日志、统计、心跳会串在一起。

优先级：环境变量 > config.yaml，两者都缺失时启动直接报错。

方式 1（推荐）：环境变量

env:
  - name: SERVICE_NAME
    value: my-toolset
  - name: SERVICE_VERSION
    value: v1.0.0

方式 2：config.yaml

service:
  name: my-toolset
  version: v1.0.0

框架安装说明

一条命令即可安装全部组件（日志后端、对象存储等都已默认包含）：

pip install llm-toolforge

默认包含的可选后端：

• 日志后端（与 config.yaml 的 logging.storage 对应）：MySQL（aiomysql）、SQLite（aiosqlite）、Redis（redis，心跳 / 实时流 / 统计缓存）
• 对象存储（工具上传文件时用）：阿里云 OSS（oss2）、腾讯云 COS（cos-python-sdk-v5）

旧的 pip install llm-toolforge[all] 等命令仍可用，extra 现已为空别名，效果与直接安装一致。

框架命令

toolforge new project my-app   # 创建 ./my-app/ 并生成项目初始文件
toolforge new project .        # 在当前目录初始化项目（目录已存在时使用）
toolforge new tool <name>      # 在 tools/<name>/ 下生成工具骨架
toolforge list                 # 列出已发现的工具（确认插件加载正常）
toolforge run                  # 启动 HTTP API（默认 :12345）+ MCP SSE（默认 :12346）
toolforge run --api-only       # 只启动 HTTP API
toolforge run --mcp-only       # 只启动 MCP SSE 服务
toolforge run -c path/cfg.yaml # 指定配置文件路径

---

文档

文档	内容
工具开发指南	从零创建工具 + Generator / Plugin / InputField 完整说明
接口参考	HTTP API / MCP 协议
运行观测	日志 / 统计 / 负载监控 / 并发调优

环境变量

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

变量	覆盖字段
SERVICE_NAME	service.name
SERVICE_VERSION	service.version

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

---