@softspark/ai-toolkit 3.1.0 → 3.2.0

package/kb/planning/mcp-context-trim-v4-prd.md

@@ -0,0 +1,158 @@
+---
+title: "PRD: MCP Context Trim v4.0 — Local Proxy with Description Compression"
+category: planning
+service: ai-toolkit
+tags:
+  - mcp
+  - proxy
+  - tool-descriptions
+  - jsonrpc
+  - tokens
+  - v4
+doc_type: plan
+status: proposed
+created: "2026-05-04"
+last_updated: "2026-05-04"
+completion: "0%"
+target_milestone: "v4.0"
+predecessor:
+  - "kb/history/completed/output-token-discipline-plan-20260504.md"
+  - "kb/history/completed/f2-mcp-trim-spike-20260504.md"
+description: "Local MCP proxy server that compresses tool descriptions before they reach the model. Carved out of the v3.2.0 output-token-discipline plan (Feature 2), deferred after the 2026-05-04 spike showed Claude Code hooks cannot modify tools/list metadata. Targets ~8-15k token reduction per session for users with many MCP servers."
+---
+
+# PRD: MCP Context Trim v4.0
+
+**Status:** Proposed
+**Target milestone:** v4.0
+**Carved out of:** [`output-token-discipline-plan-20260504.md`](../history/completed/output-token-discipline-plan-20260504.md) (was Feature 2)
+**Spike basis:** [`f2-mcp-trim-spike-20260504.md`](../history/completed/f2-mcp-trim-spike-20260504.md)
+
+## Problem
+
+MCP server tool descriptions are injected into every model turn's system prompt. With ~100 tools across 7 typical servers, descriptions consume 8–15k tokens per turn — pure overhead, paid every message. Examples observed in users' configs:
+
+- `dart-mcp-server` — ~30 tools with multi-paragraph descriptions
+- `filesystem` — verbose paths and example sections
+- `pencil` — "IMPORTANT" stanzas repeated across tools
+- `jira-mcp` — long `Use this tool to…` boilerplate
+
+The v3.2.0 output-discipline plan attempted to solve this with a hook-based trimmer. The spike conducted 2026-05-04 proved Claude Code hooks do not expose `tools/list` metadata or the system-prompt tool catalog. The only viable architecture is a local MCP proxy.
+
+## Goal
+
+Reduce MCP-description overhead by ≥40% per server, with **zero** loss of parameter schemas, required fields, or discrimination signals (`not`, `never`, `only`, `except`, `unless`).
+
+## Non-goals
+
+- Modifying tool **call** behavior (only descriptions)
+- Compressing user-facing prompts or completions
+- Replacing or rewriting upstream MCP servers
+- Touching MCP servers we do not control
+
+## Architecture
+
+### Proxy topology
+
+```
+Claude Code  ──stdio──▶  ai-toolkit MCP proxy  ──stdio/SSE──▶  upstream MCP server
+                                │
+                                └─ rewrites tools/list response
+                                   passes through tools/call unchanged
+```
+
+One proxy process per upstream server, supervised by `ai-toolkit mcp-trim daemon` (or equivalent). User's `~/.claude/.mcp.json` is rewritten by `ai-toolkit install` (opt-in) to point Claude Code at the proxy instead of upstream — proxy reads the original target from a sidecar config.
+
+### Required components
+
+| Component | Purpose |
+|-----------|---------|
+| `scripts/mcp_proxy_server.py` | JSON-RPC 2.0 proxy. Reads stdin, forwards to upstream over stdio or SSE, intercepts `tools/list` response, rewrites descriptions. Stdlib-only. |
+| `scripts/mcp_description_trimmer.py` | Pure function library: `trim(description: str) → str`. Reused from heuristics below. Stdlib-only. |
+| `scripts/mcp_proxy_config.py` | Reads `~/.softspark/ai-toolkit/mcp-proxy/servers.json`, validates upstream targets, generates supervisord/launchd config. |
+| `app/hooks/mcp-proxy-health.sh` | SessionStart hook — verifies all configured proxies responsive; fall through (warn, do not block) if any down. |
+| `app/skills/mcp-trim/SKILL.md` | Knowledge skill: how to enable, opt out, audit savings. |
+| `bin/ai-toolkit-mcp-trim` | CLI: `enable`, `disable`, `status`, `audit` (per-server token savings report). |
+| `tests/test_mcp_proxy.bats` | Integration tests with mock upstream MCP servers. |
+| `tests/test_mcp_trimmer.bats` | Unit tests for description trim heuristics on captured fixtures. |
+
+### Compression heuristics (from spike)
+
+Applied to each tool description in `tools/list` response:
+
+- Drop example sections >40 chars
+- Collapse `Use this server to…` / `Use this tool to…` boilerplate to minimum form preserving intent
+- Drop duplicate occurrences of tool name in its own description
+- **Preserve bytewise:** `inputSchema.properties[*].description`, `required`, `enum` values, URL/path identifiers
+- **Never strip:** the words `not`, `never`, `only`, `except`, `unless` — these carry "when NOT to use" signals
+- Target: ≥40% length reduction, 0% schema loss
+
+### Failure modes & rollback
+
+| Scenario | Behavior |
+|----------|----------|
+| Proxy crashes mid-session | `mcp-proxy-health.sh` detects on next SessionStart, prints warning, suggests `ai-toolkit mcp-trim disable <server>` |
+| Upstream MCP server changes its tool catalog | Proxy passes through unchanged tools (no cached schema), warns once if a tool's description was previously trimmed |
+| Trimmer produces malformed JSON | Proxy falls through to upstream response unchanged, logs to `~/.softspark/ai-toolkit/mcp-proxy/error.log` |
+| User wants to bypass | `AI_TOOLKIT_MCP_TRIM_DISABLE=1` env var → proxies pass everything through unchanged |
+| User wants to fully uninstall | `ai-toolkit mcp-trim disable` reverts `~/.claude/.mcp.json` to original upstream targets |
+
+### Migration of existing user `.mcp.json`
+
+`ai-toolkit mcp-trim enable` does:
+
+1. Backup `~/.claude/.mcp.json` → `~/.softspark/ai-toolkit/mcp-proxy/.mcp.json.bak.<timestamp>`
+2. Read each server entry, store in `~/.softspark/ai-toolkit/mcp-proxy/servers.json`
+3. Rewrite each entry to point at the local proxy (with sidecar `target` field)
+4. Spawn supervisor (per-OS: launchd on macOS, systemd on Linux, scheduled task on Windows)
+5. Verify each upstream reachable via proxy, abort + restore backup on any failure
+
+## Out-of-scope decisions (rejected mid-spike)
+
+| Option | Why rejected |
+|--------|--------------|
+| Pre-install rewrite of `.mcp.json` only | MCP spec sources descriptions from server runtime, not config — wouldn't take effect |
+| Source-side forks of MCP servers | Doesn't help users with custom servers; high maintenance |
+| F2-lite observability tool | User decision 2026-05-04: tracking token waste without trimming is half-value; do the full thing in v4.0 |
+| Hook-based interception | Spike proved hooks cannot reach `tools/list` |
+
+## Success criteria
+
+- ≥40% description-length reduction per server on the captured fixture set (jira, filesystem, dart, pencil)
+- Deep-equal `inputSchema` between trimmed and upstream — zero schema regression
+- Proxy adds <50ms per `tools/list` call (one-time per session)
+- Proxy adds <5ms per `tools/call` (passthrough overhead)
+- Round-trip correctness: every tool callable via proxy returns byte-identical result vs direct call
+- Zero MCP-skill regressions in `npm test` after enabling proxy in CI
+- Rollback (`ai-toolkit mcp-trim disable`) restores byte-identical original `.mcp.json`
+
+## Open questions
+
+1. Process supervision per-OS — launchd / systemd / scheduled-task wrappers, or a built-in `ai-toolkit-mcp-trimd` daemon binary?
+2. SSE-mode upstreams (e.g., rag-mcp at `http://localhost:8081/mcp/sse`) — proxy listens on SSE locally too, or stdio-only with internal SSE client?
+3. Description rewrites — static dictionary of "boilerplate phrases to drop" (faster, deterministic) vs LLM-based summarizer (more aggressive, less predictable)? Recommend static for v4.0, LLM as v4.1 stretch.
+4. Config path — `~/.softspark/ai-toolkit/mcp-proxy/` (matches existing convention) or `~/.claude/mcp-proxy/` (closer to MCP config)? Recommend the former.
+5. Telemetry — does this become an opt-in metric in `/briefing --tokens` ("MCP descriptions: 12.3k → 7.2k, saved 5.1k per turn")? Recommend yes.
+
+## Pre-mortem (failure scenarios to design against)
+
+1. **Proxy gets out of sync with upstream** — upstream adds a new tool, proxy doesn't know how to compress it → passthrough that tool's description unchanged, log warning
+2. **Compression breaks tool discriminability** — model picks wrong tool because trimmed description lost the "use only when X" qualifier → the `not/never/only/except/unless` blacklist must be exhaustive; add per-server allowlists for false positives
+3. **Multi-process race on `.mcp.json` rewrite** — two `ai-toolkit install` invocations clobber each other → file lock during enable/disable
+4. **Proxy supervisor fails to start on user's machine** — different distro / no systemd → ai-toolkit doctor must detect and report; degrade to "MCP proxy unavailable, falling through" with no functionality loss
+5. **User has custom MCP server we don't recognize** — must work without per-server schema; default heuristics must be safe enough for arbitrary servers
+
+## Estimate
+
+- Architecture spike + working proxy prototype: 2 days
+- Production proxy + supervisor + config + CLI: 3 days
+- Test suite + fixtures + CI integration: 2 days
+- Documentation + migration guide + release notes: 1 day
+
+**Total: ~8 working days** (1.5–2 weeks calendar time at typical pace)
+
+## Status
+
+| Date | Status | Author |
+|------|--------|--------|
+| 2026-05-04 | PRD drafted from spike conclusions, carved out of v3.2.0 plan | claude |

