Tonl MCP Bridge

TONL-MCP电桥

使用TONL格式将LLM令牌成本降低40-60%（针对高容量日志和重复数据结构进行了优化）

](https://www.npmjs.com/package/tonl-mcp-bridge) ](https://www.npmjs.com/package/tonl-mcp-bridge)   

概述

TONL-MCP Bridge是一个生产级TypeScript库和CLI工具，可将JSON/YAML数据转换为TONL（令牌优化自然语言）格式。通过消除JSON的结构开销，TONL减少了大型语言模型上下文窗口的令牌使用，从而直接降低了成本并提高了性能。

主要用例

• RAG系统：优化检索增强生成管道
• 矢量数据库：减少Milvus、Qdrant和ChromaDB查询的令牌开销
• MCP服务器：构建高效的模型上下文协议集成
• 实时流媒体：具有恒定内存的进程日志和事件流
• 企业合规性：GDPR/HIPAA就绪数据匿名化

当TONL表现出色时

✅ 表格/结构化数据 （日志、事件、分析）\ ✅ 重复的字段结构 （API响应、数据库查询）\ ✅ 大型数据集 （100+条记录，模式一致）\ ✅ 高场密度 （每条记录>10个字段）

何时使用JSON

❌ 单对象转换 （标题开销>节省）\ ❌ 高度异构的数据 （许多可选字段导致稀疏表）\ ❌ 深巢树木 （具有复杂层次结构的配置文件）\ ❌ 小型有效载荷 （\ 专业提示： 为了最大限度地节省成本，对具有重复、冗长键的数据使用TONL（例如。， http_request_duration_ms, kubernetes_pod_name_identifier).对于原始文本繁重的负载，标准JSON或Markdown就足够了。

为什么会有变化？

• 企业日志 在数千条记录中重复15个以上的详细字段名
• 表格数据 具有适中的字段名（5-10个字段）和简单的值
• RAG文件 内容繁重，结构\<总令牌的10%

现实世界影响

示例：中型测井基础设施

*基于GPT-4o的定价（截至2025年12月，每100万输入代币2.50美元）*

脚本： 云可观察性平台处理Kubernetes日志

• 100000个日志事件/天
• 每个事件15个字段（详细键如 distributed_trace_correlation_id)
• JSON有效载荷：每个事件约170个令牌

之前（JSON）：

• 每日代币：1700万代币（10万×170）
• 每日费用：42.50美元（2.50美元×17美元）
• 每月费用：约1275美元

之后（吨减少47%）：

• 每日代币：900万代币（10万×90）
• 每日费用：22.50美元（2.50美元×9）
• 每月费用：约675美元
• 每月节省：600美元

在1M事件/天的规模下： 每月节省6000美元

*运行自己的基准测试： npm run benchmark （参见 基准测试/README.md)*

主要特点

核心功能

双向转换

• JSON转换为TONL并返回（无损）
• YAML到TONL并返回
• 自动模式检测
• 智能报价（仅在必要时）

类型系统

• 优化的数字类型（i8、i16、i32、f32）
• 原生支持字符串、布尔值、null
• 通过点符号处理嵌套对象
• 数组类型保存

生产特性（v1.0.0）

流媒体管道

• 使用恒定内存处理千兆字节级文件
• 250000行/秒吞吐量（在M1 MacBook Pro上测量，100字节行）
• 用于NDJSON到TONL转换的HTTP端点
• 背压处理和错误恢复

隐私与合规

• 智能屏蔽（电子邮件、SSN、信用卡、电话）
• 嵌套字段匿名化
• GDPR/HIPAA合规支持
• 可配置的编辑策略

可观测性

