mcpison 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# mcpison - MCP to ISON Transport Proxy
+
+`mcpison` 是一个透明的 MCP (Model Context Protocol) 传输层拦截代理。它可以将现有的 MCP Server (如返回包含庞大 JSON 数据的 `tools/call` 强结构) 的标准输出，实时转换为极端轻量级的 **ISON 格式**，大幅节约向大语言模型传输的 Token，且**无需修改任何原本的 MCP Server 代码**。
+
+## 核心特性
+
+- **零侵入性**：直接包装现有的启动命令，无需向你的代码中引入任何依赖。
+- **动态转换**：自动监听 MCP 特有的标准输入/输出流，解析 `tools/call` 并在响应时替换 JSON `text` 内容。
+- **Token 节约**：借助 [ISON-format](https://github.com/ISON-format/ison)，可以有效减少 JSON 在结构封套上浪费的无用 Token。
+
+## 安装
+
+可以通过全局安装此代理（或如果你已经将其构建）：
+
+```bash
+npm install -g mcpison
+```
+
+*(或者在项目本地通过 `npm link` 建立全局命令以供测试)*
+
+## 使用方式
+
+只需在你当前使用的 MCP Client 配置文件（例如 Claude Desktop 的 `claude_desktop_config.json` 或 Cursor 的相关配置）中，在现有的 server 命令前垫加一层 `mcpison`：
+
+### 原始配置
+
+```json
+"mcpServers": {
+  "my-sql-server": {
+    "command": "node",
+    "args": ["/path/to/sql-server.js"]
+  }
+}
+```
+
+### 修改后配置 (加入了 `mcpison`)
+
+```json
+"mcpServers": {
+  "my-sql-server": {
+    "command": "mcpison",
+    "args": ["node", "/path/to/sql-server.js"]
+  }
+}
+```
+
+> **注意：** `mcpison` 之后的内容就是你原本需要执行的子进程以及它需要的参数。
+
+## 调试模式 (Debug)
+
+如果你想要查看你具体节省了多少字节，可以加上 `--debug` 标志。
+
+```json
+"mcpServers": {
+  "my-sql-server": {
+    "command": "mcpison",
+    "args": ["--debug", "node", "/path/to/sql-server.js"]
+  }
+}
+```
+
+MCP Client 的日志中（通常通过 `stderr` 重定向）可以实时打印如下信息：
+
+```
+[mcpison DEBUG] Request ID 1001 Optimized: 395 bytes -> 240 bytes (Saved ~155 bytes)
+```
+
+
+## 测试
+
+```bash
+node test/run-test.js
+```
+该测试会启动一个 Mock MCP Server，并向其发送 `tools/call` 以证明响应内容被正确转为了 ISON 格式。

package/bin/mcpison.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const readline = require('readline');
+const { jsonToISON } = require('ison-parser');
+
+// 提取专属参数并保留传递给子进程的参数
+const args = process.argv.slice(2);
+let isDebug = false;
+
+const spawnArgs = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--debug') {
+    isDebug = true;
+  } else {
+    spawnArgs.push(args[i]);
+  }
+}
+
+if (spawnArgs.length === 0) {
+  console.error("Usage: mcpison [--debug] <command> [args...]");
+  process.exit(1);
+}
+
+const command = spawnArgs[0];
+const commandArgs = spawnArgs.slice(1);
+
+// 启动底层 MCP Server 子进程
+const child = spawn(command, commandArgs, {
+  stdio: ['pipe', 'pipe', 'inherit'] // 将 stderr 直接透传给父进程
+});
+
+child.on('error', (err) => {
+  console.error(`Failed to start child process: ${err.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  process.exit(code || Number(Boolean(signal)));
+});
+
+// 使用 readline 逐行处理 stdin (Client -> Proxy -> Server)
+const rlStdin = readline.createInterface({
+  input: process.stdin,
+  output: null,
+  terminal: false
+});
+
+// 记录所有 Client 发送过来的 "tools/call" 请求的 ID
+const pendingCallToolIds = new Set();
+
+rlStdin.on('line', (line) => {
+  if (!line.trim()) return;
+
+  try {
+    const req = JSON.parse(line);
+    // 拦截识别 tools/call
+    if (req.method === 'tools/call' && req.id !== undefined) {
+      pendingCallToolIds.add(req.id);
+    }
+  } catch (err) {
+    // 不是合法 JSON，忽略
+  }
+
+  // 将请求原样转发给子进程
+  child.stdin.write(line + '\n');
+});
+
+rlStdin.on('close', () => {
+  child.stdin.end();
+});
+
+// 使用 readline 逐行处理 stdout (Server -> Proxy -> Client)
+const rlStdout = readline.createInterface({
+  input: child.stdout,
+  output: null,
+  terminal: false
+});
+
+rlStdout.on('line', (line) => {
+  if (!line.trim()) {
+    process.stdout.write(line + '\n');
+    return;
+  }
+
+  try {
+    const res = JSON.parse(line);
+
+    // 检查是否是我们追踪的 call_tool 响应
+    if (res.id !== undefined && res.result && res.result.content && Array.isArray(res.result.content)) {
+      if (pendingCallToolIds.has(res.id)) {
+        // 这是 call_tool 响应，拦截并转换其中的 JSON text
+        let tokenSaved = 0;
+        let origLength = 0;
+        let newLength = 0;
+
+        for (let i = 0; i < res.result.content.length; i++) {
+          const item = res.result.content[i];
+          if (item.type === 'text' && typeof item.text === 'string') {
+            try {
+              // 尝试将里面的文本解析为 JSON 以便验证它确实是 JSON 数据
+              JSON.parse(item.text); // 进行验证
+              const isonStr = jsonToISON(item.text);
+
+              if (isDebug) {
+                origLength += item.text.length;
+                newLength += isonStr.length;
+                tokenSaved += (item.text.length - isonStr.length);
+              }
+
+              // 替换文本为 ISON
+              item.text = isonStr;
+            } catch (innerErr) {
+              // 内部文本不是标准 JSON，或者是简单的 String，不作转换
+            }
+          }
+        }
+
+        // 移除已经响应的请求 ID
+        pendingCallToolIds.delete(res.id);
+
+        if (isDebug && tokenSaved > 0) {
+          console.error(`[mcpison DEBUG] Request ID ${res.id} Optimized: ${origLength} bytes -> ${newLength} bytes (Saved ~${tokenSaved} bytes)`);
+        }
+
+        // 修改完后，将整个 JSON-RPC 对象重新序列化输出到 Client
+        process.stdout.write(JSON.stringify(res) + '\n');
+        return;
+      }
+    }
+
+    // 其他情况或者未命中的响应，原样输出
+    process.stdout.write(line + '\n');
+
+  } catch (err) {
+    // 解析失败（比如它输出了些非 JSON 调试信息），安全地将其原样透传
+    process.stdout.write(line + '\n');
+  }
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "mcpison",
+    "version": "1.0.0",
+    "description": "A minimal, token-efficient MCP transport interceptor converting JSON to ISON.",
+    "main": "bin/mcpison.js",
+    "bin": {
+        "mcpison": "bin/mcpison.js"
+    },
+    "files": [
+        "bin/mcpison.js"
+    ],
+    "scripts": {
+        "test": "node test/run-test.js"
+    },
+    "keywords": [
+        "mcp",
+        "ison",
+        "proxy",
+        "interceptor",
+        "token",
+        "jsonrpc"
+    ],
+    "author": "TRX",
+    "license": "MIT",
+    "dependencies": {
+        "ison-parser": "^1.0.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}