techzone-mcp
# techzone-mcp
MCP server for [IBM Technology Zone](https://techzone.ibm.com): manage your
reservations end-to-end and search the TechZone catalog from Claude. Every
state-changing tool describes itself as such so Claude confirms with you
before calling; cancellation additionally requires echoing the reservation's
exact name.
## Tools
| Tool | What it does |
|---|---|
| `whoami()` | Validates your token, returns your TechZone profile |
| `list_reservations()` | All reservations: status, environment, dates (no credentials) |
| `get_reservation(id)` | Full detail for one reservation, incl. access info |
| `check_expiring(days)` | Active reservations ending within N days (default 3) |
| `search_catalog(term)` | Search environments/collections in the catalog |
| `get_catalog_entry(kind, name)` | Detail for one catalog entry |
| `search_collections(term)` | Search reservable TechZone collections by name |
| `get_collection(id)` | Deployment options (platforms/regions) for a collection |
| `extend_reservation(id, days)` | **Write:** extend a reservation's end date by N days |
| `create_reservation(collection_id, name, ...)` | **Write:** reserve an environment from a collection |
| `cancel_reservation(id, confirm_name)` | **Destructive:** delete a reservation (name must match) |
Plus two resources: `techzone://reservations` (live reservation summary) and
`techzone://reservation/{id}` (full detail for one reservation).
## Setup
1. Get your API token: [techzone.ibm.com](https://techzone.ibm.com) → **My Profile** → **API token**.
2. Install and register with Claude Code:
```bash
uv sync
claude mcp add techzone --env TECHZONE_API_TOKEN=<your-token> -- uv --directory /path/to/techzone-mcp run techzone-mcp
```
(Or put `TECHZONE_API_TOKEN=<your-token>` in a `.env` file in this directory —
it is gitignored.)
TechZone tokens expire periodically; when the server reports a 401, grab a
fresh token from My Profile.
## Development
```bash
uv sync
uv run pytest # unit tests (mocked, no live API)
uv run python walkthrough.py # interactive live walkthrough of every tool
```
The walkthrough steps through all 11 tools against the real API: read-only
steps run on Enter, write steps are skipped unless you type `yes`, and
sensitive service-link values are redacted from output.
API endpoints are undocumented publicly; they were derived from the
open-source [itzcli](https://github.com/cloud-native-toolkit/itzcli) and
verified live. See `PLAN.md` for design notes.
TDQS
Scored across 11 tools
Most tools target a clearly distinct resource+action: whoami (auth), list/get/create/cancel/extend_reservation (reservation lifecycle), search/get_collection (find reservable things), search/get_catalog_entry (separate Backstage catalog), check_expiring (proactive monitoring). The only mild overlap is search_collections vs search_catalog, but the descriptions explicitly differentiate them. create vs cancel vs extend are all distinct lifecycle operations with clear confirmations.
The naming follows a consistent verb_noun pattern: list_reservations, get_reservation, create_reservation, cancel_reservation, extend_reservation, search_collections, search_catalog, get_collection, get_catalog_entry. 'whoami' and 'check_expiring' are minor deviations but both are still readable single-action verbs. The pattern is highly predictable across the reservation lifecycle.
11 tools is well within the ideal range (3-15). Each tool earns its place: the reservation lifecycle needs at least 5 (list/get/create/cancel/extend), discovery needs 4 (search/get for both collections and catalog), plus whoami and check_expiring for auth and proactive monitoring. No fat to trim, no obvious missing pieces that would inflate the count.
The reservation lifecycle is complete: create, list, get, cancel, extend, plus check_expiring for monitoring. Discovery is covered for both the reservable collections and the separate Backstage catalog. The only minor gap is that once you get a reservation or collection, you can't modify things like name/region without cancel+recreate, but that matches typical reservation semantics. Overall the domain is well covered with no dead ends.