mims-harvard__tooluniverse/plugin/commands/setup-keys.md at fix/duplicate-tool-names

mirror of https://github.com/mims-harvard/ToolUniverse.git synced 2026-09-19 07:31:47 +08:00

Files

T

Shanghua Gao ac41c28fe8 Add /tooluniverse:setup-keys command for API key configuration (#194 )

* feat: add API key metadata catalog source

* feat: add API key catalog generator

* feat: generate API key catalog and regenerate .env.template

* ci: sync API key catalog from tool configs

* feat: load global ~/.tooluniverse/.env from any workspace

* feat: add .env read/mask/merge helper for key setup

* feat: add graphical API key setup server

* feat: add /tooluniverse:setup-keys command and package it

* feat: redesign setup-keys page with domain grouping and per-key context

- Group keys by research domain (Genomics & Variants, Drugs & Chemistry,
  Proteins & Structure, Literature & Patents, Clinical & Safety,
  Models & Infrastructure) instead of Required/Optional/Endpoints.
- Each key shows its purpose (what it unlocks) and a without-it note
  (blocked / demo mode / lower limits / leave blank unless self-hosting).
- Light product UI: white cards in responsive grid, indigo accent,
  Hanken Grotesk + IBM Plex Mono, live progress meter, show/hide toggles.
- Enrich api_key_metadata.json with domain, purpose, without fields;
  generator emits them in api_keys_catalog.json; .env.template regrouped
  by domain with per-key Without notes.

* fix: exclude __pycache__ from plugin scripts dir during build

cp -r was shipping stray .pyc files / __pycache__ dirs into the built
plugin if a developer had run the scripts locally before building.
Switch to rsync with explicit excludes, and add a regression test that
plants a canary __pycache__ before the build and asserts dist/ stays
clean.

* fix: split one-line try/except in pycache regression test (ruff E701)

* refactor: declare API key metadata inline in tool configs (api_key_info)

Instead of a separate api_key_metadata.json, each tool config now carries
an api_key_info block next to its required/optional_api_keys. The generator
scans configs for both the key names and their info, so adding a new key is
a one-file edit. Deletes api_key_metadata.json; runtime code is untouched
(required_api_keys stays a list of strings). Catalog + .env.template output
is byte-identical.

* chore: sync API key catalog [skip ci]

* docs: document api_key_info convention in custom-tool skill

The JSON-tool authoring guide now explains declaring required/optional_api_keys
and the inline api_key_info block (domain/purpose/without/register_url/type)
that flows into the /tooluniverse:setup-keys UI and .env.template, plus the
generator + CI auto-sync step.

* fix: add UMLS, ICD-11, Gemini, OpenRouter keys to the catalog

These keys are read by umls_tool / icd_tool / llm_clients via os.getenv but
were never declared in any tool config, so the generated catalog and
.env.template omitted them (UMLS_API_KEY + ICD_CLIENT_ID/SECRET regressed
vs main). Declare them as optional_api_keys with api_key_info on the
relevant tools so they appear in /tooluniverse:setup-keys and .env.template.
Runtime load behavior unchanged (optional, not required).

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

2026-05-26 08:50:26 -07:00

2.7 KiB

Raw Permalink Blame History

name, description

name	description
setup-keys	Set up ToolUniverse API keys. Opens a graphical setup page (or guides you in chat) listing every key tools can use, with registration links, and saves them permanently to a .env that the MCP server, CLI, and SDK all read. Use when a tool reports a missing API key or when first configuring ToolUniverse.

You are setting up ToolUniverse API keys for the user. Keys are read from the environment by tools at run time and persisted in a .env that ToolUniverse auto-loads. Follow these steps exactly.

Step 1 — Ask which mode

Ask the user (use the AskUserQuestion tool):

Graphical interface — a local web page with a form for all keys.
Agent-guided — I ask you for keys here in chat.

Step 2 — Ask where to store

Ask the user:

Global ~/.tooluniverse/.env (recommended) — works across all projects.
Project-local ./.tooluniverse/.env — only this project; read when the MCP server runs from this directory.

Resolve the target path:

Global -> ~/.tooluniverse/.env
Local -> <current working directory>/.tooluniverse/.env

Step 3a — Graphical mode

Run (do NOT redirect or background it; it prints a URL and blocks until the user saves, then exits):

python "${CLAUDE_PLUGIN_ROOT}/scripts/setup_keys_server.py" --target <TARGET_ENV_PATH>

If api_keys_catalog.json is not found next to the script (e.g. running from a source checkout), add --catalog <repo>/src/tooluniverse/data/api_keys_catalog.json.

Show the user the printed http://127.0.0.1:... URL in case the browser does not open automatically. When the command exits, report the target path and the number of keys saved. Never print the key values.

Step 3b — Agent-guided mode

Read the catalog: python -c "import json; print(json.dumps(json.load(open('${CLAUDE_PLUGIN_ROOT}/scripts/api_keys_catalog.json'))))" (fall back to the repo path src/tooluniverse/data/api_keys_catalog.json).
Ask the user whether to set all required keys, or name specific APIs.
For each selected key, show its register_url and description, then ask for the value. Do not echo previously stored values.
Write all collected values at once with the helper. keys_env.py exposes merge_env(path, updates); call it from a short inline Python snippet, passing the target path and a dict of the values you collected:

python -c "import sys; sys.path.insert(0, '${CLAUDE_PLUGIN_ROOT}/scripts'); import keys_env; keys_env.merge_env('<TARGET_ENV_PATH>', {'OMIM_API_KEY': '...'})"

Confirm the path and the names set (not the values).

Step 4 — Finish

Tell the user to restart the ToolUniverse MCP server / CLI session so the new keys load. Confirm storage location and which key names were set.

2.7 KiB Raw Permalink Blame History