Token Smithers

托肯·史密瑟斯

*“你的背景窗口是一笔财富。别浪费了。”*

Claude Code    Token Smithers (proxy)    Backend MCP Server

你忠诚的助手，象征着效率。Token Smithers位于Claude Code和后端MCP服务器之间，透明地压缩工具模式和结果以减少令牌使用。无需对Claude Code或后端服务器进行任何更改。

像任何一个好助手一样，史密瑟斯默默地做着脏活，并以得体的方式汇报。

适用于任何MCP客户端 --Claude Code、Codex、Cursor、Windsurf、Cline或任何讲MCP协议的东西。不依赖于任何特定的工具。

注： Token Smithers目前支持 stdio MCP服务器 （服务器作为子流程启动）。HTTP/远程MCP服务器（例如，通过URL连接的服务器）尚不受支持。大多数MCP服务器使用stdio——请检查您的配置 "type": "stdio" 或 "command" 条目。 单实例服务器： 一些MCP服务器锁定其数据库，只允许一个运行实例（例如MuninnDB）。由于Token Smithers将后端作为子进程生成，如果另一个实例已经在运行，这些服务器将失败。保持单实例服务器的未包装状态。

我应该包装哪些MCP服务器？

每个MCP服务器都是一个独立的后端。你的AI编码工具会分别与每个人进行通信——它们不会相互共享流量：

                    ┌──→  MCP Server A  (filesystem — raw data)
                    │
Your AI Tool  ──────┼──→  MCP Server B  (GitHub — raw API responses)
                    │
                    ├──→  MCP Server C  (database — query results)
                    │
                    └──→  MCP Server D  (code intelligence — already optimized)

托肯·史密瑟斯包装 一次一台服务器。您可以选择哪些从压缩中受益：

经验法则： 如果MCP服务器转储原始数据，则对其进行包装以节省模式和结果。如果它已经返回了紧凑的结果，那么无论如何都要包装它——你仍然可以节省模式加载的时间，这会在每次加载时发生 tools/list 刷新（每次约5次）。

token-smithers setup 显示所有服务器并允许您进行选择。您始终可以使用撤消 token-smithers setup --undo.

内置工具与MCP服务器

像Claude Code这样的AI编码工具 内置工具 （读取、编辑、Grep、Bash）不通过MCP。令牌Smithers只能压缩MCP服务器流量，而不能压缩内置工具调用。

|工具|类型|令牌史密瑟斯？ | |------|------|:-:| |读取、编辑、Grep、Bash、写入、Glob |内置|--| |文件系统MCP、GitHub MCP、数据库MCP | MCP服务器|是| |已优化的MCP（jCodeMunch、jDocMunch、上下文模式）|MCP服务器|跳过|

如果您使用标准MCP服务器 在返回原始未压缩数据的（文件系统、GitHub、数据库等）中，Token Smithers提供了最大的节省——在所有内容类型中高达62%。

如果您已经在使用优化工具 与jCodeMunch、jDocMunch或上下文模式一样，它们处理了代码读取、文档读取和命令输出的大部分繁重工作。TokenSmithers仍然为那些工具没有涵盖的MCP服务器增加了价值——API服务器（GitHub，EXA）、内存存储（Muninn）、文档提取器（context7），以及您添加的任何未来的MCP服务器。

MCP服务器的节省

根据流行MCP服务器的实际模式和响应进行测量：

每次会话影响

您加载的每个MCP服务器都会消耗令牌 每 tools/list 刷新 --即使你从不调用这些工具。9台MCP服务器（共95个工具，包括已经优化的工具）：

||没有史密瑟斯|有史密瑟斯|得救| |--|--:|--:|--:| |每次工具/列表刷新|~12000个令牌|~5400个令牌| 约6600个代币（55%） | |每次会话（约5次刷新）|~60000个代币|~27000个代币| 约33000个代币 | |+10次工具调用|约110000个代币|约52000个代币| 约5.8万个代币 |

即使是像jCodeMunch（31个工具）这样“已经优化”的MCP服务器，每次刷新也要花费约5350个模式令牌。包装它们仅在模式上就节省了约55%-- 每场约25500个代币 --而不影响其内部结果优化。

MCP服务器越多，每次刷新支付的模式开销就越大，Token Smithers节省的也就越多。

它的作用

运作原理

1. Claude Code调用工具 通过MCP→ Token Smithers收到请求
2. 安全检查：修改工具（写入、删除、创建）总是去后端——从不缓存
3. 缓存检查：对照语义缓存检查只读工具，以获得类似的先前结果
4. 后端呼叫：请求已转发到您的后端MCP服务器
5. 压缩管路：结果通过适配器链传递（清理→ 特定内容→ 安全网）
6. 响应：压缩结果返回给Claude Code
7. 学习：记录使用统计数据和压缩事件以进行跨会话优化

基准测试

通过完整的11个适配器管道，在12种内容类型中测量，每种类型有3种大小。 总计：输入192K代币，输出73K——节省62%。

