Metadata-Version: 2.4
Name: toolbase
Version: 0.5.0
Summary: The community registry and CLI for AI agent toolkits - discover, share, and serve tools to AI agents over MCP
Author-email: Alex Roman <toolbase.dev@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/alexr314/toolbase
Project-URL: Documentation, https://github.com/alexr314/toolbase#readme
Project-URL: Repository, https://github.com/alexr314/toolbase
Project-URL: Issues, https://github.com/alexr314/toolbase/issues
Keywords: ai,agents,tools,toolkit,mcp,orchestral,registry,package-manager
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.31
Requires-Dist: pyyaml>=6.0
Requires-Dist: ruamel.yaml>=0.18
Requires-Dist: rich>=13.0
Requires-Dist: pydantic>=2.0
Requires-Dist: email-validator>=2.0
Requires-Dist: orchestral-ai>=1.4
Requires-Dist: mcp>=1.0
Requires-Dist: tomlkit>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Dynamic: license-file

# toolbase

The package manager for AI agent toolkits. Install toolkits into
isolated environments, curate which tools your agent sees, and serve
them to your harness over the [Model Context Protocol](https://modelcontextprotocol.io). Toolkits
span any domain, from web and data utilities to scientific categories
like astro, hep, and quantum.

A **toolkit** is the publishable unit; it bundles one or more **tools**
an agent can call. Each toolkit installs into its own isolated Python
environment, so dependency conflicts between toolkits are never a
problem.

Full CLI reference: <https://toolbase-ai.com/docs>.

---

## Install toolbase

```bash
pip install toolbase     # Python 3.12+
```

## Arm your agent

The loop is **install → activate → connect**. `tb` is a short alias for
`toolbase`; both ship with the package and behave identically.

```bash
tb install calculator             # download into an isolated environment
tb activate calculator            # expose it to the agent
tb connect claude-code            # write toolbase into Claude Code's MCP config
```

Now launch your harness (e.g. `claude` for Claude Code) — or, in an
already-running session, reconnect the toolbase MCP server. The tools
appear as `calculator__add`, `calculator__multiply`, etc.
`tb install calculator -a` installs and activates in one step.

**Install ≠ activate.** Installing places a toolkit in the global cache
but serves nothing — activation is what exposes it to the agent. The
binary always lives in the shared cache (`~/.toolbase/cache/`); only
the activation is scoped: `tb activate` writes to the current
directory's `.toolbase/` by default, `-g` writes to the user-wide
profile instead.

**`tb connect` writes the MCP config for you.** Claude Code, Codex, and
Orchestral are all supported (`tb connect --harnesses` lists them);
Claude Code and Codex are MCP clients (`tb connect` edits their config
file), while Orchestral gets a runnable agent script you launch
yourself.

## Inspect

```bash
tb list              # installed toolkits, ✓ active / ✗ inactive
tb list -v           # per-tool view with bundle + config-gating annotations
tb logs              # tool calls, live (best diagnostic for "did it fire?")
```

## Curate what the agent sees

`tb activate` / `deactivate` work at three granularities:

```bash
tb activate calculator                # the whole toolkit
tb activate calculator/scientific     # one bundle (group of related tools)
tb activate calculator__add           # one specific tool
tb deactivate calculator__add         # hide it again
```

A **bundle** is a self-contained capability an author carves out of a
toolkit, with its own deps and skills. `tb profile tools calculator`
lists what's available. Power users can keep several named profiles
(`tb profile create paper`,
`tb connect claude-code --profile paper`) and switch between them; most
users only ever touch the default profile.

---

## Authoring a toolkit

```bash
tb init my-toolkit             # scaffold from template
cd my-toolkit
# write tools in tools/ and skills in skills/
tb validate                    # check structure
tb login                       # one-time browser-flow auth
tb publish                     # ship it (auto-registers on first run)
```

**Iterating locally.** Develop a toolkit's code without a
publish→install round-trip by installing it editable:

```bash
cd my-toolkit
tb install -e . -a             # live symlink to this source dir, and activate
```

Edits to your tool source appear on the next serve; rerun
`tb install -e .` to rebuild the env when dependencies change.

For the full author guide — tool conventions, skills, bundles,
configuration, `setup.py` — see <https://toolbase-ai.com/docs/authoring>.
For the agent-assisted authoring flow (recommended for first toolkits),
see <https://toolbase-ai.com/docs/scaffold-with-an-agent>.

---

## Commands

Full reference with all flags: <https://toolbase-ai.com/docs/reference/commands>.

| Command | Purpose |
|---|---|
| `tb install NAME` | Install a toolkit (`-a` to also activate, `-e <path>` for editable, `NAME[a,b]` for selected bundles) |
| `tb uninstall NAME` | Remove a toolkit |
| `tb list` | Installed toolkits (`-v` for a per-tool view) |
| `tb activate ITEM` | Expose a toolkit / `toolkit/bundle` / `toolkit__tool` (project-local; `-g` for user-wide) |
| `tb deactivate ITEM` | Hide a toolkit / bundle / tool |
| `tb connect HARNESS` | Wire toolbase into Claude Code, Codex, or scaffold an Orchestral agent script |
| `tb disconnect HARNESS` | Remove toolbase from a harness |
| `tb logs` | Tail the serve log, live |
| `tb profile …` | Manage named profiles: `list \| show \| create \| edit \| delete \| set-default \| path \| tools` |
| `tb config …` | Manage per-toolkit config: `show \| init \| set \| unset \| edit \| path \| validate` |
| `tb setup TOOLKIT` | Run a toolkit's `setup.py` (`--reset`, `--check`) |
| `tb project init` | Create `.toolbase/` here |
| `tb init NAME` | Scaffold a toolkit from template |
| `tb validate` / `tb ingest` | Check toolkit structure / regenerate `toolkit.yaml` from code |
| `tb login` / `tb whoami` / `tb logout` | Registry auth |
| `tb publish` | Package and upload to the registry |

See [CHANGELOG.md](CHANGELOG.md) for the full release history.

---

## Architecture

Three pieces:

- **CLI** (this package) — installed locally, manages toolkit
  environments and serves tools.
- **Backend** ([api.scitoolkit.org](https://api.scitoolkit.org)) —
  registry, auth, tarball storage.
- **Website** ([toolbase-ai.com](https://toolbase-ai.com)) — discover
  and manage published toolkits.

Each installed toolkit runs in its own subprocess in its own Python
environment. `toolbase serve` aggregates them and exposes the union as
a single MCP server upstream; failures in one toolkit don't affect
others.

---

## Contributing

Issues and PRs are welcome at
<https://github.com/alexr314/toolbase>.

## License

MIT. See [LICENSE](LICENSE).

## Links

- Website: <https://toolbase-ai.com>
- Docs: <https://toolbase-ai.com/docs>
- Backend API: <https://api.scitoolkit.org>
- GitHub: <https://github.com/alexr314/toolbase>
- Issues: <https://github.com/alexr314/toolbase/issues>
