toolbase 0.1.0__tar.gz → 0.2.0__tar.gz

toolbase-0.2.0/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to `toolbase` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+## [0.2.0] — 2026-06-05
+
+Serve/curation revamp. **Breaking** (v0, clean cutover — no compatibility aliases).
+
+### Added
+
+- `toolbase connect <client>` / `disconnect <client>` — write (or remove) the toolbase MCP entry in an agent client's config, replacing the manual JSON copy-paste. Claude Code in v1 (`~/.claude.json` for user scope, `.mcp.json` for `-l` project scope), via a pluggable adapter so Codex / Orchestral can follow. `--list` shows where toolbase is wired; `--clients` lists targets; `--profile` also sets the active profile; `--abspath` writes an absolute binary path. Non-destructive merge, atomic write.
+- `toolbase activate` / `deactivate <toolkit | toolkit/bundle | toolkit__tool>` — expose or hide tools in the active profile. The casual-tier surface; users never need to learn "profiles" to curate.
+- **Profiles** — named curated tool sets, one file per profile under `<scope>/.toolbase/profiles/<name>.yaml`. `toolbase profile <list|show|create|edit|delete|set-default|path|tools>` manages them (replaces `toolbase groups`).
+- `toolbase install -a/--activate` — install and activate in one step.
+- `toolbase list -v` — per-tool served/hidden view with bundle + config-gating annotations; `tb list` now marks each toolkit active/inactive, and `--json` gains an `active` field.
+- `toolbase config init <toolkit> [--user | --project] [--force]` — scaffold a commented YAML config file from a toolkit's `config:` schema. Defaults to the project layer (matches `config set` / `unset`); pass `--user` for the user layer. Required fields land as `<NEEDS VALUE>`; optional fields with defaults get their default; optional fields without defaults are commented out so the full schema is visible.
+- **Workspace-aware schema defaults.** `path` and `string` fields in a toolkit's `config:` block may use `${CWD}` (the orchestrator's `os.getcwd()` at serve time — i.e. the harness's launch directory, where the agent is working) or `${PROJECT_ROOT}` (the discovered `.toolbase/` parent, or `${CWD}` if there is none). Composition works (`${CWD}/scratch`). Unknown templates are rejected at schema parse time. `tb config show` renders templates alongside their current expansion.
+- **Multi-bundle tool membership.** A tool's `bundle:` field now accepts either a single name or a list (`bundle: [a, b]`); a multi-bundle tool is served if **any** of its bundles is available and counts as in-profile if any of its bundles is in the profile's allowlist.
+- **Per-bundle dependencies.** A toolkit author can declare `deps: [pip-spec]` on each bundle alongside the existing `requires:` (config-key gate). The toolkit's `requirements.txt` stays the always-installed base; bundle `deps:` add on top when the user installs that bundle.
+- **Install-time bundle selection: `tb install <toolkit>[a,b]` (pip-extras style) and `--bundle a` (flag form).** Pip-installs only the selected bundles' `deps:` on top of `requirements.txt` rather than every bundle's deps. Re-installing with new bundles is **additive** (pip-like): pip-installs the new bundles' deps into the existing venv without rebuilding. `--rebuild` forces destructive reinstall. Cache metadata (`.install_meta.yaml`) and project manifest entries record the installed bundle set; serve filters tools whose bundles are entirely outside the installed set, with a one-line summary at startup per toolkit.
+- **Subset-install visibility in `tb list`.** Version rows now end with `[subset: a, b]` when only some bundles' deps are installed (`[subset: (base only)]` for an explicit empty subset). `--json` gains an `installed_bundles` field (`null` for a full install, list for a subset). `tb list -v` annotates per-tool why a tool is hidden when its bundle isn't in the install set: `(skipped: bundle X not installed)` — multi-bundle plural `(skipped: bundles a, b not installed)`. Install-scope wins over the existing config-gating annotation since install-scope strips the deps that config-gating would later check. When 6+ tools would be install-gated in a single toolkit (large toolkits with bundle subsets — heptapod's 50-tool/8-bundle case prompted this), they collapse into a single dim summary line `(+N tools in uninstalled bundles: a, b, … — add with tb install <name>[<bundle>])` to keep the verbose output scannable. Config-gated tools stay inline since they're one `tb config set` away rather than a reinstall.
+- **Author-controlled tool display names.** A `tools[]` entry in `toolkit.yaml` may now carry an optional `display_name:` field that overrides the agent-visible name on the MCP wire (after the orchestrator's `<toolkit>__` prefix). When absent, the default is the Python class name with the trailing `Tool` suffix stripped, PascalCase preserved — so `InspireSearchTool` advertises as `heptapod__InspireSearch`. Explicit `display_name: search_papers` would advertise as `heptapod__search_papers`. Precedence: yaml `display_name:` > `@define_tool(display_name=...)` in code > derived default. The yaml layer wins because that's what the registry sees and what an author editing the file directly expects to take effect.
+
+### Changed
+
+- **Nothing-active by default.** Installing a toolkit places it in the cache but serves nothing until you `activate` it (conda-style: install ≠ activate). `tb serve` resolves an active profile — there is no "serve everything" fallback.
+- `serve.yaml` is now defaults-only: `default.profile` (the active profile) and `default.disabled` (absolute blocklists), with a two-layer user→project merge.
+- **Vocabulary:** the author-side intra-toolkit grouping is now a **bundle** (was `tool_groups:` / per-tool `group:`); the user-side curated subset is now a **profile** (was the `groups:` block in `serve.yaml`). The developer unit stays a **toolkit**. `tb serve --enable-bundle` replaces `--enable-group`.
+- **Resolved state-config is injected at tool construction time.** Tools declared with required `StateField`s (e.g. a `base_directory` the toolkit author marks `required: true`) no longer fail with a pydantic `ValidationError` on serve startup; values flow from `~/.toolbase/config/<toolkit>.yaml` (and project-layer overrides) into the tool constructor via `_import_explicit_tools`. Required fields with a schema default — literal or template — are now satisfied by the default; previously the default was ignored and the field was flagged missing.
+- **Per-tool failures during import / construction now skip just that tool**, emitting a structured `tool_import_skipped` log line to the per-toolkit log. A single misconfigured tool no longer takes down its sibling tools or the whole toolkit host.
+- **Agent-visible tool names are now PascalCase by default** (breaking on the wire — old: `heptapod__inspiresearch`, new: `heptapod__InspireSearch`). The toolkit host now sets each instance's `_mcp_display_name` to the class name with the `Tool` suffix stripped (PascalCase preserved), and calls `MCPServer(use_display_names=True)` so MCP advertises it. The previous default — `cls.__name__.removesuffix("Tool").lower()` from `BaseTool.get_name()` — collapsed word boundaries into a single lowercase blob that was both harder for the agent to read and impossible to customise per-tool short of subclassing. Agents that have hard-coded the old lowered form (logs, harness configs, scripts) need updating; agents that read the tool list each turn (Claude Code, Codex) adapt automatically.
+- **CLI startup is faster.** `tb --help` / `tb list` and similar no-network commands dropped from ~290 ms to ~50 ms warm by lazy-importing `requests`, `rich.syntax`/`pygments`, `rich.panel` / `table` / `progress`, and dropping a dead `Syntax` import. Heavy modules load only when commands that need them run.
+- `config_dir()` and `project_config_dir()` are pure path resolvers; they no longer `mkdir(parents=True, exist_ok=True)` as a side effect. Writers (`save_config` etc.) create parents lazily at write time, so a layered path lookup no longer leaves an empty `<project>/.toolbase/config/` dir behind that looks like a half-done install.
+
+### Fixed
+
+- **Orchestrator's per-tool install-scope and config-gating filter actually fires.** `tb serve` reads each toolkit's `toolkit.yaml` to build a `name_to_bundles` lookup (which bundles each tool belongs to) and consults it for every tool the host advertises. The lookup was keyed by toolkit.yaml's `tools[].name` field — the PascalCase BaseTool subclass name (e.g. `InspireSearchTool`). But the toolkit host calls `orchestral.mcp.MCPServer(..., use_display_names=False)`, which registers each tool under `BaseTool.get_name() = cls.__name__.removesuffix("Tool").lower()` — so MCP advertises `inspiresearch`, not `InspireSearchTool`. Every `name_to_bundles.get(host_advertised_name)` missed → `tool_bundles` came back `[]` → both the install-scope gate and the config-gate short-circuited (they no-op on empty bundle membership). Result: a `tb install heptapod[inspire,pdg]` subset install still surfaced ~30 tools instead of the expected ~14, including tools from bundles whose pip deps weren't installed — those would just blow up at the host's import step with a `tool_import_skipped` log line, but the orchestrator continued to advertise the rest. Normalised `name_to_bundles` keys to match the MCP form so the filter works as documented.
+- **`tb config init` scaffold no longer produces unparseable multi-document YAML.** Defaults with non-trivial values — `path` template defaults like `${CWD}`, string/integer/secret defaults — were being rendered via `yaml.safe_dump(scalar)` whose output appends a `\n...` document-end marker that the previous `.strip()` only partially trimmed (trailing newline only, not the marker). The resulting file looked like one document but parsed as two, so the orchestrator dropped the toolkit at serve startup with `config incomplete — invalid: <file> (failed to parse ...: expected a single document in the stream)` and the harness reported `Failed to reconnect to toolbase: -32000` with no obvious cause. Existing broken files don't auto-repair — delete the bare `...` line manually or re-run `tb config init --force` to regenerate.
+- **Partial-install cache slots no longer wedge subsequent `tb install` invocations.** A Ctrl-C during a long pip install (heavy bundle deps can take minutes) used to leave the cache slot with source files but no `.install_meta.yaml`. The next install with a bundle subset (`tb install foo[a,b]`) matched the "already installed with all bundles" branch, printed a misleading message about needing `--rebuild`, and exited 0 without doing anything. Two-part fix: (1) the fresh-install pipeline (source → env setup → meta write) is now wrapped in `try/finally` keyed on a success flag, so any interrupt or exception before meta-write removes the slot; (2) the collision check explicitly detects a missing `.install_meta.yaml` and treats it as a corrupted slot — auto-clean and proceed as fresh install rather than no-op.
+
+### Removed
+
+- `toolbase groups` and the `groups:` block in `serve.yaml` (replaced by profiles).
+- `tb serve` positional toolkit names and the `--group` / `--enable-tool` / `--disable-tool` one-shot flags (curation now lives in profiles; `--profile` selects one).
+
+---
+
+## [0.1.0] — 2026-05-22
+
+Initial Toolbase release. Toolbase is the community registry and CLI for AI agent toolkits — a **toolkit** is the publishable unit, and each toolkit bundles one or more **tools** that agents call over the [Model Context Protocol](https://modelcontextprotocol.io). You author and ship toolkits, install them into isolated environments, and serve them to coding agents (Claude Code, Codex) or any MCP client.
+
+> Toolbase began as `scitoolkit`. The code is mature — it shipped across nine `scitoolkit` releases (0.1.0–0.6.1) over two weeks — but `toolbase` is a new, general-purpose package on PyPI, not a rename of the published `scitoolkit`. This entry is the cumulative feature set as of the first Toolbase release; the granular pre-rebrand release notes live with the `scitoolkit` project.
+
+### Authoring and publishing
+
+- `toolbase init` — scaffold a toolkit from template (`--with-setup` for toolkits that need a `setup.py`).
+- `toolbase ingest` — register tools from existing source. Re-running over a directory that already has a `toolkit.yaml` merges (new tools appended, hand-edited entries preserved byte-for-byte) rather than overwriting; `--prune` removes stale entries, `--force` rebuilds from scratch.
+- `toolbase create` — reserve a toolkit name on the registry without uploading code (optional; `publish` auto-registers on first run).
+- `toolbase validate` — Pydantic-based pre-publish structural checks.
+- `toolbase login` — browser-flow auth that stores a per-user token good for any toolkit you own or collaborate on. Legacy per-toolkit tokens (`toolbase login <toolkit>`) are still accepted but deprecated. `whoami` / `logout` round out auth.
+- `toolbase publish [--dry-run]` — package and upload to the registry; auto-registers the name on first run, and blocks "version already exists" / "version decrease" before upload.
+
+### Installing and managing
+
+- `toolbase search` — find toolkits on the registry.
+- `toolbase install <name|path>` — download (or build from a local path), extract, and set up an isolated environment (venv or conda, auto-detected). Scope flags: `-g` (global, the default), `-l` (pin into the current project's `.toolbase/manifest.yaml`), `-e <path>` (editable — symlink a local source into the cache so `serve` loads tools live, the `pip install -e .` parallel). Multiple versions of a toolkit coexist in the global cache; the binary lives once in the shared cache and the manifest scope is independent of file location.
+- `toolbase list` / `toolbase uninstall <name>` — manage installed toolkits.
+
+### Serving
+
+- `toolbase serve` — multi-toolkit MCP aggregator (stdio). Each installed toolkit runs in its own subprocess in its own Python environment; the orchestrator aggregates them and exposes the union as a single MCP server. A crashed toolkit auto-restarts with exponential backoff and doesn't take the orchestrator down. Supports positional toolkit names, `--group`, `--enable-tool`, `--disable-tool`, `--dry-run`, `--call-timeout`.
+- `toolbase groups` — manage named tool subsets that span toolkits.
+- `toolbase logs` — tail the serve log with Rich coloring.
+
+### Configuration and setup
+
+- `toolbase config <show|edit|path|set|unset|validate>` — manage per-toolkit config at `~/.toolbase/config/<toolkit>.yaml`. Toolkits declare a `config:` block in `toolkit.yaml` (seven types: `string`, `secret`, `path`, `integer`, `float`, `boolean`, `choice`); the human-editable file is the canonical source, prompts are scaffolding.
+- `toolbase setup <toolkit>` (`--reset`, `--check`) — run a toolkit's `setup.py` for involved setup: full prompts, resumable SHA256-verified downloads with auto-extraction (tar/zip, zip-slip defended), and derived-state writes via `ctx.set_config(...)`.
+
+### Platform
+
+- **Multi-tier execution:** same-Python toolkits run in venv, different-Python toolkits run under conda (auto-detected). Docker mode is detected and refused with a clear "coming in Phase 3B" message.
+- **HTTP-loopback architecture** between the orchestrator and per-toolkit subprocesses.
+- **Per-tool selection** per serve session or persistently in `~/.toolbase/serve.yaml`.
+- **Skills surfacing:** a toolkit's `skills/*.md` files are auto-mirrored to `~/.claude/skills/` (symlinked on POSIX for live edits, copied on Windows) so Claude Code discovers them.
+- **Agent-friendly:** every state-modifying command supports `--yes`, `--no`, `--no-input`; non-TTY stdin auto-applies non-interactive behavior.
+- **`tb` alias:** every command is available as `tb` as well as `toolbase`.
+- Python 3.12+ required.

toolbase-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include CHANGELOG.md
+prune tests
+prune toolbase.egg-info
+global-exclude __pycache__ *.py[cod] .DS_Store

{toolbase-0.1.0 → toolbase-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolbase
-Version: 0.1.0
+Version: 0.2.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
@@ -29,11 +29,14 @@ 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
@@ -60,42 +63,54 @@ pip install toolbase
 # Install a toolkit from the registry (global by default)
 tb install arxiv-search
 
-# Or scope an install to the current project's manifest
-tb install -l arxiv-search
+# Expose it to the agent (installing alone serves nothing)
+tb activate arxiv-search
 
-# See what you have
-tb list
+# Wire toolbase into Claude Code (writes its MCP config for you)
+tb connect claude-code
 
-# Serve installed toolkits over MCP stdio
-tb serve
+# See what's installed and what's active
+tb list
 ```
 
 `tb` is a shorter alias for `toolbase`; both ship with the package
 and behave identically.
 
+**Install, then activate.** Installing places a toolkit in the cache but
+does not serve it — nothing reaches the agent until you `tb activate` it
+(conda-style: install ≠ activate). `tb install -a arxiv-search` does both
+in one step. Use `tb deactivate` to hide a toolkit, bundle, or tool again.
+
 Installs are global by default (`-g`). Use `-l` to pin a toolkit into
 the current project's `.toolbase/manifest.yaml` instead — the binary
 still lives in the shared global cache, only the pin is project-scoped,
 so a collaborator who clones the project and runs `tb install` (no
 args) gets the same toolkits at the same versions.
 
-To use the served toolkits in [Claude Code](https://claude.ai/code), add
-this to its MCP config:
-
-```json
-{
-  "mcpServers": {
-    "toolbase": {
-      "command": "toolbase",
-      "args": ["serve"]
-    }
-  }
-}
+**`tb connect` replaces hand-editing MCP config.** It writes the
+`toolbase` server entry into [Claude Code](https://claude.ai/code)'s
+config (`~/.claude.json` for user scope, `.mcp.json` for `-l` project
+scope). Claude Code then spawns its own `toolbase serve` subprocess and
+discovers the active profile's tools. To watch tool calls fire in real
+time, run `tb logs` in another terminal. (If you'd rather wire it by
+hand, the entry is `{"mcpServers": {"toolbase": {"command": "toolbase",
+"args": ["serve"]}}}`.)
+
+### Curating what the agent sees
+
+`tb activate` / `tb deactivate` edit the active **profile** — a named
+curated set of tools. Three granularities:
+
+```bash
+tb activate heptapod                 # the whole toolkit
+tb activate heptapod/pythia          # one bundle (a coherent group of tools)
+tb activate heptapod__run_pythia     # one specific tool
 ```
 
-Claude Code will spawn its own `toolbase serve` subprocess and
-discover all installed toolkits' tools. To watch tool calls fire in
-real time, run `tb logs` in another terminal.
+Most users only ever touch the default profile via these commands. Power
+users can keep several named profiles (`tb profile create paper`,
+`tb connect claude-code --profile paper`) and switch between them. Run
+`tb profile tools` to see the bundles and tools a toolkit offers.
 
 ---
 
@@ -127,20 +142,20 @@ publish→install round-trip on every change, install it editable:
 
 ```bash
 cd my-toolkit
-tb install -e .                 # live symlink to this source dir
-tb serve my-toolkit             # serve it; edit tools/, restart, edits are live
+tb install -e . -a              # live symlink to this source dir, and activate it
+# edit tools/, restart your agent session — edits are live
 ```
 
 An editable install symlinks your source into the cache and builds the
 environment there (your source tree stays clean — no `.venv` written
-into it). Edits to your tool source appear on the next `tb serve`. If
-you change dependencies, re-run `tb install -e .` to rebuild the env.
+into it). Edits to your tool source appear on the next serve. If you
+change dependencies, re-run `tb install -e .` to rebuild the env.
 
 For the agent-assisted authoring flow (recommended for first toolkits),
 see <https://toolbase-ai.com/docs/scaffold-with-an-agent>.
 
 For the full author guide — toolkit layout, tool conventions, skills,
-groups, expected_toolkits, configuration — see
+bundles, expected_toolkits, configuration — see
 <https://toolbase-ai.com/docs/authoring> and
 <https://toolbase-ai.com/docs/configuration>.
 
@@ -154,15 +169,23 @@ groups, expected_toolkits, configuration — see
   `publish` — author and ship toolkits.
 - `search`, `install`, `uninstall`, `list` — manage installed toolkits.
   `install` takes `-g` (global, the default), `-l` (pin into this
-  project), or `-e <path>` (editable, live symlink to a local source).
-- `serve` — run installed toolkits as an MCP stdio server. Supports
-  positional toolkit names, `--group`, `--enable-tool`,
-  `--disable-tool`, `--dry-run`, `--call-timeout`.
+  project), `-e <path>` (editable, live symlink to a local source), or
+  `-a` (also activate). `list` takes `-v` for a per-tool served/hidden
+  view.
+- `activate` / `deactivate` — expose or hide a toolkit, bundle
+  (`toolkit/bundle`), or tool (`toolkit__tool`) in the active profile.
+- `connect <client>` / `disconnect <client>` — write (or remove)
+  toolbase in an agent client's MCP config (`claude-code` in v1).
+  `--list` shows where it's wired; `--clients` lists supported targets.
+- `serve` — run the active profile's tools as an MCP stdio server
+  (`--profile`, `--dry-run`, `--call-timeout`). Normally spawned by the
+  client, not run by hand.
+- `profile <list|show|create|edit|delete|set-default|path|tools>` —
+  manage named profiles (curated tool sets).
 - `setup <toolkit>` — run a toolkit's `setup.py` (`--reset`, `--check`).
 - `config <show|edit|path|set|unset|validate>` — manage per-toolkit
   config files at `~/.toolbase/config/<toolkit>.yaml`.
 - `logs` — tail the serve log with Rich coloring.
-- `groups` — manage named tool subsets that span toolkits.
 
 **Features:**
 
@@ -190,8 +213,11 @@ groups, expected_toolkits, configuration — see
 - **Multi-tier execution:** same-Python toolkits run in venv,
   different-Python toolkits run under conda (auto-detected). Docker
   mode coming in 3B.
-- **Per-tool selection:** enable or disable individual tools per
-  serve session or persistently in `~/.toolbase/serve.yaml`.
+- **Profiles:** curated tool sets assembled across toolkits at
+  toolkit / bundle / tool granularity, stored one-file-per-profile under
+  `.toolbase/profiles/`. Activate with `tb activate`; the active profile
+  is chosen by `default.profile` in `~/.toolbase/serve.yaml` (or a
+  project-level override).
 - **Skills surfacing:** a toolkit's `skills/*.md` files are
   auto-mirrored to `~/.claude/skills/` so Claude Code discovers
   them. Symlinked on POSIX for live edits, copied on Windows.

toolbase-0.1.0/toolbase.egg-info/PKG-INFO → toolbase-0.2.0/README.md

@@ -1,41 +1,3 @@
-Metadata-Version: 2.4
-Name: toolbase
-Version: 0.1.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
-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"
-Dynamic: license-file
-
 # toolbase
 
 The package manager and runtime for AI agent tools. Publish toolkits to
@@ -60,42 +22,54 @@ pip install toolbase
 # Install a toolkit from the registry (global by default)
 tb install arxiv-search
 
-# Or scope an install to the current project's manifest
-tb install -l arxiv-search
+# Expose it to the agent (installing alone serves nothing)
+tb activate arxiv-search
 
-# See what you have
-tb list
+# Wire toolbase into Claude Code (writes its MCP config for you)
+tb connect claude-code
 
-# Serve installed toolkits over MCP stdio
-tb serve
+# See what's installed and what's active
+tb list
 ```
 
 `tb` is a shorter alias for `toolbase`; both ship with the package
 and behave identically.
 
+**Install, then activate.** Installing places a toolkit in the cache but
+does not serve it — nothing reaches the agent until you `tb activate` it
+(conda-style: install ≠ activate). `tb install -a arxiv-search` does both
+in one step. Use `tb deactivate` to hide a toolkit, bundle, or tool again.
+
 Installs are global by default (`-g`). Use `-l` to pin a toolkit into
 the current project's `.toolbase/manifest.yaml` instead — the binary
 still lives in the shared global cache, only the pin is project-scoped,
 so a collaborator who clones the project and runs `tb install` (no
 args) gets the same toolkits at the same versions.
 
-To use the served toolkits in [Claude Code](https://claude.ai/code), add
-this to its MCP config:
-
-```json
-{
-  "mcpServers": {
-    "toolbase": {
-      "command": "toolbase",
-      "args": ["serve"]
-    }
-  }
-}
+**`tb connect` replaces hand-editing MCP config.** It writes the
+`toolbase` server entry into [Claude Code](https://claude.ai/code)'s
+config (`~/.claude.json` for user scope, `.mcp.json` for `-l` project
+scope). Claude Code then spawns its own `toolbase serve` subprocess and
+discovers the active profile's tools. To watch tool calls fire in real
+time, run `tb logs` in another terminal. (If you'd rather wire it by
+hand, the entry is `{"mcpServers": {"toolbase": {"command": "toolbase",
+"args": ["serve"]}}}`.)
+
+### Curating what the agent sees
+
+`tb activate` / `tb deactivate` edit the active **profile** — a named
+curated set of tools. Three granularities:
+
+```bash
+tb activate heptapod                 # the whole toolkit
+tb activate heptapod/pythia          # one bundle (a coherent group of tools)
+tb activate heptapod__run_pythia     # one specific tool
 ```
 
-Claude Code will spawn its own `toolbase serve` subprocess and
-discover all installed toolkits' tools. To watch tool calls fire in
-real time, run `tb logs` in another terminal.
+Most users only ever touch the default profile via these commands. Power
+users can keep several named profiles (`tb profile create paper`,
+`tb connect claude-code --profile paper`) and switch between them. Run
+`tb profile tools` to see the bundles and tools a toolkit offers.
 
 ---
 
@@ -127,20 +101,20 @@ publish→install round-trip on every change, install it editable:
 
 ```bash
 cd my-toolkit
-tb install -e .                 # live symlink to this source dir
-tb serve my-toolkit             # serve it; edit tools/, restart, edits are live
+tb install -e . -a              # live symlink to this source dir, and activate it
+# edit tools/, restart your agent session — edits are live
 ```
 
 An editable install symlinks your source into the cache and builds the
 environment there (your source tree stays clean — no `.venv` written
-into it). Edits to your tool source appear on the next `tb serve`. If
-you change dependencies, re-run `tb install -e .` to rebuild the env.
+into it). Edits to your tool source appear on the next serve. If you
+change dependencies, re-run `tb install -e .` to rebuild the env.
 
 For the agent-assisted authoring flow (recommended for first toolkits),
 see <https://toolbase-ai.com/docs/scaffold-with-an-agent>.
 
 For the full author guide — toolkit layout, tool conventions, skills,
-groups, expected_toolkits, configuration — see
+bundles, expected_toolkits, configuration — see
 <https://toolbase-ai.com/docs/authoring> and
 <https://toolbase-ai.com/docs/configuration>.
 
@@ -154,15 +128,23 @@ groups, expected_toolkits, configuration — see
   `publish` — author and ship toolkits.
 - `search`, `install`, `uninstall`, `list` — manage installed toolkits.
   `install` takes `-g` (global, the default), `-l` (pin into this
-  project), or `-e <path>` (editable, live symlink to a local source).
-- `serve` — run installed toolkits as an MCP stdio server. Supports
-  positional toolkit names, `--group`, `--enable-tool`,
-  `--disable-tool`, `--dry-run`, `--call-timeout`.
+  project), `-e <path>` (editable, live symlink to a local source), or
+  `-a` (also activate). `list` takes `-v` for a per-tool served/hidden
+  view.
+- `activate` / `deactivate` — expose or hide a toolkit, bundle
+  (`toolkit/bundle`), or tool (`toolkit__tool`) in the active profile.
+- `connect <client>` / `disconnect <client>` — write (or remove)
+  toolbase in an agent client's MCP config (`claude-code` in v1).
+  `--list` shows where it's wired; `--clients` lists supported targets.
+- `serve` — run the active profile's tools as an MCP stdio server
+  (`--profile`, `--dry-run`, `--call-timeout`). Normally spawned by the
+  client, not run by hand.
+- `profile <list|show|create|edit|delete|set-default|path|tools>` —
+  manage named profiles (curated tool sets).
 - `setup <toolkit>` — run a toolkit's `setup.py` (`--reset`, `--check`).
 - `config <show|edit|path|set|unset|validate>` — manage per-toolkit
   config files at `~/.toolbase/config/<toolkit>.yaml`.
 - `logs` — tail the serve log with Rich coloring.
-- `groups` — manage named tool subsets that span toolkits.
 
 **Features:**
 
@@ -190,8 +172,11 @@ groups, expected_toolkits, configuration — see
 - **Multi-tier execution:** same-Python toolkits run in venv,
   different-Python toolkits run under conda (auto-detected). Docker
   mode coming in 3B.
-- **Per-tool selection:** enable or disable individual tools per
-  serve session or persistently in `~/.toolbase/serve.yaml`.
+- **Profiles:** curated tool sets assembled across toolkits at
+  toolkit / bundle / tool granularity, stored one-file-per-profile under
+  `.toolbase/profiles/`. Activate with `tb activate`; the active profile
+  is chosen by `default.profile` in `~/.toolbase/serve.yaml` (or a
+  project-level override).
 - **Skills surfacing:** a toolkit's `skills/*.md` files are
   auto-mirrored to `~/.claude/skills/` so Claude Code discovers
   them. Symlinked on POSIX for live edits, copied on Windows.

{toolbase-0.1.0 → toolbase-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "toolbase"
-version = "0.1.0"
+version = "0.2.0"
 description = "The community registry and CLI for AI agent toolkits - discover, share, and serve tools to AI agents over MCP"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -40,6 +40,10 @@ dependencies = [
     # Phase 3C-1 setup system relies on for state-field declaration.
     "orchestral-ai>=1.4",
     "mcp>=1.0",
+    # Round-trips ~/.codex/config.toml for `tb connect codex` while preserving
+    # the user's comments + formatting. The stdlib only reads TOML (tomllib);
+    # tomlkit is the writer (same role ruamel.yaml plays for our YAML).
+    "tomlkit>=0.12",
 ]
 
 [project.urls]
@@ -62,10 +66,14 @@ dev = [
     "black>=23.0",
     "ruff>=0.1.0",
 ]
+docs = [
+    "mkdocs-material>=9.5",
+]
 
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["toolbase*"]
+exclude = ["tests*"]
 
 [tool.setuptools.package-data]
 # Ship template files (non-.py) so `toolbase init` works on PyPI installs.