toolsmelt

toolsmelt

原名 mcpsmith。uvx mcpsmith 和 mcpsmith 生成的服务仍可正常使用；系统仍会读取你保存在 ~/.mcpsmith 中的连接、MCPSMITH_* 变量和钥匙串条目。运行一次 uvx toolsmelt setup，即可切换 Agent 条目。

将 OpenAPI 文件、Postman 集合、需要登录的网站、你拥有的应用或 SQL 数据库转换为适合 AI Agent 使用的精选工具。新格式可以作为软件包接入（扩展文档）。由大模型设计工具；如果你想发布这些工具，还可以获得自己拥有的普通 Python 代码。

uvx toolsmelt setup

可转换为工具的内容

来源	命令
OpenAPI / Swagger 文件或 URL	toolsmelt inspect <file-or-url>
Postman 集合（v2.0/v2.1 导出文件）	toolsmelt inspect shop.postman_collection.json
cURL 命令（DevTools 中的“Copy as cURL”）	toolsmelt inspect requests.txt
SQL 数据库（SQLite、PostgreSQL、MySQL，以及任何 SQLAlchemy 可读取的数据库）	pip install "toolsmelt[sql]"，然后运行 toolsmelt inspect sqlite:///shop.db
SOAP 服务（WSDL 1.1）或 XML API	toolsmelt inspect https://example.com/service.asmx?WSDL
gRPC 服务（服务器反射）	pip install "toolsmelt[grpc]"，然后运行 toolsmelt inspect grpc://localhost:50051
网站或已登录的控制面板	toolsmelt browser，然后由你的 Agent 记录（toolsmelt capture <url> 可在不使用 hub 的情况下记录 HAR）
Android 应用（你拥有的 APK）	toolsmelt app-android app.apk --base-url https://api.example.com
Electron / JavaScript 应用	toolsmelt app-js <dir|app.asar|file> --base-url https://api.example.com
桌面程序	toolsmelt app-desktop（显示 mitmproxy 操作步骤），然后运行 toolsmelt app-desktop capture.har --host api.example.com

应用和程序：仅限分析你拥有或获准分析的软件。

toolsmelt --help：命令列表。

快速开始：已登录的网站

uvx toolsmelt setup                  # once: registers toolsmelt + Chrome DevTools MCP with your agents
uvx toolsmelt browser                # opens the shared Chrome; log in to the site yourself
# restart your agent, then ask it:
#   "Record example.com in the shared Chrome and connect it as tools."
# the extract-api skill runs the rest: record, inspect, design, validate, connect

你的密码和双重身份验证代码绝不会传给 Agent。详情请参阅实时 hub。

在真实软件上验证

• Tusky 29.0（开源 Android 客户端，使用 Retrofit）：toolsmelt app-android 找到了 113 个端点，并解析了所有 HTTP 方法（48 个 GET、43 个 POST、11 个 DELETE、8 个 PUT、3 个 PATCH），没有未解决的备注。精简后的注解名称是从应用自己的请求构建器类中解析出的，并非猜测所得。
• GitHub Desktop 3.6.7（Electron）：toolsmelt app-js 找到了 33 个端点，并解析了所有方法。通过应用的源映射，追溯出了全部 33 个端点对应的原始 TypeScript 行。
• hn.algolia.com（公共 API，无需登录）：在共享的 Chrome 中记录。通过 hub 连接了 2 个精选工具，并返回了实时结果。重启 hub 后，这些工具仍然存在。
• 内部考勤控制面板（ASP.NET，Cookie 登录）：登录后进行记录。2 个工具回答了所有者的问题。注销后，这些工具会返回清晰的会话过期错误。

数据来自 2026-10-21 使用 toolsmelt 0.4.0 进行的运行。可在这些应用上运行 toolsmelt app-android 和 toolsmelt app-js，复现前两项结果。

toolsmelt app-js 正在读取 Electron 应用自身的代码。

## 面向编码 Agent

无需 API 密钥：你的编码 Agent 就是设计者。