管道延迟： 0.05-11毫秒 这取决于内容大小。典型的MCP工具调用需要50-500ms，因此Token Smithers补充道 低于1%的管理费用.

Why so fast

• 纯字符串操作、正则表达式和JSON解析/序列化——无ML，无GPU
• 内容感知路由跳过不相关的适配器
• 小结果（\

Reproduce these benchmarks

python scripts/benchmark_all.py

需求

• Python 3.11+
• 后端MCP服务器 --Token Smithers将代理的任何MCP兼容服务器（例如，文件系统、GitHub、数据库或自定义服务器）

安装

macOS/Linux：

pip install "token-smithers[learning] @ git+https://github.com/shacharbard/token-smithers.git@stable"

或与 pipx （隔离，无需静脉）：

pipx install "token-smithers[learning] @ git+https://github.com/shacharbard/token-smithers.git@stable"

Windows（PowerShell）：

pip install "token-smithers[learning] @ git+https://github.com/shacharbard/token-smithers.git@stable"

就是这样 token-smithers 命令现在全球可用。

Alternative: clone and install

git clone https://github.com/shacharbard/token-smithers.git
cd token-smithers
pip install ".[learning]"

Optional extras

核心依赖关系 （始终安装）： mcp>=1.0.0, pyyaml>=6.0, pydantic>=2.0

For contributors

git clone https://github.com/shacharbard/token-smithers.git
cd token-smithers
pip install -e ".[dev]"

快速开始

运行的三个命令：

pip install "token-smithers[learning] @ git+https://github.com/shacharbard/token-smithers.git@stable"
token-smithers setup                      # Pick which MCP servers to compress
# ... use your AI coding tool normally ...
token-smithers stats                      # Check your savings

自动设置

setup命令可以找到现有的MCP服务器，并允许您选择要压缩的服务器。

token-smithers setup

Found 2 MCP config files:

  Global (~/.claude.json): 3 servers
    1. github        npx -y @modelcontextprotocol/server-github
    2. slack         npx -y @anthropic/server-slack
    3. memory        npx -y @modelcontextprotocol/server-memory

  Project (.mcp.json): 2 servers
    4. filesystem    npx -y @modelcontextprotocol/server-filesystem .
    5. my-database   my-db-server --port 5432

Which servers should token-smithers compress? (comma-separated, or 'all')
> 1,4,5

就是这样。托克·史密瑟斯：

• 在中为每台服务器创建配置文件 ~/.token-smithers/configs/
• 更新您的MCP配置以通过Token Smithers路由
• 将原件备份到 .mcp.json.backup / ~/.claude.json.backup

安装程序扫描两个配置位置：

• 项目级别： .mcp.json 在当前目录中
• 用户级别： ~/.claude.json （所有项目中都有全局服务器）

撤消设置

要删除令牌Smithers并恢复原始MCP服务器连接，请执行以下操作：

token-smithers setup --undo

Unwrapping 3 servers:
  github        → restored to: npx -y @modelcontextprotocol/server-github
  filesystem    → restored to: npx -y @modelcontextprotocol/server-filesystem .
  my-database   → restored to: my-db-server --port 5432

Updated:
  ~/.claude.json — 1 server restored
  .mcp.json      — 2 servers restored

这将读取生成的YAML配置以恢复原始命令，并将MCP配置重写回直接连接。您的备份文件将被保留。

检查你的储蓄

token-smithers stats

  "Excellent..."

  === Token Smithers — Session Stats ===
  Events:     142
  Original:   284,000 tokens
  Compressed: 156,200 tokens
  Saved:      127,800 tokens (45.0%)

  Smithers, we saved 127,800 tokens. Not a single one squandered.

  === Per-Strategy Breakdown ===
  Strategy                        Count   Original Compressed
  ------------------------------ ------ ---------- ----------
  whitespace_normalizer              142     284000     241400
  toon_compressor                     38     120000      54000
  yaml_transcoder                     67      98000      73500
  smart_truncation                    12      42000      28700

状态行

在终端状态栏中查看实时代币节省：

token-smithers status-line

Smithers: 1.2M (42%) | today: 52.0K (38%)     # green when >= 40%
Smithers: 340.5K (23%) | today: 12.1K (19%)   # blue when >= 20%
Smithers: 8.2K (6%) | today: 1.4K (5%)        # red when  columnar format
    - name: yaml_transcoder         # Non-tabular JSON -> YAML
    - name: file_redirect           # Oversized results -> temp file
      enabled: false
    - name: smart_truncation        # Safety net (always last)

# Schema virtualization (DietMCP-style)
schema_virtualization:
  enabled: false                    # Enable to compress tool schemas
  tier: 2                           # 1=lossless, 2=brief descriptions, 3=one-liner notation
  frequent_call_threshold: 3        # Tools called >= N times stay at Tier 1

