kitsune-mcp 0.11.0 → 0.13.0

package/README.md

@@ -17,17 +17,16 @@
 
 ---
 
-## What's new in v0.9.0
+## What's new in v0.12.0
 
-Friction-reduction release focused on first-run onboarding, credential visibility, and agent workflows.
+Security, reliability, and quality-of-life release.
 
-- **`search()` shows credential status per result** — `✅ ready` or `✗ needs BRAVE_API_KEY` inline, so you know before you shapeshift
-- **`shapeshift(server_id, source="local", confirm=True)`** — force a local `npx`/`uvx` install without a Smithery key; `source="smithery"` forces HTTP; `source="official"` requires a verified registry listing
-- **`shiftback(uninstall=True)`** — optionally removes the locally installed package (uvx fully removed via `uv tool uninstall`; npx cache clears automatically)
-- **`KITSUNE_TRUST=community`** env var — skip the `confirm=True` gate permanently for trusted users and agents; set once via `key("KITSUNE_TRUST", "community")`
-- **First-run onboarding in `status()`** — clean sessions now show a 5-step getting-started guide with an example flow
-- **Lean-mounting hint** — after a heavy `shapeshift()` the output suggests `tools=[...]` with a concrete tool name and token cost
-- **Registry failure reporting** — `search()` now shows `⚠️ Skipped: <name> (timeout)` when one registry is slow, so you know results are partial instead of silently incomplete
+- **SSRF protection** — `fetch()` and `craft()` now block requests to private/loopback addresses (127.x, 10.x, 192.168.x, 169.254.x, localhost), consistent with `skill()`. Set `KITSUNE_ALLOW_LOCAL_FETCH=1` to allow local URLs in dev environments.
+- **Parameter aliasing** — `from_timezone` is automatically remapped to `source_timezone`, `to` to `target`, `src`/`dst`/`dest` to `source`/`target`, and language variants. Works transparently for any server with non-intuitive param names (e.g. `mcp-server-time`). Closes #9.
+- **Session persistence** — `crafted_tools` and named `connect()` sessions survive server restarts. State is written to `~/.kitsune/state.json` on exit and restored on startup. Crafted tools are re-registered automatically.
+- **Registration failures surface** — if `mcp.add_tool()` throws during `shapeshift()`, the error is now shown inline (`⚠️ N tool(s) failed to register`) instead of being silently swallowed.
+- **`auto()` prefers free stdio over Smithery HTTP** — `mcp-server-time` (official, local, free) beats a Smithery HTTP equivalent when both match a query.
+- **MCP Registry backfill** — all versions back to v0.9.0 are now listed in the MCP Registry (previously silently failing due to an OIDC change in the publisher tool).
 
 See [CHANGELOG.md](CHANGELOG.md) for the full list plus internal refactors and bug fixes.
 
@@ -71,6 +70,65 @@ Base overhead: **7 tools, ~650 tokens** ([measured](examples/benchmark.py)). Eac
 
 ---
 
+## vs. always-on connectors (Claude.ai, ChatGPT, Cursor)
+
+Most clients now offer a "connector marketplace" — Notion, Gmail, Drive, Slack, Linear, etc. — one click to enable. The catch: **every enabled connector loads its full tool surface into the system prompt of every message, for the lifetime of the conversation.** You pay for it whether you use it or not.
+
+Kitsune is lazy and parallel: one entry, every server reachable on demand, only the tools you actively call sit in context.
+
+### Notion, head to head (numbers measured live in this session)
+
+| Setup | Resting context (every turn) | One Notion search | After cleanup |
+|---|---:|---:|---:|
+| Always-on Notion connector | **13,733 tokens** | 13,733 + reply | 13,733 forever |
+| Kitsune — full Notion mounted | 3,000 tokens | 16,733 + reply | 3,000 |
+| Kitsune — `shapeshift("notion-hosted", tools=["notion-search"])` | 3,000 tokens | **4,540** + reply | 3,000 (after `shiftback`) |
+
+Over a 50-turn conversation:
+
+- Always-on connector: 50 × 13,733 = **686,650 tokens** of repeated Notion overhead
+- Kitsune lean: 50 × 3,000 + 5 turns × 1,540 = **157,700 tokens**
+
+**77% reduction for the same workflow.** And Notion is just one connector.
+
+### The "but it's just one" trap
+
+Real-world enabled-connector token costs (typical hosted MCPs):
+
+- Notion ~13.7K · Gmail ~8K · Drive ~10K · Slack ~7K · Calendar ~5K
+
+**Five connectors enabled = ~43K tokens per turn**, every turn, whether you mention them or not. Same five via Kitsune lean: ~3K resting, with a brief spike only on the turn where you actually use one.
+
+For a 100-turn dev session: 4.3M tokens of waste vs ~310K. **You can have a 14× longer conversation before hitting context limits.**
+
+### The killer demo
+
+```
+> compare("notion")
+
+   tokens  tools  src         status              id
+   13,733     14  official    live (oauth)        notion-hosted
+   18,349     22  npm         live                @notionhq/notion-mcp-server
+   ...
+
+💡 Cheapest ready-to-use: notion-hosted
+
+> shapeshift("notion-hosted", tools=["notion-search"])
+   ✓ Mounted notion-search (~1,540 tokens)
+
+> call("notion-search", {"query": "roadmap"})
+   [results]
+
+> shiftback()
+   ✓ Released. Context returned to baseline.
+```
+
+One tool. On demand. Off again. Same OAuth, same Notion endpoint (`mcp.notion.com/mcp`) — but tokens stay in `~/.kitsune/oauth/`, not on a third-party's servers.
+
+> **Connectors charge rent. Kitsune charges per use.**
+
+---
+
 ## Built for two audiences
 
 ### Adaptive agents
