{"id":50470311,"url":"https://github.com/yang1bai/claw-tsaver","last_synced_at":"2026-06-01T10:01:44.372Z","repository":{"id":359004386,"uuid":"1221202894","full_name":"Yang1Bai/claw-tsaver","owner":"Yang1Bai","description":"A token-saving MCP proxy for OpenClaw users. Cuts tool call payloads by 90%+ via lazy expansion.","archived":false,"fork":false,"pushed_at":"2026-05-20T00:30:15.000Z","size":75,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T03:30:51.348Z","etag":null,"topics":["mcp","openai","python","token-optimization"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yang1Bai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-25T22:15:27.000Z","updated_at":"2026-05-20T00:30:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Yang1Bai/claw-tsaver","commit_stats":null,"previous_names":["yang1bai/claw-tsaver"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Yang1Bai/claw-tsaver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yang1Bai%2Fclaw-tsaver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yang1Bai%2Fclaw-tsaver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yang1Bai%2Fclaw-tsaver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yang1Bai%2Fclaw-tsaver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yang1Bai","download_url":"https://codeload.github.com/Yang1Bai/claw-tsaver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yang1Bai%2Fclaw-tsaver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33769492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","openai","python","token-optimization"],"created_at":"2026-06-01T10:01:40.690Z","updated_at":"2026-06-01T10:01:44.361Z","avatar_url":"https://github.com/Yang1Bai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claw-tsaver\n\n\u003e A token-saving MCP proxy for OpenClaw users. Cuts tool call payloads by 90%+ via lazy expansion.\n\n## Why\n\nMCP tool calls often return thousands of tokens of HTML or JSON in a single response — but the model typically uses only 5% of it. The remaining 95% silently burns context window and increases cost. claw-tsaver sits between OpenClaw and your downstream MCP servers, intercepts oversized responses, and hands the model a compact preview + an on-demand handle instead.\n\n## How\n\n```mermaid\nsequenceDiagram\n    participant U as OpenClaw (Claude)\n    participant C as claw-tsaver proxy\n    participant F as fetch / puppeteer / etc.\n    U-\u003e\u003eC: call_tool(\"fetch\", url)\n    C-\u003e\u003eF: forward call\n    F--\u003e\u003eC: 11,507 tokens of HTML\n    Note over C: tiktoken count \u003e threshold\n    C-\u003e\u003eC: store full content in SQLite\n    C--\u003e\u003eU: {preview_head, preview_tail, expand_handle}\u003cbr/\u003e(only 104 tokens)\n    Note over U: model decides if it needs full text\n    U-\u003e\u003eC: expand_content(handle)\n    C--\u003e\u003eU: full 11,507 tokens\n```\n\n## Real measurement\n\n| Test | Original tokens | Returned tokens | Saved |\n|---|---|---|---|\n| fetch Wikipedia \"Tokenization (data security)\" | 11,507 | 104 | **99.1%** |\n\nTested on OpenClaw + Claude Sonnet 4.6 + mcp-server-fetch, 2026-04-25.  \nRaw data: `benchmarks/mvp-day1-fetch.jsonl`.\n\n## Quick Start\n\n### 1. Prerequisites\n\nInstall [uv](https://docs.astral.sh/uv/) (one-time setup):\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nNo claw-tsaver install needed — `uvx` will fetch and run it on demand.\n\n### 2. Configure downstream MCP servers\n\nEdit `~/.claw-tsaver/config.json` (first run of `claw-tsaver-mcp` will auto-create a template):\n\n```json\n{\n  \"downstream_servers\": [\n    {\"name\": \"fetch\", \"command\": \"uvx\", \"args\": [\"mcp-server-fetch\"]}\n  ],\n  \"compression_threshold_tokens\": 500\n}\n```\n\n### 3. Register with OpenClaw\n\nAdd this block at the top level of `~/.openclaw/openclaw.json`:\n\n```json\n\"mcp\": {\n  \"servers\": {\n    \"claw-tsaver\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/Yang1Bai/claw-tsaver\",\n               \"claw-tsaver-mcp\"]\n    }\n  }\n}\n```\n\nThen restart OpenClaw gateway: `openclaw gateway restart`\n\n## Dashboard\n\nOptional: a local web UI for real-time token savings stats.\n\n```bash\nuvx --from git+https://github.com/Yang1Bai/claw-tsaver claw-tsaver-dashboard\n```\n\nOpen \u003chttp://localhost:7878\u003e in your browser.\n\n## Roadmap\n\n- [x] **Module A**: lazy expansion proxy (this release)\n- [x] **Module D**: local dashboard (this release)\n- [ ] **Module B**: tool routing (auto-load only relevant MCPs per turn)\n- [ ] **Module C**: conversation history compression (atomic fact cards)\n\n## License\n\nMIT — see LICENSE file.\n\n## Contributing\n\nIssues and PRs welcome.\n\n---\n\n## 🇨🇳 中文说明\n\n### 什么是 claw-tsaver？\n\n**claw-tsaver** 是一个为 OpenClaw 用户设计的 MCP 代理，通过懒加载扩展机制将工具调用的 token 消耗削减 **90%+**。\n\n### 问题背景\n\nMCP 工具调用（如 fetch、puppeteer）经常在单次响应中返回数千个 token 的 HTML 或 JSON，但模型通常只使用其中约 5% 的内容。剩余 95% 悄悄消耗上下文窗口并增加费用。\n\n### 解决方案\n\nclaw-tsaver 作为 OpenClaw 与下游 MCP 服务器之间的代理：\n1. 拦截过大的响应（超过可配置的 token 阈值）\n2. 将完整内容存储到本地 SQLite 数据库\n3. 返回给模型一个**紧凑预览 + 按需扩展句柄**\n4. 模型需要更多内容时，调用 `expand_content` 工具按需获取\n\n### 快速安装\n\n```bash\nnpm install -g claw-tsaver\n# 在 OpenClaw 配置中添加为 MCP 服务器\n```\n\n### 开源协议\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyang1bai%2Fclaw-tsaver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyang1bai%2Fclaw-tsaver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyang1bai%2Fclaw-tsaver/lists"}