• 技能（纯 Markdown，任何 Agent 都能读取）：skills/build-mcp-server（完整工作流）、skills/extract-api（将已登录的网站转为实时工具）、skills/design-mcp-tools（设计检查清单）。AGENTS.md 会引导 Codex、Cursor 和 Gemini CLI 使用这些技能。
• MCP 工具（路径为绝对路径）：smith_guide、smith_inspect、smith_app_android、smith_app_js、smith_app_desktop、smith_probe、smith_draft、smith_validate、smith_generate、smith_check、smith_install，以及用于 hub 的 smith_record_start、smith_record_stop、smith_connect、smith_disconnect、smith_connections、smith_login、smith_tools、smith_call。
• MCP 配置，适用于任何客户端：

  {"mcpServers": {"toolsmelt": {"command": "uvx", "args": ["toolsmelt", "mcp"]}}}
  

• Claude Code 插件（技能 + MCP 服务）：/plugin marketplace add sepehr071/toolsmelt，然后运行 /plugin install toolsmelt@toolsmelt。

MCP 客户端启动服务时不会使用你 shell 中的代理变量。若在代理后运行，请添加 "env": {"HTTPS_PROXY": "http://127.0.0.1:8080"}，以便 smith_inspect 获取规范。

实时 hub

跳过项目：连接一个计划，其工具便会立即出现在你的 Agent 中。toolsmelt MCP 服务就是 hub。连接保存在 ~/.toolsmelt（TOOLSMELT_HOME）下，并会在重启后重新加载。这些连接是个人专用的（单台机器、单个用户）；发布仍需使用 generate。

从 Agent 调用：smith_inspect，编辑 plan.yaml，运行 smith_validate，然后调用 smith_connect(workdir, name) 并使用新工具。如果客户端没有显示启动后添加的工具，请使用 smith_tools(connection) 和 smith_call(connection, tool, args)（仅限只读工具）。smith_connections 会列出连接，smith_disconnect(name) 会移除连接（CLI：toolsmelt connections）。

已登录的网站

对于没有公共 API 的仪表盘或门户，Agent 会在你使用网站时记录网站自身的调用。extract-api 技能会运行完整流程。

toolsmelt browser                                                      # shared Chrome on port 9222 (--port N, --no-proxy)
npx [email protected] --browser-url=http://127.0.0.1:9222    # point Chrome DevTools MCP at it

1. 在那个 Chrome 窗口中自行登录（密码和双重身份验证信息绝不会传给 Agent）。
2. Agent 调用 smith_record_start(name, hosts)，使用不同输入浏览每项功能两次，然后调用 smith_record_stop(name)，生成一份已移除 Cookie 和令牌的 HAR。
3. Agent 检查、设计并连接计划，其中包含 auth: {type: browser, login_path: /login}。调用会复用你的 Chrome 会话；会话过期时，工具会提示你重新登录。

Agent 不得使用 DevTools get_network_request：它会打印请求标头，包括 Cookie。generate 会拒绝浏览器身份验证计划，因为这些计划只能通过你的 Chrome 使用；如要发布，请改用令牌或 API 密钥身份验证。

不使用 hub 的网站

pip install "toolsmelt[capture]" && playwright install chromium
toolsmelt capture https://example.com -o site.har --host example.com   # browse, then close the tab
toolsmelt inspect site.har --host example.com
toolsmelt draft --name example-mcp
# redesign plan.yaml, then validate, generate, check as under Export & publish

录制时，请对每个想作为工具的操作都执行一次：搜索、打开详情页、翻页、应用筛选器。未点击的内容不会被捕获。--host（可重复指定）只保留你列出的主机。DevTools 的“Save all as HAR”导出可替代 capture。设置了 HTTPS_PROXY 时，录制浏览器会使用它。

HAR 包含浏览器发送和接收的所有内容，包括 Cookie 和个人数据：请勿将其提交到 git，并在 inspect 后删除。inspect 会清理保留的内容：API 密钥或令牌会变成值已移除的 auth 环境变量，其他看起来像机密的标头和查询参数会被删除，电子邮件、电话号码、JWT，以及机密或个人字段名下的值都会在示例和测试夹具中屏蔽。这种清理基于模式，因此发布生成的服务前，请先阅读 tests/fixtures/。如果某个密钥是网站发送给所有访客的公开密钥（例如搜索或地图密钥），可以将它放在工具的 fixed 值中。