@@ -101,6 +159,23 @@ No separate web UI. No isolated test environment. Test how your server actually
 
 ---
 
+## Why MCP — not a CLI skill
+
+A CLI-based agent skill gives every agent the same surface. An MCP lets you design a completely different surface for each agent — down to the individual tool.
+
+**1. Surgical token budgets.**
+`shapeshift("brave-search", tools=["web_search"])` loads exactly one tool — ~300 tokens — instead of the full server schema. A specialized research agent can be wired to see only the three tools it ever needs. A coding agent sees a different three. Same underlying servers; different, purpose-built surfaces. Token overhead stays flat because context is opt-in, not always-on.
+
+**2. On-the-fly server creation.**
+CLI skills require something to already exist on disk. An MCP can be generated mid-session. An agent can call `craft(name, description, params, url)` to define a new tool backed by any HTTP endpoint — no install, no config change, no restart. One conversation. Any problem. New capability spun up and available to the same agent immediately.
+
+**3. Fine-tune the surface via the Forge.**
+`kitsune-forge` exposes the full toolkit — inspect, benchmark, craft, and test. You can prototype a tool, measure its latency, compare two competing servers, and lock in exactly the shape you want before your production agent ever sees it. The Forge is the workbench; the lean `kitsune-mcp` entry is what the agent runs with after you've dialed it in.
+
+> The result: agents that carry only the tools they need for the current problem, can extend themselves on demand, and never waste tokens on capability they aren't using.
+
+---
+
 ## Two modes
 
 | | `kitsune-mcp` | `kitsune-forge` |
@@ -291,6 +366,23 @@ Before spawning any subprocess, Kitsune MCP validates the executable name:
 
 Arguments are passed directly to `asyncio.create_subprocess_exec` (never a shell), so they are not subject to shell interpretation.
 
+### OAuth 2.1 for hosted MCP servers
+
+Many hosted MCP servers (Notion, Linear, Cloudflare) authenticate via OAuth 2.1 with Dynamic Client Registration rather than a static API key. Kitsune supports this automatically — pass the server URL directly:
+
+```python
+inspect("https://mcp.notion.com/mcp")
+# First use: browser opens, you approve, tokens are cached.
+# Subsequent runs: cached token loaded silently, refreshed when expired.
+
+shapeshift("https://mcp.notion.com/mcp")
+call("notion-search", {"query": "..."})
+```
+
+Kitsune probes `/.well-known/oauth-authorization-server` on the server origin; if present, it registers a client (RFC 7591) and runs the authorization code flow with PKCE S256. Tokens and client registrations are stored at `~/.kitsune/oauth/<origin>/` with mode `0600` — never in `.env`.
+
+Headless or no-browser environments: set `KITSUNE_NO_BROWSER=1` to have Kitsune print the authorize URL for you to paste manually (a loopback listener still captures the callback).
+
 ### Credential warnings
 
 `shapeshift()` probes tool descriptions for unreferenced environment variable patterns. If a tool mentions `BRAVE_API_KEY` and that variable isn't set, you get a warning immediately — before you call anything:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitsune-mcp",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The shape-shifting MCP hub — shapeshift() into 10,000+ MCP servers at runtime. One entry point, no restarts, 7 registries.",
   "mcpName": "io.github.kaiser-data/kitsune-mcp",
   "bin": {