io.github.kaiser-data/kitsune-mcp

Load a Smithery skill into context. forget=True removes it.

Save an API key to .env for persistent use. e.g. key('EXA_API_KEY', 'sk-...')

search → pick server → infer args → call. Use when you don't know which server to use. auto('what time in Tokyo') auto('list issues on acme/api', server_hint='github')

Gateway wizard and connection setup. setup() → detect competing servers, preview harvest setup(action="harvest") → extract API keys from other configs → ~/.kitsune/.env setup(action="absorb") → harvest + register servers for shapeshift() setup(action="exclusive") → absorb + rewrite config (backup saved first) setup(action="restore") → restore config from backup setup(project=True) → write .claude/mcp.json with only Kitsune (this project) setup(name="my-server") → connection wizard for a connected server (existing)

Check or set credentials. ALL_CAPS = env var; server-id = creds check or OAuth. auth('GITHUB_TOKEN', 'ghp_...') # save env var auth('GITHUB_TOKEN') # check if set auth('server-id') # show creds needed / run OAuth auth('server-id', 'logout') # revoke OAuth tokens

First-run wizard — show provider auth state + the fastest path to a working tool call. Run once at the start of a new session if `kitsune:status` shows you're in base form with nothing explored. Returns provider health + a curated list of zero-config servers you can shapeshift into immediately.

Discover MCP servers across registries — the entry point to mounting. Returns a ranked list of server_ids with name, description, source, and credential-readiness status. Records discovered servers in session so status() can summarize them. Reports per-registry failures inline rather than failing the whole call. Use when: you need to find a server matching a capability before mounting. Avoid when: the server_id is already known — go straight to shapeshift() or inspect(). search('web search') # find candidates search('postgres', compare=True) # side-by-side token-cost table search('vector db', registry='smithery') registry: all|official|mcpregistry|glama|npm|smithery|pypi

Show server tools, schemas, and required credentials. Auto-probes high/medium-trust sources for live tool schemas. Community sources (npm, github, glama-via-github) are gated — pass probe=True to install and probe them, or set KITSUNE_TRUST=community.

Side-by-side token cost & creds for the top N candidates of a search. Probes ALL candidates in parallel. Use to pick a server before shapeshift(). probe=True overrides the community-trust gate for community sources.

Show Kitsune runtime state: providers, current form, connections, token stats.

Invoke a tool on an MCP server. Returns the tool's response as text. Routes through the warm pooled transport when a server is shapeshifted; otherwise spins up a transient transport for the given server_id. Records the call in session stats. Long responses (HTML, large outputs) are truncated with a continuation note. Use when: the tool name and target server are known. Avoid when: discovery is needed — auto() does search → pick → call in one step. call('get_current_time', arguments={'timezone': 'UTC'}) # after shapeshift call('list_directory', '@mcp/server-fs', {'path': '/tmp'}) # ad-hoc one-shot

Run a tool from npm/pip. package: 'pkg-name' (npx) or 'uvx:pkg-name' (Python).

Fetch a URL and return compressed content (~500 tokens vs ~25K raw HTML).

Quality-score a server 0–100. level: 'basic' (schema checks) or 'full' (live calls).

Benchmark tool latency — p50, p95, min, max ms. iterations: 1–20.

Mount an MCP server's tools at runtime. Empty server_id unmounts. shapeshift('mcp-server-time') # mount (community sources cage by default) shapeshift('id', tools=['only_this']) # lean — mount only listed tools shapeshift('id', sandbox=False) # opt out of the default Docker cage shapeshift('id', sandbox=True) # force the cage (hard-fail if no Docker) shapeshift() # unmount + kill process sandbox: None (default) cages low-trust npm/PyPI/github sources in Docker when it's available (best-effort — runs uncaged with a nudge if not); True forces the cage; False opts out. source: auto|local|smithery|official. confirm=True for community sources.

Unmount current server. kill=False keeps process pooled. uninstall=True removes local package.

Register a custom tool backed by your HTTP endpoint — live immediately. POST=JSON body, GET=query params. shiftback() removes it.

Start a persistent server. command: server_id or shell cmd (e.g. 'uvx voice-mode'). name: alias for release().

Kill a persistent connection by name.

Reload a persistent connection after editing its code — the MCP REPL in one call. reload('dev') # release the stale process, start fresh code, remount live Replaces the manual release() + connect() + shapeshift() cycle and removes the "connect() handed back the old process" footgun (it always releases first). `name` is the alias you gave connect().

Start a server's subprocess in the pool WITHOUT mounting its tools. prewarm('mcp-server-time') # spawn + pool, no tools in session shapeshift('mcp-server-time') # reuses the warm process — no npx/uvx delay For benchmarks and latency-sensitive sessions. confirm=True for community sources. Caging follows the same tri-state policy as shapeshift(): low-trust sources cage by default (sandbox=None) so a warm community process is never left uncaged then reused by a later call().