应用和程序

仅适用于你拥有或获准分析的软件。

• 桌面程序：toolsmelt app-desktop 会打印使用你自己的 mitmproxy 录制其流量的步骤（mitmdump --set hardump=capture.har）；toolsmelt app-desktop capture.har --host api.example.com 会导入结果。toolsmelt 不会替你运行任何程序，证书固定的程序不在支持范围内。
• Android 应用：toolsmelt app-android app.apk --base-url https://api.example.com 会读取应用的 Retrofit 接口。它需要反编译器：PATH 中的免费 jadx CLI（scoop install extras/jadx、brew install jadx），或 REA 的 JADX jar（REA_JADX_MCP_JAR）。如果不指定 --class，它会列出候选类。反编译前，它会在大约一秒内对 APK 进行初步分析（列出 zip 内容和检查 dex 字节）：如果是 Flutter 或 React Native 应用，或应用不使用 Retrofit，它会立即给出下一步操作（录制其流量，或对 React Native JS bundle 使用 app-js）；如果检测到已知的请求签名 SDK，则会指出要使用的登录提供方。
• 自行对请求签名的应用：计划使用 auth: {type: signin, provider: xiaomi}（Mi Home 云是第一个提供方）。用户通过服务器的 <prefix>_login 工具中的链接，在提供方自己的页面上登录（hub 中为 smith_login）；会话会保存到操作系统钥匙串。再次调用登录工具会指出账号及其数据所在位置，以便发现账号或地区选错的问题。
• Electron/JavaScript 应用：toolsmelt app-js <dir|app.asar|file> --base-url ... 会读取应用随附代码中的调用。

app-android 和 app-js 都不会运行应用。端点在未经验证前不会有示例响应；只有 toolsmelt probe 使用你的凭据在线调用 GET 端点后，端点才会通过验证（其余端点需使用 --writes，且仅在你同意后调用）。无法读取的方法会保持为空，且 validate 会拒绝该方法。

设置

uvx toolsmelt setup 会注册 toolsmelt 和 toolsmelt-chrome（Chrome DevTools）MCP 服务，并将技能复制到它找到的每个编码 Agent 中（Claude Code、Codex、Cursor、Gemini CLI）。选项：

• --dry-run 会打印计划，不会写入任何内容。
• --agents claude,codex 将范围限制为指定的 Agent（默认：找到的 Agent）。
• --rea 也会安装 REA（rea-agents）。默认关闭：它的 MCP 服务会为每个 Agent 增加约 200 个工具，而 toolsmelt 的应用工作流只需要 jadx 等普通工具。
• --no-skills 跳过技能；--yes 跳过确认。
• --remove 撤销 setup 所做的更改。你自行创建的条目和技能文件夹会保留。REA 会继续保留（你可能之前就已安装）；命令会打印用于移除它的命令行。

setup 首次更改配置文件前，会将文件复制为 *.toolsmelt.bak。备份只会创建一次，之后的运行不会更新备份。完成后重启你的 Agent。使用 Chrome DevTools 前先运行 toolsmelt browser：它会启动服务器所连接的共享 Chrome。

Claude Code 插件用户已经可以通过插件使用这两个服务，无需运行 setup。

toolsmelt install <project> 会以相同方式，为相同的 Agent 注册由 generate 创建的服务：它会运行项目文件夹（uv run --directory），或者在使用 --pypi 时运行已发布的包。它只会修改以计划命名的条目；如果同名条目运行的是其他内容，则会拒绝操作，除非指定 --force。再次运行 --remove 即可移除该条目。

toolsmelt setup --dry-run 会打印将要进行的更改，不会写入任何内容。

转换

计划通过参数上的 transform、output.transforms（date->unix、date->unix_end、unix->date、unix->datetime、minutes->hh:mm、toman->rial、rial->toman、int->str，以及可选的 Jalali 日历转换）和 timezone（IANA 名称；留空表示系统本地时区）来转换格式。