• 普罗米修斯指标（业务和运营）
• 实时监控仪表板(tonl top 命令）
• Kubernetes的健康检查端点
• Grafana仪表板模板

安全

• 速率限制（可按IP配置）
• 头盔安全头
• 承载令牌身份验证（或自动生成的会话令牌）
• 优雅的关机，连接排水

矢量数据库集成

本机适配器适用于：

• 米尔维斯：搜索结果的自动TONL转换
• Qdrant：优化查询格式
• ChromaDB：集合发现和相似性搜索

每个适配器都包含内置的令牌统计信息和节省计算。

限制和边缘案例

稀疏数据/联合模式

当记录具有不同的字段时，TONL使用联合模式：

// Heterogeneous data
const data = [
  { type: "user", name: "Alice", age: 30 },
  { type: "product", name: "Widget", price: 9.99 }
];

// TONL handles via union schema
// @items|type:s,name:s,age:n?,price:n?
// user|Alice|30|null
// product|Widget|null|9.99

• 标记为的可选字段 ? 后缀
• 缺失值表示为 null
• 代币节省减少，但仍然存在（通常为20-30%）

性能注意事项

• 模式推理开销： 第一批约1-2ms
• 类型检测成本： 混合类型字段增加
• 标题大小： 与字段数成比例（10个字段≈50个令牌）
• 内存： 无论文件大小如何，都会持续使用

有关完整的技术细节，请参阅 限制.md

安装

CLI工具（全局）

npm install -g tonl-mcp-bridge

图书馆（本地项目）

npm install tonl-mcp-bridge

MCP服务器

stdio模式（适用于克劳德桌面）：

npm install -g tonl-mcp-bridge

# Configure in claude_desktop_config.json:
# {
#   "mcpServers": {
#     "tonl": {
#       "command": "npx",
#       "args": ["-y", "tonl-mcp-stdio"]
#     }
#   }
# }

HTTP/SSE模式（用于远程/Docker）：

# With permanent token (production)
export TONL_AUTH_TOKEN=your-secure-token
npx tonl-mcp-server

# Without token (development)
# Server auto-generates session tokens (valid for 1 hour)
npx tonl-mcp-server

码头工人

docker run -d \
  -p 3000:3000 \
  -e TONL_AUTH_TOKEN=your-token \
  ghcr.io/kryptomrx/tonl-mcp-bridge:latest

# Verify health
curl http://localhost:3000/health

快速开始

CLI使用情况

# Basic conversion
tonl convert data.json

# With token statistics
tonl convert data.json -s

# Show all commands
tonl help

# Monitor server metrics
tonl top --url https://your-server.com

# Convert with anonymization
tonl convert users.json --anonymize email,ssn

程序化使用

import { jsonToTonl, tonlToJson } from 'tonl-mcp-bridge';

// Convert to TONL
const data = [
  { id: 1, name: "Alice", age: 25 },
  { id: 2, name: "Bob", age: 30 }
];

const tonl = jsonToTonl(data, "users");
// users[2]{id:i32,name:str,age:i32}:
//   1, Alice, 25
//   2, Bob, 30

// Convert back to JSON
const json = tonlToJson(tonl);

流媒体

import { pipeline } from 'stream/promises';
import { NdjsonParse, TonlTransform } from 'tonl-mcp-bridge/streams';
import { createReadStream, createWriteStream } from 'fs';

await pipeline(
  createReadStream('logs.ndjson'),
  new NdjsonParse(),
  new TonlTransform({ collectionName: 'logs' }),
  createWriteStream('logs.tonl')
);

隐私和匿名

import { jsonToTonl } from 'tonl-mcp-bridge';

const users = [
  { 
    id: 1, 
    name: 'Alice', 
    email: 'alice@company.com',
    ssn: '123-45-6789' 
  }
];

// Smart masking (preserves format context)
const masked = jsonToTonl(users, 'users', {
  anonymize: ['email', 'ssn'],
  mask: true
});
// Output: a***@company.com, ***-**-6789

// Simple redaction
const redacted = jsonToTonl(users, 'users', {
  anonymize: ['email', 'ssn']
});
// Output: [REDACTED], [REDACTED]

建筑

组件

核心库

• 类型检测和优化
• 模式推理
• 双向转换引擎
• 使用js-tiktoken进行令牌计数

流媒体管道

• 具有错误恢复功能的NDJSON解析器
• 转换流以进行转换
• 用于远程处理的HTTP端点

隐私模块

• 基于模式的场检测
• 可配置的屏蔽策略
• 深度克隆（无副作用）
• 嵌套对象支持

可观测性

• Prometheus指标集合
• 实时仪表盘
• 健康终点
• 平滑关闭

技术栈

• 运行时：Node.js 18+
• 语言：TypeScript 5.3
• 测试：Vitest（385项测试通过）
• HTTP框架：快递5
• 安全：头盔，快递费率限制
• 指标：舞会客户
• 分词器：js tiktoken（gpt-4或toknizer）
• 协议：MCP、SSE、HTTP

生产部署

码头工人

# docker-compose.yml
version: '3.8'
services:
  tonl-server:
    image: ghcr.io/kryptomrx/tonl-mcp-bridge:latest
    ports:
      - "3000:3000"
    environment:
      - TONL_AUTH_TOKEN=${TONL_AUTH_TOKEN}
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tonl-mcp-bridge
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: tonl-server
        image: ghcr.io/kryptomrx/tonl-mcp-bridge:latest
        ports:
        - containerPort: 3000
        env:
        - name: TONL_AUTH_TOKEN
          valueFrom:
            secretKeyRef:
              name: tonl-secrets
              key: auth-token
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 10

文档

综合文件可在 tonl-mcp-bridge-docs.vercel.app

指南

• 入门指南
• 命令参考
• 流媒体
• 隐私与合规
• 实时监控
• MCP服务器
• 矢量数据库

api参考

• 核心api
• 流式API
• 隐私API
• 服务器应用程序接口

发展

# Clone repository
git clone https://github.com/kryptomrx/tonl-mcp-bridge.git
cd tonl-mcp-bridge

# Install dependencies
npm install

# Run tests (385 passing)
npm test

# Build
npm run build

# Run local server
npm run mcp:start

路线图

已完成（v1.0.0）

• 具有类型优化的核心转换引擎
• MCP服务器与自动生成的会话令牌集成
• 矢量数据库适配器（Milvus、Qdrant、ChromaDB）
• 流媒体管道（250k线/秒）
• 智能屏蔽的隐私和匿名化
• 生产可观察性（普罗米修斯、健康检查）
• 安全（限速、安全帽、优雅关机）
• 全面的CLI tonl help 命令

计划中（发布v1.0.0）

• LangChain集成
• LlamaIdex插件
• VS代码扩展
• 无服务器部署模板（AWS Lambda、Cloudflare Workers）
• 附加矢量数据库适配器（Pinecone、Weaviate）

查看详细路线图

贡献

欢迎捐款。请通过GitHub提交问题和拉取请求。

1. 分叉存储库
2. 创建要素分支
3. 提交您的更改
4. 推到分支
5. 打开拉取请求

许可证

MIT许可证-请参阅 许可证 详情

链接

• npm: https://www.npmjs.com/package/tonl-mcp-bridge
• GitHub: https://github.com/kryptomrx/tonl-mcp-bridge
• 文档: https://tonl-mcp-bridge-docs.vercel.app/
• 命令: https://github.com/kryptomrx/tonl-mcp-bridge/blob/main/COMMANDS.md
• 问题: https://github.com/kryptomrx/tonl-mcp-bridge/issues

______________________________________________________________________

*定价信息已于2025年12月11日验证。基于GPT-4o令牌化器（js tiktoken）的令牌计算。基准数据来自 基准测试/README.md.*

由厌倦了为JSON的冗长付费的开发人员构建。如果这为您的组织节省了资金，请考虑在GitHub上展示该项目。