diff --git a/README.md b/README.md index e4de615..e65474f 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,7 @@ Install or disable them dynamically with the `/plugin` command — enabling you - [debug-session](./plugins/debug-session) - [debugger](./plugins/debugger) - [double-check](./plugins/double-check) +- [gcf-proxy](./plugins/gcf-proxy) - [optimize](./plugins/optimize) - [performance-benchmarker](./plugins/performance-benchmarker) - [refractor](./plugins/refractor) diff --git a/plugins/gcf-proxy/.claude-plugin/plugin.json b/plugins/gcf-proxy/.claude-plugin/plugin.json new file mode 100644 index 0000000..700275b --- /dev/null +++ b/plugins/gcf-proxy/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "gcf-proxy", + "description": "Save 71% on MCP tool call tokens. Wraps any MCP server with GCF encoding, zero code changes.", + "version": "1.0.0", + "author": { + "name": "Blackwell Systems", + "url": "https://blackwell-systems.com" + }, + "homepage": "https://gcformat.com", + "repository": "https://github.com/blackwell-systems/gcf-claude-plugin", + "license": "MIT" +} diff --git a/plugins/gcf-proxy/hooks/hooks.json b/plugins/gcf-proxy/hooks/hooks.json new file mode 100644 index 0000000..e5ce3f0 --- /dev/null +++ b/plugins/gcf-proxy/hooks/hooks.json @@ -0,0 +1,14 @@ +{ + "hooks": [ + { + "event": "SessionStart", + "command": "rm -f /tmp/gcf-proxy-stats.json", + "timeout": 1000 + }, + { + "event": "Stop", + "command": "node -e \"const fs=require('fs'); try{const d=JSON.parse(fs.readFileSync('/tmp/gcf-proxy-stats.json','utf8')); if(d.calls>0){const s=d.pct_saved.toFixed(0); const tb=d.est_tokens_saved; const saved=tb>=1000?(tb/1000).toFixed(1)+'K':tb; console.log(JSON.stringify({notification:'gcf-proxy: '+d.calls+' tool calls rewritten, '+s+'% fewer tokens (~'+saved+' tokens saved)'}))}}catch(e){}\"", + "timeout": 1000 + } + ] +} diff --git a/plugins/gcf-proxy/skills/setup/SKILL.md b/plugins/gcf-proxy/skills/setup/SKILL.md new file mode 100644 index 0000000..04ee48b --- /dev/null +++ b/plugins/gcf-proxy/skills/setup/SKILL.md @@ -0,0 +1,53 @@ +--- +description: Wrap an existing MCP server with gcf-proxy to reduce token costs by 71%. Provide the server name from your MCP config. +--- + +# GCF Proxy Setup + +The user wants to wrap an MCP server with gcf-proxy to reduce token costs. + +## What to do + +1. Read the user's MCP configuration (`.mcp.json` in the project or `~/.claude.json`) to find the target server. +2. If `$ARGUMENTS` is provided, find the server matching that name. +3. Create a new entry that wraps the original server with gcf-proxy: + - Keep the original server entry (renamed with a `-raw` suffix, disabled) so the user can revert. + - The new entry prepends gcf-proxy before the original command: `npx -y @blackwell-systems/gcf-proxy@latest --stats-file /tmp/gcf-proxy-stats.json ` +4. Show the user what changed and explain the expected savings (71% fewer tokens on tool responses). + +## Example + +If the user has: +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"] + } + } +} +``` + +Transform it to: +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@blackwell-systems/gcf-proxy@latest", "--stats-file", "/tmp/gcf-proxy-stats.json", "npx", "-y", "@modelcontextprotocol/server-github"] + }, + "github-raw": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "disabled": true + } + } +} +``` + +## Important +- Do NOT use `--` between gcf-proxy and the server command. gcf-proxy takes the server command directly as positional arguments. +- Always preserve the original server config so the user can revert. +- If the server already uses gcf-proxy, tell the user it's already wrapped. +- Environment variables from the original config must be preserved. diff --git a/plugins/gcf-proxy/skills/stats/SKILL.md b/plugins/gcf-proxy/skills/stats/SKILL.md new file mode 100644 index 0000000..6e03bd6 --- /dev/null +++ b/plugins/gcf-proxy/skills/stats/SKILL.md @@ -0,0 +1,21 @@ +--- +description: Show GCF proxy token savings statistics for the current session or overall usage. +--- + +# GCF Stats + +Show the user their gcf-proxy token savings. + +Run `npx -y @blackwell-systems/gcf-proxy@latest --stats` to retrieve session statistics. + +If that command is not available or returns no data, explain that gcf-proxy tracks savings in real time when running with `--verbose` and suggest: + +```bash +npx -y @blackwell-systems/gcf-proxy@latest --verbose -- +``` + +Present any stats in a clear format showing: +- Tokens saved (GCF vs JSON) +- Percentage reduction +- Session deduplication savings (if multi-call session) +- Estimated cost savings based on their model's pricing