密钥

凭据由你提供，绝不会来自聊天：toolsmelt secret set <connection> <ENV_NAME> 会通过隐藏提示询问并将值存入操作系统密钥链（--once 会在使用一次后忘记该值，适用于一次性验证码；此外还有 list 和 delete 命令）。

导出并发布

要将计划转换为独立的服务项目，而不是 Hub 连接：

uvx toolsmelt inspect https://petstore3.swagger.io/api/v3/openapi.json   # .toolsmelt/source.json + digest.md
uvx toolsmelt draft --name petstore-mcp                                  # heuristic .toolsmelt/plan.yaml, no LLM
# redesign plan.yaml (your coding agent does this, or use `design`, see below)
uvx toolsmelt validate
uvx toolsmelt generate -o petstore-mcp
cd petstore-mcp && uv run pytest
uvx toolsmelt check .                                                    # call every tool live
uvx toolsmelt install .                                                  # register it with your agents

从本地文件读取的规范可能只有相对服务 URL；此时，validate 会要求你在计划中设置绝对 base_url。

让 toolsmelt 调用 LLM

uvx toolsmelt design --goal "find products, compare prices, read reviews" --provider anthropic

提供方：anthropic（ANTHROPIC_API_KEY）、openai（OPENAI_API_KEY）、openrouter（OPENROUTER_API_KEY）、ollama（无需密钥）。--model 用于选择模型；TOOLSMELT_MODEL 和 TOOLSMELT_BASE_URL 可覆盖模型和端点。结果是同一个 plan.yaml；在运行 generate 前请先检查。

工作原理

openapi.yaml | site.har --inspect--> source.json + digest.md
                        --draft----> plan.yaml     (heuristic starting point)
   your agent edits plan.yaml, or `design` ------> plan.yaml
                        --validate-> issues
                        --generate-> <name>/       (server project)
                        --check----> live report per tool

Source 是 API 提供的内容；Plan 是要构建的服务；代码生成会读取计划以及捕获的响应，用作测试夹具。精简后的计划如下：

name: shop-mcp
description: Search products and compare prices on Example Shop.
prefix: shop
base_url: https://example.com/api
env_prefix: SHOP_MCP
instructions: Search first, then fetch details with the id. Prices are in toman.
tools:
  - name: shop_search
    title: Search products
    description: Returns matching products with price and stock. Use shop_product for full details.
    endpoint: GET /v2/search
    args:
      - {name: query, type: string, required: true, description: "Search words, e.g. 'laptop'", to: query.q}
      - {name: max_price, type: integer, description: "Upper price limit in toman, e.g. 20000000", to: query.price_max}
      - {name: sort, description: "Result order.", map: {cheapest: price_asc, newest: date_desc}, default: cheapest, to: query.o}
    output:
      root: data.products
      fields: {id: id, title: title_fa, price: price.selling_price, in_stock: stock.available}
      max_items: 10
    example: {query: laptop}

参数目标（to:）：path.<n>、query.<n>、header.<n>、cookie.<n>、body、body.<a.b.c>。输出路径使用点号，数字表示索引列表（images.0.url），[] 表示映射列表（tags[].name）。map 会将模型看到的易读值转换为 API 所需的晦涩值。

工具还可以跟随分页，或串联调用（每个工具只能选其一）：

    # in one tool: read up to 3 pages and join the lists at output.root
    paginate: {style: page, param: query.page, max_pages: 3}   # or offset, cursor, next_url
    # in another: search, then fetch the details of the first 5 hits
    steps:
      - {endpoint: getProduct, for_each: data.products, max_items: 5, args: {path.id: $item.id}}

body_encoding（json、form 或 multipart）用于指定 body.* 值的发送方式。计划包含 schema_version: 1，未知键会报错（例如拼错的 readonly: 会导致失败，而不会被忽略），并且 toolsmelt schema 会输出计划的 JSON Schema，供编辑器补全和验证使用。

你将获得什么