package/kb/procedures/release-verification-sop.md

@@ -3,10 +3,10 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
-version: "1.4.1"
+version: "1.4.2"
 created: "2026-04-08"
-last_updated: "2026-04-28"
-description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds."
+last_updated: "2026-04-29"
+description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds. v1.4.2 makes the Phase 9.4 idempotence check deterministic by sorting file paths before hashing."
 ---
 
 # SOP: Release Verification
@@ -382,10 +382,13 @@ grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Ge
 
 ```bash
 D=/tmp/aitk-idem-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+# Sort file paths before hashing — find traversal order follows inode order,
+# which can shift between runs even when content is byte-identical, producing
+# false FAIL signals.
 ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
-SHA1=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
+SHA1=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
 ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
-SHA2=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
+SHA2=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
 [ "$SHA1" = "$SHA2" ] && echo "OK: idempotent" || echo "FAIL: install is not idempotent"
 ```
 

package/kb/reference/architecture-overview.md

@@ -186,8 +186,8 @@ Three tiers determine how to approach a task:
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
-| Hybrid | (neither) | User via `/skill` + agent knowledge | 31 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 49 |
+| Hybrid | (neither) | User via `/skill` + agent knowledge | 32 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 48 |
 
 ## Multi-Agent Execution
 

package/kb/reference/skills-catalog.md