# Semantic result caching
semantic_cache:
  enabled: false                    # Enable for similarity-based result caching
  similarity_threshold: 0.85        # 0.0-1.0, higher = stricter matching
  max_entries: 1000
  ttl_seconds: 86400                # Cache entry lifetime (null = no expiry)

# Cross-session learning
learning:
  enabled: true                     # SQLite persistence for usage stats + caching
  db_path: "~/.token-smithers/learning.db"

# Dashboard / metrics
dashboard:
  enabled: true
  metrics_file_path: "~/.token-smithers/metrics.json"

# System prompt optimization
system_prompt:
  enabled: true
  compress_instructions: true       # Compress backend server instructions at startup

# Statistical reranker
reranker:
  enabled: true                     # Reorder tools/list by usage frequency
  max_tools: 500
  recency_weight: 0.3

# Caching
cache:
  schema_cache_ttl: 3600            # Tools/list cache TTL (seconds)
  call_cache_max: 200               # Max exact-match cached results
  diff_store_max: 100               # Max semantic diff entries

# Observability
observability:
  metrics_to_stderr: true           # Emit [Token Smithers] log lines per compression event
  log_level: "INFO"

适配器管道

压缩适配器按顺序运行。每个适配器决定它是否可以处理内容(can_handle)，如果是这样，则对其进行压缩。结果将通过整个管道。

建筑

src/token_sieve/
  domain/          # Pure Python domain core (zero external deps)
    model.py       #   ContentEnvelope, CompressionEvent, value objects
    ports.py       #   CompressionStrategy, DeduplicationStrategy protocols
    pipeline.py    #   CompressionPipeline service
    ports_cache.py #   SemanticCachePort protocol
    ports_learning.py # LearningStore protocol
    ports_schema.py   # SchemaVirtualizerPort protocol
    metrics.py     #   InMemoryMetricsCollector
  adapters/        # Implementations (external deps allowed)
    compression/   #   17 compression strategy adapters
    cache/         #   Call cache, semantic cache, invalidation, schema cache
    backend/       #   MCP client transport + connector
    learning/      #   SQLite learning store
    schema/        #   Schema virtualizer (DietMCP notation)
    rerank/        #   Statistical reranker + persistence
    dedup/         #   Window-based deduplication
  server/          # MCP proxy server
    proxy.py       #   ProxyServer (MCP handlers, dependency wiring)
    metrics_sink.py #  Stderr metrics formatter
    metrics_writer.py # Periodic JSON metrics file writer
    tool_filter.py #   Allowlist/blocklist tool filtering
  config/          # YAML config loading + Pydantic validation
  cli/             # CLI entry point (proxy, pipe, stats modes)

采用DDD原理的六边形架构（端口和适配器）。域核心没有外部依赖关系——所有I/O都通过协议接口。

用法示例

代理文件系统服务器

# Token Smithers.yaml
backend:
  command: "npx"
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

具有主动压缩功能的代理

backend:
  command: "npx"
  args: ["-y", "@modelcontextprotocol/server-filesystem", "."]

compression:
  adapters:
    - name: whitespace_normalizer
    - name: null_field_elider
    - name: path_prefix_deduplicator
    - name: timestamp_normalizer
    - name: log_level_filter
      enabled: true                  # Enable log filtering
    - name: code_comment_stripper
      enabled: true                  # Strip code comments
    - name: sentence_scorer
      enabled: true                  # Requires 'prose' extra
    - name: rle_encoder
    - name: toon_compressor
    - name: yaml_transcoder
    - name: smart_truncation

schema_virtualization:
  enabled: true
  tier: 3                            # DietMCP one-liner notation

semantic_cache:
  enabled: true                      # Cache similar read results
  similarity_threshold: 0.90         # Strict matching

筛选工具

backend:
  command: "my-mcp-server"

filter:
  mode: "blocklist"
  tools: ["dangerous_tool"]
  patterns: ["^internal_.*"]          # Regex: block tools starting with "internal_"

管道模式（独立压缩）

# Compress a file directly (no MCP server needed)
cat large-output.json | token-smithers --pipe

# Compress from file
token-smithers --pipe input.txt

发展

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov

# Run integration tests only
pytest -m integration

# Run benchmarks
pytest -m benchmark

测试统计数据

• 950+次测试
• 91.8%的覆盖率
• 单元/集成/E2E/合同/金文件测试金字塔

安全

Token Smithers在您的计算机上本地运行。它从不向外部服务发送数据。

看 安全.md 了解完整信任模型、漏洞报告和审计详细信息。

# Run security checks yourself
pip install bandit pip-audit
bandit -r src/token_sieve/ -ll    # Static analysis
pip-audit                          # Dependency vulnerabilities

致谢

Token Smithers的灵感来自并建立在以下想法之上：

• DietMCP --开创了DietMCP单线符号(tool(param, ?opt) desc)用于模式压缩和类型省略。Token Smithers的Tier 3模式虚拟化通过频率感知层选择实现了这种表示法。

许可证

麻省理工学院