<name>/
  pyproject.toml  server.json  README.md  LICENSE  .gitignore  toolsmelt.yaml
  src/<package>/server.py        # tools, built on toolsmelt.runtime
  tests/                         # replay captured responses; one -m live test per tool
  .github/workflows/             # ci.yml, publish.yml (PyPI + MCP Registry)
  .claude-plugin/plugin.json     # Claude Code plugin
  skills/<name>/SKILL.md         # skill for the generated server

toolsmelt.yaml 是计划，因此你可以重新生成。server.py 中的每个工具都会保留其类型化签名，并调用 toolsmelt.runtime.interpret.run_tool，也就是 Hub 运行的同一段代码。

使用 Streamable HTTP 而非 stdio 运行生成的服务（或 Hub toolsmelt mcp），可添加 --transport http --port 8000（或设置 MCP_TRANSPORT=http）；服务会在 127.0.0.1 的 /mcp 路径监听。设置 MCP_AUTH_TOKEN 可要求每个请求都携带 Authorization: Bearer <token>；也可以通过 MCP_OAUTH_ISSUER（以及可选的 MCP_OAUTH_AUDIENCE、MCP_OAUTH_SCOPES、MCP_PUBLIC_URL）将其设为身份提供方的 OAuth 2.1 资源服务：它会验证提供方的 JWT（RS256/ES256、iss、aud、exp、作用域），并发布 /.well-known/oauth-protected-resource/mcp。绑定到非回环地址的 --host 前，请先设置其中一个。发布步骤：添加 PyPI 可信发布者（工作流 publish.yml，环境 pypi），更新 pyproject.toml 和 server.json 中的版本号，然后创建 v* 标签。

数据库

toolsmelt inspect postgresql://[email protected]/shop 会读取表、列、键以及最多 3 行示例数据（个人信息值会被遮蔽）。draft 会以纯 SQL 的形式写入 list 和按键获取工具（sql: 使用 :name 占位符，参数为 to: sql.<name>）。只读工具必须是单条 SELECT（或 WITH ... SELECT）；validate 和运行时都会检查这一点，SQLite 和 PostgreSQL 还会以只读方式打开连接。密码不会写入计划：它来自 <P>_DB_PASSWORD（或在 Hub 中通过 toolsmelt secret set 设置）。请在 toolsmelt[sql] 旁安装数据库驱动（例如 psycopg）。

工具选择评估

toolsmelt eval --write --provider anthropic 会写入 evals.yaml（每个工具对应一两个用户问题，另加几个不应由任何工具回答的问题）。请检查该文件并提交。随后运行 toolsmelt eval --provider anthropic，模型会判断哪个工具以及哪些参数可以回答每个问题，并报告工具和参数的准确率，以及哪些工具容易混淆。--json 和 --min 0.9 可将其设为 CI 门禁。工具列表是缓存的提示词前缀，因此重复运行成本很低。

漂移检查

toolsmelt check <project> [--json] 会使用示例参数调用每个工具，并报告错误、输出字符数，以及返回结果中为空的字段。可在 CI 中每晚运行，以了解 API 或网站何时发生变化。它会发起真实调用，因此除非传入 --writes，否则会跳过标记为 read_only: false 的工具。

运行时功能

生成的服务会导入 toolsmelt.runtime，因此升级时修复这里即可惠及所有服务。

• 网络错误、超时、429 和 5xx 时重试（写入操作仅在 429 时重试，因此绝不会发送两次）；遵循 Retry-After 并设上限；加入抖动；限制并发数。
• GET 响应缓存、主机允许列表、5 MB 正文上限。
• 代理支持：<P>_PROXY 接受单个 URL 或逗号分隔的列表（代理池）。<P>_BASE_URL 可覆盖基础 URL。系统代理环境变量会被有意忽略。
• 适用于会拦截普通客户端的网站的 Chrome TLS 指纹：运行 pip install "toolsmelt[stealth]"，并在计划中设置 impersonate: true。未安装额外依赖时会回退到普通 httpx，并发出一条警告。
• 紧凑输出：shape() 仅保留计划中的字段，限制列表长度（报告总数），截断长字符串，并移除 null 值。
• 可操作的错误提示：403 会建议设置 <P>_PROXY；401 会指出认证环境变量；404/429/5xx 会说明后续该怎么做。
• 认证：Bearer、请求头、查询参数、Cookie 或 Basic，均从环境变量读取。

