MCP Autostarter

Instructions

Implementation Reference

• src/process-manager.ts:21-76 (handler)

  Core handler function that implements the restart_mcp tool logic: detects MCP handler process, gracefully terminates it, and waits for auto-restart by Claude Desktop.

  async restartMCPHandler(): Promise<RestartResult> {
    try {
      // Step 1: Find the MCP handler process
      const mcpProcess = await this.detector.findMCPHandlerProcess();
      
      if (!mcpProcess) {
        return {
          success: false,
          message: 'Could not find MCP handler process. It may not be running.',
          error: 'MCP_HANDLER_NOT_FOUND'
        };
      }
  
      const oldPid = mcpProcess.pid;
      console.log(`Found MCP handler process: PID ${oldPid}`);
  
      // Step 2: Gracefully terminate the process
      await this.gracefulKill(mcpProcess.pid);
      
      // Step 3: Wait a moment for Claude Desktop to detect the disconnection
      await this.delay(1000);
  
      // Step 4: Verify the process was terminated
      const stillRunning = await this.isProcessRunning(oldPid);
      if (stillRunning) {
        // Force kill if graceful didn't work
        await this.forceKill(oldPid);
        await this.delay(500);
      }
  
      // Step 5: Wait for Claude Desktop to restart the MCP handler
      const newProcess = await this.waitForMCPHandler(5000);
      
      if (newProcess) {
        return {
          success: true,
          message: 'MCP handler restarted successfully',
          oldPid,
          newPid: newProcess.pid
        };
      } else {
        return {
          success: false,
          message: 'MCP handler was terminated but did not restart automatically',
          oldPid,
          error: 'MCP_HANDLER_NOT_RESTARTED'
        };
      }
    } catch (error) {
      return {
        success: false,
        message: 'Failed to restart MCP handler',
        error: error instanceof Error ? error.message : 'UNKNOWN_ERROR'
      };
    }
  }

• src/index.ts:67-86 (handler)

  MCP server request handler for call_tool 'restart_mcp', which invokes the process manager's restartMCPHandler and formats the response.

  case 'restart_mcp': {
    try {
      console.error('Restarting MCP handler process...');
      const result = await processManager.restartMCPHandler();
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to restart MCP handler: ${error}`
      );
    }
  }

• src/index.ts:33-41 (schema)

  Tool schema definition including name, description, and empty input schema (no parameters required).

  {
    name: 'restart_mcp',
    description: 'Intelligently restarts only the MCP handler process without disrupting Claude Desktop UI',
    inputSchema: {
      type: 'object',
      properties: {},
      required: [],
    },
  },

• src/process-manager.ts:9-15 (schema)

  Type definition for the output/result of the restart operation.

  export interface RestartResult {
    success: boolean;
    message: string;
    oldPid?: number;
    newPid?: number;
    error?: string;
  }

• src/index.ts:30-62 (registration)

  Registration of tool list handler, which advertises the 'restart_mcp' tool to MCP clients.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: 'restart_mcp',
          description: 'Intelligently restarts only the MCP handler process without disrupting Claude Desktop UI',
          inputSchema: {
            type: 'object',
            properties: {},
            required: [],
          },
        },
        {
          name: 'restart_claude',
          description: 'Fully restarts Claude Desktop application (use only if MCP restart fails)',
          inputSchema: {
            type: 'object',
            properties: {},
            required: [],
          },
        },
        {
          name: 'get_mcp_status',
          description: 'Check if MCP handler and Claude Desktop processes are running',
          inputSchema: {
            type: 'object',
            properties: {},
            required: [],
          },
        },
      ],
    };
  });