Tumiki Proxy

tumiki代理

MCP (Model Context Protocol) 服务器透明记录代理。Claude Code 和后端服务器之间的所有MCP将流量记录在本地文件中，帮助调试和分析。

特徴

• 支持多传输: stdio、HTTP/StreamableHTTP、HTTP/SSEに対応
• 公式SDK使用: @modelcontextprotocol/sdk基于
• 自动回退: StreamableHTTP → SSE自动切换
• 认证对应: HTTP面向基本服务器API密钥支持
• 透过的: MCP不更改协议的零影响包装器
• 効率的：异步缓冲和批处理的最小开销
• 型安全: TypeScript完全实施
• 统一日志格式：在所有传输中NDJSON采用形式

安装

方法1: Homebrew（macOS/Linux - 推奨）

macOS或Linux对于用户Homebrew中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积

# Tapを追加してインストール
brew tap rayven122/tumiki-proxy https://github.com/rayven122/tumiki-proxy
brew install tumiki-proxy

# アップデート
brew update
brew upgrade tumiki-proxy

了解更多信息Homebrew安装指南来修改标记元素的显示属性。

方法2:二进制分发

GitHub的，之Releases从页面下载平台的已构建二进制文件：

# macOS (ARM64)
curl -L -o tumiki-proxy https://github.com/rayven122/tumiki-proxy/releases/latest/download/tumiki-proxy-macos-arm64
chmod +x tumiki-proxy

# macOS (x64)
curl -L -o tumiki-proxy https://github.com/rayven122/tumiki-proxy/releases/latest/download/tumiki-proxy-macos-x64
chmod +x tumiki-proxy

# Linux (x64)
curl -L -o tumiki-proxy https://github.com/rayven122/tumiki-proxy/releases/latest/download/tumiki-proxy-linux-x64
chmod +x tumiki-proxy

# Windows (x64)
# PowerShellで実行:
Invoke-WebRequest -Uri "https://github.com/rayven122/tumiki-proxy/releases/latest/download/tumiki-proxy-win-x64.exe" -OutFile "tumiki-proxy.exe"

方法3:从源构建

Bun使用（建议-独立二进制）

# リポジトリをクローン
git clone https://github.com/rayven122/tumiki-proxy.git
cd tumiki-proxy

# Bunで依存関係のインストールとビルド
bun install
bun run build

# スタンドアロンバイナリの生成
bun run build:binary
# → tumiki-proxy バイナリが生成されます

Node.js使用（传统方法）

# リポジトリをクローン
git clone https://github.com/rayven122/tumiki-proxy.git
cd tumiki-proxy

# 依存関係のインストールとビルド
npm install
npm run build

# Node.js経由で実行
node dist/index.js [args...]

使用方法

stdio 模式（本地MCP服务器）

stdin/stdout 中所述的工具，调整墙的布局和几何形状MCP对于服务器：

# ログファイルの場所を指定
export TUMIKI_LOG_FILE="./mcp-filesystem.log"

# stdioベースのMCPサーバーをプロキシ経由で実行
tumiki-proxy npx -y @modelcontextprotocol/server-filesystem /path/to/dir

SSEStreamable HTTP 模式（远程MCP服务器）

HTTP可通过的远程MCP对于服务器：

export TUMIKI_LOG_FILE="./mcp-context7.log"
export CONTEXT7_API_KEY="your-api-key"  # オプション
tumiki-proxy --http https://mcp.context7.com/mcp

Claude Code 设定

.mcp.json 建议使用文件进行设置。在项目根目录中 .mcp.json 中所述修改相应参数的值。

设定例（.mcp.json）

{
  "mcpServers": {
    "filesystem": {
      "command": "./tumiki-proxy",
      "args": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/dir"
      ],
      "env": {
        "TUMIKI_LOG_FILE": "/tmp/mcp-filesystem.log"
      }
    },
    "context7": {
      "command": "./tumiki-proxy",
      "args": [
        "--http",
        "https://mcp.context7.com/mcp"
      ],
      "env": {
        "TUMIKI_LOG_FILE": "/tmp/mcp-context7.log",
        "CONTEXT7_API_KEY": "your-api-key"
      }
    }
  }
}

注意：使用二进制版本时 ./tumiki-proxy 中所述修改相应参数的值。Node.js使用版本时 node dist/index.js 的command 选项卡页面上创建或编辑条目args 之后由应用程序进行调用。

设定

环境变数

｜变量｜必需｜默认｜说明｜ |----------|----------|---------|-------------| | TUMIKI_LOG_FILE 是，日志文件路径 | TUMIKI_LOG_BUFFER_SIZE 不，不，不，不，不，不，不，不 | TUMIKI_LOG_BATCH_SIZE 不，不，不，不，不，不，不 | TUMIKI_LOG_BATCH_TIMEOUT_MS 否100刷新间隔（毫秒）

认证用环境变量（SSE・Streamable HTTP 模式）

自定义设置示例