对比

大多数生成器会将每个端点映射为一个工具，并将原始 JSON 交给模型。toolsmelt 则设计少量工作流级工具，使用通俗的参数名称，描述会说明何时调用哪个后续工具，并提供紧凑输出。

	输入	输出	工具设计	响应整形	漂移检查	开源
toolsmelt	OpenAPI、HAR、应用代码	实时中心工具或 Python MCP 项目	由 LLM 设计的计划	按工具设置根节点/字段/最大条目数	toolsmelt check	是
FastMCP from_openapi	OpenAPI	运行时代理	每个端点对应一个工具；手动路由映射/转换	原始 JSON	否	是
openapi-mcp-generator	OpenAPI	TypeScript 服务	每个端点对应一个工具；通过 x-mcp 选择	原始 JSON	否	是
Speakeasy / Gram	OpenAPI	TypeScript 或托管服务	手动工具集	实验性	否	是（AGPL，自 2026 年 9 月起）
Cloudflare Forge / Code Mode	OpenAPI	SDK、CLI、MCP 服务	代码模式（搜索 + 执行）	不适用	否	是
AnythingMCP	OpenAPI、Postman、SOAP、GraphQL、SQL、HAR	可自托管的网关	每个操作对应一个工具，带可视化编辑器	手动	否	是（AGPL）
mitmproxy2swagger、har-to-openapi	HAR / 流量	OpenAPI 规范	无	无	否	是
Integuru、reverse-api-engineer	HAR / 浏览	API 客户端代码，而非 MCP	无	无	否	是
Supergood、Wire	网站操作演示	托管 API / MCP	托管	托管	供应商声明	否

内容汇总自各项目于 2026 年 10 月公开的文档；依赖表中信息前请先核实。Stainless 曾以代码模式生成 MCP 服务，于 2026 年 5 月加入 Anthropic 并停止接受新用户注册。FastMCP 自己的文档明确指出，经过精心设计的服务远胜于自动转换生成的服务。

扩展

无需分叉，即可将输入格式、值转换或登录提供方作为自行安装的包添加：toolsmelt 会通过入口点组 toolsmelt.importers、toolsmelt.transforms 和 toolsmelt.signin 查找它们。插件导入器使用 toolsmelt.scrub，遵循与内置功能相同的隐私规则。详见 docs/extending.md。

限制

• 每次调用都不会启动浏览器：JS 挑战和验证码不在支持范围内。需要处理这些内容的网站会在 check 时失败。
• 一个工具对应一个请求、一个分页请求（paginate），或一系列请求（steps，支持 for_each 扇出）。除此之外的逻辑（分支、计算值）需要手动修改生成的 server.py，重新生成会覆盖这些修改。
• 生成的项目仅支持 Python。服务通过 stdio 通信，或使用 --transport http 通过 Streamable HTTP 通信；HTTP 身份验证使用共享 bearer token（MCP_AUTH_TOKEN），或来自你自己的身份提供方的 OAuth 令牌（MCP_OAUTH_ISSUER）；toolsmelt 不是授权服务器。
• HAR 只包含录制期间执行的操作；未录制的功能不会纳入计划。
• 从应用代码中读取的端点在 probe 前未经验证；无法读取的方法会保持为空。
• 请求正文支持 JSON、表单（application/x-www-form-urlencoded）或 multipart 文本字段（工具上的 body_encoding）；不支持文件上传。
• 计划是受信任的输入：其中的文本会写入服务说明和技能中，而且 toolsmelt check 会运行生成的代码。在生成和发布第三方内容生成的 LLM 计划之前，请先检查它。
• Alpha 版。

开发

uv sync
uv run pytest -q
uv run ruff check .

请参阅 CONTRIBUTING.md 和 docs/design.md。

许可证

MIT