Visum Thinker MCP Server

Instructions

Implementation Reference

• src/index-backup.ts:927-970 (registration)

  MCP tool registration for 'project_health_check', including schema (projectId string) and thin async handler that calls projectManager.checkProjectHealth(projectId) and formats response.

  server.tool(
    "project_health_check",
    "Check health of specific project instance",
    {
      projectId: z.string().describe("Project identifier to check health for")
    },
    async ({ projectId }) => {
      try {
        const result = await projectManager.checkProjectHealth(projectId);
        
        if (result.success) {
          const health = result.health;
          const uptime = Math.floor((health.uptime || 0) / 1000);
          
          return {
            content: [
              {
                type: "text", 
                text: `💚 **Health Check - ${health.projectName}**\n\n✅ **Status:** Salutare\n🔄 **Uptime:** ${uptime}s\n⚡ **Performance:** ${health.response_time_ms}ms\n📊 **Memory Usage:** ${health.memory_mb}MB\n📂 **Progetto Caricato:** ${health.project_loaded ? '✅' : '❌'}\n🔗 **Network:** ${health.network_ready ? '✅' : '❌'}`
              }
            ]
          };
        } else {
          return {
            content: [
              {
                type: "text",
                text: `❌ **Health Check Fallito**\n\n${result.error}`
              }
            ]
          };
        }
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `❌ **Errore:** ${error instanceof Error ? error.message : String(error)}`
            }
          ]
        };
      }
    }
  );

• src/project-instance-manager.ts:212-245 (handler)

  Core handler logic in ProjectInstanceManager.checkProjectHealth: retrieves project instance, calls controller.checkInstanceHealth, aggregates with project-specific info like uptime, name.

  public async checkProjectHealth(projectId: string): Promise<{
    success: boolean;
    health?: any;
    error?: string;
  }> {
    const instance = this.projectInstances.get(projectId);
    
    if (!instance || !instance.isActive) {
      return {
        success: false,
        error: `Project instance ${projectId} not active`
      };
    }
  
    try {
      const healthResult = await instance.controller.checkInstanceHealth();
      
      return {
        success: healthResult.success,
        health: {
          ...healthResult.result,
          projectName: instance.config.name,
          uptime: Date.now() - (instance.startTime || Date.now()),
          lastUsed: instance.lastUsed
        },
        error: healthResult.error
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : String(error)
      };
    }
  }

• src/persistent-visum-controller.ts:1036-1072 (helper)

  Supporting health check in PersistentVisumController: sends 'ping' JSON command to persistent Python VisumPy process via stdin, awaits 'pong' response with stats like requestCount, projectLoaded.

  public async checkInstanceHealth(): Promise<VisumResponse> {
    if (!this.isInstanceActive || !this.persistentProcess || this.persistentProcess.killed) {
      return {
        success: false,
        error: "Persistent process not running"
      };
    }
  
    const requestId = (++this.requestCounter).toString();
    
    return new Promise((resolve, reject) => {
      // Store the request
      this.pendingRequests.set(requestId, { resolve, reject });
      
      // Send ping command
      const pingCommand = {
        type: 'ping',
        id: requestId,
        timestamp: Date.now()
      };
      
      const commandJson = JSON.stringify(pingCommand) + '\n';
      console.error(`🩺 Sending health check ${requestId}`);
      this.persistentProcess?.stdin?.write(commandJson);
      
      // Set timeout for ping
      setTimeout(() => {
        if (this.pendingRequests.has(requestId)) {
          this.pendingRequests.delete(requestId);
          resolve({
            success: false,
            error: "Health check timeout"
          });
        }
      }, 5000); // 5 second timeout for ping
    });
  }