export TUMIKI_LOG_FILE="./mcp.log"
export TUMIKI_LOG_BUFFER_SIZE=500
export TUMIKI_LOG_BATCH_SIZE=50
export TUMIKI_LOG_BATCH_TIMEOUT_MS=200

tumiki-proxy your-mcp-server

日志格式

日志换行符JSON（NDJSON）格式：

{"timestamp":"2024-01-15T10:30:00.000Z","type":"request","direction":"client→backend","backendCmd":"npx","message":{"jsonrpc":"2.0","id":1,"method":"tools/list"},"raw":"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}"}
{"timestamp":"2024-01-15T10:30:00.100Z","type":"response","direction":"backend→client","backendCmd":"npx","message":{"jsonrpc":"2.0","id":1,"result":{"tools":[...]}},"raw":"{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"tools\":[...]}}"}
{"timestamp":"2024-01-15T10:30:00.150Z","type":"info","backendCmd":"--http","message":"Connected using StreamableHTTP transport"}

日志条目类型

• request：客户端-后端-MCP服务器）
• response：后端-客户端（MCP服务器-Claude Code）
• stderr：后端错误输出（仅限stdio模式）
• info：代理生命周期事件（启动、退出和连接信息）
• error：代理错误

体系结构

stdio 模式

┌─────────────┐
│ Claude Code │
└──────┬──────┘
       │ stdin/stdout (JSON-RPC)
       ↓
┌────────────────────┐
│  tumiki-proxy      │
│  ┌──────────────┐  │
│  │ FileLogger   │──┼─→ ローカルログファイル (NDJSON)
│  └──────────────┘  │
│  ┌──────────────┐  │
│  │ spawn + pipe │  │
│  └──────────────┘  │
└────────┬───────────┘
         │ stdin/stdout (透過的)
         ↓
┌─────────────────┐
│  MCP Server     │
│  (stdio)        │
└─────────────────┘

SSEStreamable HTTP 模式

┌─────────────┐
│ Claude Code │
└──────┬──────┘
       │ stdin/stdout
       ↓
┌────────────────────┐
│  tumiki-proxy      │
│  ┌──────────────┐  │
│  │ FileLogger   │──┼─→ ローカルログファイル (NDJSON)
│  └──────────────┘  │
│  ┌──────────────┐  │
│  │ Stdio Server │  │
│  │ Transport    │  │
│  └──────────────┘  │
│  ┌──────────────┐  │
│  │StreamableHTTP│  │
│  │/SSE Client   │  │
│  └──────────────┘  │
└────────┬───────────┘
         │ Streamable HTTP/SSE
         ↓
┌─────────────────┐
│  MCP Server     │
│  (HTTP)         │
└─────────────────┘

故障排除

SSEStreamable HTTP 模式连接确认

可以在日志文件中查看传输选择：

# Streamable HTTP が使用された場合
{"type":"info","message":"Connected using StreamableHTTP transport"}

# SSE にフォールバックした場合
{"type":"info","message":"StreamableHTTP connection failed, falling back to SSE transport"}
{"type":"info","message":"Connected using SSE transport"}

HTTP服务器连接错误

症状: MCP服务器failed 状态

诊断和解决方案:

1. API密钥问题（需要认证的服务器时）

- 服务提供商API获取密钥 - 设置适当的环境变量（CONTEXT7_API_KEY、MCP_API_KEY，或 API_KEY） - Claude Code 重新启动

1. 传输连接错误

- 在日志文件中查看详细的错误消息 - StreamableHTTP 和SSE 如果两者都失败，请检查网络连接 - 检查防火墙设置

未创建日志文件

确认事项:

1. TUMIKI_LOG_FILE 是否设置了环境变量
2. 日志文件路径是否具有写权限
3. 日志文件是否已在另一进程中打开

开発

Bun的开发（推荐）

# 依存関係のインストール
bun install

# TypeScriptのビルド
bun run build

# ウォッチモード
bun run dev

# スタンドアロンバイナリの生成
bun run build:binary
# → tumiki-proxy バイナリが生成されます (57MB)
# → Bun runtime込みの完全なスタンドアロン実行ファイル
# → 外部ランタイム不要、高速起動

# ビルド成果物のクリーンアップ
rm -rf dist tumiki-proxy

Node.js使用开发

# 依存関係のインストール
npm install

# TypeScriptのビルド
npm run build

# ウォッチモード
npm run dev

# ビルド成果物のクリーンアップ
rm -rf dist

技术仕样

二进制构建:

• 工具：包1.x
• 尺寸：约57MB (Bun runtime包含）
• 起动时间：\=18.0.0
• 依存关系：@modelcontextprotocol/sdk
• 実行: node dist/index.js

分发

欢迎分享！请随便Pull Request中所述修改相应参数的值。

许可证

MIT License - 了解更多信息LICENSE请参阅文件

将来的路线图

• 云存储协作：针对云存储服务（S3、GCS等）HTTP上传
• 日志查看器：用于查看和分析日志Electron贝斯GUI
• 增强的分析功能: MCP分析流量模式和性能的内置工具
• 包分发：用于更简单的安装NPM发布包