@mikoto_zero/minigame-open-mcp 1.11.0 → 1.11.2

package/README.md

@@ -19,6 +19,8 @@
 
 ## 🚀 快速开始
 
+> 🐣 **新手请看这里**：[TapTap MCP 配置指南 (小白版)](docs/USER_GUIDE.md) - 手把手教你配置 Cursor、Claude Code 和 VS Code。
+
 ### 安装
 
 ```bash
@@ -42,7 +44,7 @@ npx @mikoto_zero/minigame-open-mcp
       "command": "npx",
       "args": ["-y", "@mikoto_zero/minigame-open-mcp"],
       "env": {
-        "WORKSPACE_ROOT": "${workspaceFolder}"
+        "TAPTAP_MCP_WORKSPACE_ROOT": "${workspaceFolder}"
       }
     }
   }
@@ -52,9 +54,9 @@ npx @mikoto_zero/minigame-open-mcp
 **重要说明**：
 
 - **零配置 OAuth**：首次使用会提示扫码授权，token 自动保存！
-- **路径处理**：设置 `WORKSPACE_ROOT` 环境变量可以正确解析相对路径（推荐）
+- **路径处理**：设置 `TAPTAP_MCP_WORKSPACE_ROOT` 环境变量可以正确解析相对路径（推荐）
   - 如果不设置，相对路径会基于用户 HOME 目录（可能不符合预期）
-  - 建议使用绝对路径，或配置 `WORKSPACE_ROOT`
+  - 建议使用绝对路径，或配置 `TAPTAP_MCP_WORKSPACE_ROOT`
 
 #### OpenHands（推荐 SSE 模式）
 
@@ -311,6 +313,7 @@ graph LR
 
 ### 用户文档
 
+- **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)** - 🐣 新手配置指南（Cursor/VS Code/Claude Code）
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** - 贡献指南
 - **[CHANGELOG.md](CHANGELOG.md)** - 版本变更历史
 

package/dist/proxy.js

@@ -13389,13 +13389,19 @@ var StreamableHTTPClientTransport = class {
 };
 
 // src/mcp-proxy/proxy.ts
-var VERSION = true ? "1.11.0" : "dev";
+var VERSION = true ? "1.11.2" : "dev";
 var TapTapMCPProxy = class {
+  // 30秒验证一次会话
   constructor(config) {
     this.connected = false;
     this.reconnecting = false;
     this.reconnectTimer = null;
+    this.healthCheckTimer = null;
     this.pendingRequests = [];
+    // 会话验证相关
+    this.sessionValidated = false;
+    this.lastValidationTime = 0;
+    this.SESSION_VALIDATION_INTERVAL = 3e4;
     this.config = config;
     this.client = new Client(
       { name: "taptap-proxy-client", version: "1.0.0" },
@@ -13439,8 +13445,12 @@ var TapTapMCPProxy = class {
     try {
       const transport = new StreamableHTTPClientTransport(new URL(this.config.server.url));
       await this.client.connect(transport);
+      await this.validateSession();
       this.connected = true;
-      console.error("[Proxy] ✅ Connected to TapTap MCP Server");
+      this.sessionValidated = true;
+      this.lastValidationTime = Date.now();
+      console.error("[Proxy] ✅ Connected and session validated");
+      this.startHealthCheck();
       if (this.reconnecting) {
         await this.notifyReconnected();
         await this.processPendingRequests();
@@ -13448,9 +13458,75 @@ var TapTapMCPProxy = class {
       }
     } catch (error) {
       this.connected = false;
+      this.sessionValidated = false;
       throw error;
     }
   }
+  /**
+   * 验证 MCP 会话是否有效
+   * 通过调用 listTools 来验证 Server 端的 MCP 会话状态
+   */
+  async validateSession() {
+    console.error("[Proxy] Validating MCP session...");
+    try {
+      await this.client.listTools();
+      console.error("[Proxy] ✅ Session validation successful");
+    } catch (error) {
+      console.error("[Proxy] ❌ Session validation failed:", error);
+      if (this.isSessionInvalidError(error)) {
+        throw new Error("Server session not initialized - need to reconnect");
+      }
+      throw error;
+    }
+  }
+  /**
+   * 检测是否是会话无效错误（Server 未初始化）
+   */
+  isSessionInvalidError(error) {
+    if (!(error instanceof Error)) return false;
+    const errorMsg = error.message.toLowerCase();
+    const sessionInvalidKeywords = [
+      "server not initialized",
+      "not initialized",
+      "session not found",
+      "session expired",
+      "invalid session",
+      "no active session"
+    ];
+    return sessionInvalidKeywords.some((keyword) => errorMsg.includes(keyword));
+  }
+  /**
+   * 启动定期健康检查
+   */
+  startHealthCheck() {
+    var _a2;
+    this.stopHealthCheck();
+    const interval = ((_a2 = this.config.options) == null ? void 0 : _a2.health_check_interval) ?? this.SESSION_VALIDATION_INTERVAL;
+    this.healthCheckTimer = setInterval(async () => {
+      if (!this.connected || this.reconnecting) return;
+      try {
+        await this.validateSession();
+        this.lastValidationTime = Date.now();
+      } catch (error) {
+        console.error("[Proxy] ❌ Health check failed, triggering reconnection");
+        this.connected = false;
+        this.sessionValidated = false;
+        if (!this.reconnecting) {
+          this.reconnectToServer();
+        }
+      }
+    }, interval);
+    console.error(`[Proxy] Health check started (interval: ${interval}ms)`);
+  }
+  /**
+   * 停止健康检查
+   */
+  stopHealthCheck() {
+    if (this.healthCheckTimer) {
+      clearInterval(this.healthCheckTimer);
+      this.healthCheckTimer = null;
+    }
+  }
   /**
    * 重连到 TapTap Server
    */
@@ -13495,6 +13571,7 @@ var TapTapMCPProxy = class {
    * 清理资源（公开方法，供进程退出时调用）
    */
   cleanup() {
+    this.stopHealthCheck();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -13506,7 +13583,7 @@ var TapTapMCPProxy = class {
     }
   }
   /**
-   * 检测是否是网络错误或连接中断
+   * 检测是否是需要重连的错误（网络错误或会话无效）
    */
   isNetworkError(error) {
     if (!(error instanceof Error)) return false;
@@ -13541,12 +13618,13 @@ var TapTapMCPProxy = class {
       "connection reset",
       "timeout",
       "dns",
-      "server not initialized",
-      // MCP SDK Server 未初始化（重启后会话丢失）
       "not connected"
       // 连接断开
     ];
-    return networkErrorKeywords.some((keyword) => errorMsg.includes(keyword));
+    if (networkErrorKeywords.some((keyword) => errorMsg.includes(keyword))) {
+      return true;
+    }
+    return this.isSessionInvalidError(error);
   }
   /**
    * 处理待处理的请求队列