Visum Thinker MCP Server

Instructions

Implementation Reference

• src/index-backup.ts:1011-1058 (registration)

  MCP tool registration for 'project_open', including schema {projectPath: string} and handler that delegates to ProjectServerManager.openProject

  server.tool(
    "project_open",
    "🚀 DEFAULT TOOL for opening Visum projects. Always use this tool when asked to open, load, or launch any Visum project. Creates dedicated TCP server for ultra-fast communication.",
    {
      projectPath: z.string().describe("Full path to the Visum project file (.ver)")
    },
    async ({ projectPath }) => {
      console.error(`🚀 PROJECT_OPEN CHIAMATO: ${projectPath}`);
      console.error(`⏰ Timestamp: ${new Date().toISOString()}`);
      
      try {
        console.error(`🔄 Avvio ProjectServerManager.openProject...`);
        const result = await serverManager.openProject(projectPath);
        console.error(`✅ ProjectServerManager.openProject completato: ${result.success}`);
        
        if (result.success) {
          return {
            content: [
              {
                type: "text",
                text: `🚀 **Progetto Aperto con Server TCP**\n\n✅ ${result.message}\n\n📊 **Dettagli Server:**\n- **ID Progetto:** ${result.projectId}\n- **Nome:** ${result.serverInfo.projectName}\n- **Porta TCP:** ${result.serverInfo.port}\n- **PID:** ${result.serverInfo.pid}\n- **Status:** ${result.serverInfo.status}\n\n🔗 **Connessione Client:**\n- Host: localhost\n- Porta: ${result.serverInfo.port}\n\n⚡ Server pronto per ricevere comandi ultra-veloci dai client TCP!`
              }
            ]
          };
        } else {
          console.error(`❌ ProjectServerManager.openProject fallito: ${result.message}`);
          return {
            content: [
              {
                type: "text",
                text: `❌ **Errore Apertura Progetto**\n\n${result.message}`
              }
            ]
          };
        }
      } catch (error) {
        console.error(`💥 Eccezione in project_open: ${error instanceof Error ? error.message : String(error)}`);
        return {
          content: [
            {
              type: "text",
              text: `❌ **Errore:** ${error instanceof Error ? error.message : String(error)}`
            }
          ]
        };
      }
    }
  );

• src/project-server-manager.ts:63-166 (handler)

  Core implementation: generates projectId, spawns dedicated TCP server process for the Visum project, waits for readiness, manages registry of active servers

  async openProject(projectPath: string): Promise<any> {
    const projectId = this.generateProjectId(projectPath);
    
    // Controlla se il progetto è già aperto
    if (this.activeServers.has(projectId)) {
      const serverInfo = this.activeServers.get(projectId);
      
      // Verifica se il server è ancora attivo
      if (await this.isServerAlive(serverInfo)) {
        return {
          success: true,
          message: 'Progetto già aperto',
          projectId,
          serverInfo: {
            ...serverInfo,
            alreadyOpen: true
          }
        };
      } else {
        // Server morto, rimuovi dal registry
        this.activeServers.delete(projectId);
        this.saveRegistry();
      }
    }
  
    // Avvia nuovo server per il progetto
    const port = this.nextPort++;
    const serverScript = join(__dirname, '..', 'project-tcp-server.mjs');
    
    console.error(`STARTING: server for project: ${basename(projectPath)}`);
    console.error(`TCP: Porta TCP: ${port}`);
    
    const serverProcess = spawn('node', [serverScript, projectPath, port.toString(), projectId], {
      detached: true,
      stdio: ['ignore', 'pipe', 'pipe']
    });
  
    const serverInfo = {
      projectId,
      projectPath,
      projectName: basename(projectPath, '.ver'),
      port,
      pid: serverProcess.pid,
      startTime: Date.now(),
      startTimeString: new Date().toLocaleString('it-IT'),
      status: 'starting'
    };
  
    // Salva nel registry
    this.activeServers.set(projectId, serverInfo);
    this.saveRegistry();
  
    // Aspetta inizializzazione del server
    return new Promise((resolve) => {
      let initialized = false;
      const timeout = setTimeout(() => {
        if (!initialized) {
          resolve({
            success: false,
            message: 'Timeout inizializzazione server',
            projectId
          });
        }
      }, 300000); // 5 minuti timeout per progetti grandi
  
      serverProcess.stdout.on('data', (data) => {
        const output = data.toString();
        console.error(`SERVER: ${projectId}:`, output.trim());
        
        if (output.includes('SERVER PRONTO PER CLIENT TCP') && !initialized) {
          initialized = true;
          clearTimeout(timeout);
          
          // Aggiorna status
          serverInfo.status = 'ready';
          this.activeServers.set(projectId, serverInfo);
          this.saveRegistry();
          
          resolve({
            success: true,
            message: `Server progetto avviato su porta ${port}`,
            projectId,
            serverInfo
          });
        }
      });
  
      serverProcess.stderr.on('data', (data) => {
        const message = data.toString().trim();
        // Distingui tra messaggi informativi e veri errori
        if (message.includes('INIT:') || message.includes('Creating') || message.includes('Starting') || message.includes('Python:')) {
          console.error(`INFO: Server ${projectId}:`, message);
        } else {
          console.error(`ERROR: Server ${projectId} error:`, message);
        }
      });
  
      serverProcess.on('exit', (code) => {
        console.error(`TERMINATED: Server ${projectId} terminato con codice ${code}`);
        this.activeServers.delete(projectId);
        this.saveRegistry();
      });
    });
  }

• src/index-backup.ts:1013-1015 (schema)

  Zod input schema for project_open tool: requires projectPath string

  "🚀 DEFAULT TOOL for opening Visum projects. Always use this tool when asked to open, load, or launch any Visum project. Creates dedicated TCP server for ultra-fast communication.",
  {
    projectPath: z.string().describe("Full path to the Visum project file (.ver)")

• src/project-server-manager.ts:53-61 (helper)

  Helper to generate unique projectId from path

  generateProjectId(projectPath: string): string {
    // Genera ID unico basato sul path del progetto
    const projectName = basename(projectPath, '.ver');
    const hash = Math.abs(projectPath.split('').reduce((a: number, b: string) => {
      a = ((a << 5) - a) + b.charCodeAt(0);
      return a & a;
    }, 0));
    return `${projectName}_${hash}`;
  }

• src/project-server-manager.ts:32-52 (helper)

  Registry persistence helpers for active project servers

  loadRegistry() {
    if (existsSync(this.registryFile)) {
      try {
        const data = JSON.parse(readFileSync(this.registryFile, 'utf8'));
        this.activeServers = new Map(Object.entries(data.servers || {}));
        this.nextPort = data.nextPort || 7900;
      } catch (error: any) {
        console.error('⚠️ Errore caricamento registry:', error.message);
      }
    }
  }
  
  saveRegistry() {
    const registryData = {
      servers: Object.fromEntries(this.activeServers),
      nextPort: this.nextPort,
      lastUpdate: new Date().toISOString()
    };
    writeFileSync(this.registryFile, JSON.stringify(registryData, null, 2));
  }