@@ -62,7 +62,7 @@ Task skills execute a specific action. Invoked via slash commands. `disable-mode
 | **seo-validate** | `/seo-validate` | medium | Scan codebase for SEO issues: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Framework-aware (Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML). |
 | **mcp-builder** | `/mcp-builder` | high | Build production-grade MCP servers using the 4-phase methodology (research, implement, test, evaluate). TypeScript/Python, stdio/streamable-http. |
 
-## Hybrid Skills (31)
+## Hybrid Skills (32)
 
 Hybrid skills combine slash-command invocation with domain knowledge that agents reference.
 
@@ -99,6 +99,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **persona** | `/persona` | low | Switch engineering persona at runtime (backend-lead, frontend-lead, devops-eng, junior-dev) |
 | **council** | `/council` | high | 4-perspective decision evaluation (Advocate, Critic, Pragmatist, User-Proxy) with synthesis and confidence-rated recommendation. Tier 1, orchestrator, `context: fork`. |
 | **introspect** | `/introspect` | medium | Agent self-debugging: classify failure pattern, suggest smallest recovery action, emit structured introspection report |
+| **brand-voice** | `/brand-voice` | medium | Anti-trope list, voice principles, LLM rhetoric prevention; output modes (`concise` ≤60% tokens, `strict` ≤40%) governing conversational responses. |
 
 ### `/workflow` types
 
@@ -120,7 +121,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | `application-deploy` | 3 | Deploy → smoke test → release notes |
 | `proactive-troubleshooting` | 4 | Investigate → check perf → preventive fix → docs |
 
-## Knowledge Skills - Development (16)
+## Knowledge Skills - Development (15)
 
 | Skill | Directory | Domain |
 |-------|-----------|--------|
@@ -139,7 +140,6 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **ruby-patterns** | `skills/ruby-patterns/` | Blocks, Rails conventions, RSpec, ActiveRecord |
 | **design-engineering** | `skills/design-engineering/` | UI polish, animation craft, easing, transforms, accessibility |
 | **documentation-standards** | `skills/documentation-standards/` | KB document conventions, frontmatter validation, category taxonomy |
-| **brand-voice** | `skills/brand-voice/` | Anti-trope list, voice principles, LLM rhetoric prevention |
 
 ## Knowledge Skills - Infrastructure (6)