STARWARCLOUD STARWAR.AI
返回市场
图米基代理

图米基代理

作者：rayven1222 星标更新：2025-10-28
安装使用来源：spider==github.com

项目介绍

tumiki-proxy

MCP (模型上下文协议) 服务器的透明日志代理。记录Claude Code 和后端服务器之间所有的MCP流量到本地文件，以支持调试和分析。

特征

  • 多传输支持: 支持 stdio、HTTP/可流式传输HTTP、HTTP/SSE
  • 官方SDK使用: 基于 @modelcontextprotocol/sdk 构建
  • 自动回退: 自动从可流式传输HTTP切换到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服务器）

当与本地MCP服务器通过stdin/stdout通信时：

# 指定日志文件的位置
export TUMIKI_LOG_FILE="./mcp-filesystem.log"

# 通过代理运行基于stdio的MCP服务器
tumiki-proxy npx -y @modelcontextprotocol/server-filesystem /path/to/dir

SSE·可流式传输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 作为命令，并将实际命令放在args的第一个位置。

设置

环境变量

变量必需默认值描述
TUMIKI_LOG_FILE是-日志文件的路径
TUMIKI_LOG_BUFFER_SIZE否1000在丢弃前队列中的最大条目数
TUMIKI_LOG_BATCH_SIZE否100达到此大小后刷新
TUMIKI_LOG_BATCH_TIMEOUT_MS否100刷新间隔（毫秒）

认证环境变量（SSE·可流式传输HTTP模式）

变量描述
CONTEXT7_API_KEYContext7专用API密钥
MCP_API_KEY通用MCP API密钥
API_KEY回退用API密钥

自定义设置示例

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: 客户端 → 后端（Claude Code → 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)        │
└─────────────────┘

SSE·可流式传输HTTP 模式

┌─────────────┐
│ Claude Code │
└──────┬──────┘
       │ stdin/stdout
       ↓
┌────────────────────┐
│  tumiki-proxy      │
│  ┌──────────────┐  │
│  │ FileLogger   │──┼─→ 本地日志文件 (NDJSON)
│  └──────────────┘  │
│  ┌──────────────┐  │
│  │ Stdio Server │  │
│  │ Transport    │  │
│  └──────────────┘  │
│  ┌──────────────┐  │
│  │StreamableHTTP│  │
│  │/SSE Client   │  │
│  └──────────────┘  │
└────────┬───────────┘
         │ Streamable HTTP/SSE
         ↓
┌─────────────────┐
│  MCP Server     │
│  (HTTP)         │
└─────────────────┘

故障排除

SSE·可流式传输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服务器处于失败状态

诊断与解决办法:

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

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

  2. 传输连接错误

    • 查看日志文件中的详细错误消息
    • 如果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运行时的完整独立可执行文件
# → 不需要外部运行时，快速启动

# 清理构建产物
rm -rf dist tumiki-proxy

使用Node.js进行开发

# 安装依赖
npm install

# 编译TypeScript
npm run build

# 监控模式
npm run dev

# 清理构建产物
rm -rf dist

技术规格

二进制构建:

  • 工具: Bun 1.x
  • 大小: 约57MB (包含Bun运行时)
  • 启动时间: 小于100ms
  • 兼容性: macOS (x64/ARM64), Linux (x64), Windows (x64)
  • 依赖: 无（完全独立）

Node.js版本:

  • 要求: Node.js >= 18.0.0
  • 依赖: @modelcontextprotocol/sdk
  • 执行: node dist/index.js

贡献

欢迎贡献！请随意提交Pull Request。

许可证

MIT License - 详情请参阅LICENSE文件

未来路线图

  • 云存储集成: 将HTTP上传至云存储服务（如S3、GCS等）
  • 日志查看器: 基于Electron的GUI，用于显示和分析日志
  • 增强分析功能: 内置工具，用于分析MCP流量模式和性能
  • 包发布: 发布NPM包，以便更简单的安装