What Happens When the Revit Plugin Is Not Running or a Connection to It Fails

When the Revit plugin is not running, the MCP server attempts a TCP connection to localhost:8080, times out after 5 seconds, and returns a structured error message to the calling tool instead of crashing.

The revit-mcp server acts as a bridge between AI assistants and Autodesk Revit, relying on a local TCP socket to communicate with a running Revit plugin. Understanding the failure behavior when the Revit plugin is not running or a connection to it fails is critical for building resilient integrations.

Connection Architecture Overview

The connection lifecycle is managed by two core utilities in the src/utils/ directory:

• SocketClient.ts: Implements the low-level JSON-RPC client using Node.js net.Socket. It handles socket creation, command serialization, response matching by request ID, and error logging.
• ConnectionManager.ts: Orchestrates connection attempts through the withRevitConnection helper, implementing timeout logic and cleanup.

When a tool needs to communicate with Revit, it invokes withRevitConnection, which attempts to open a socket to localhost:8080.

Failure Path When the Revit Plugin Is Not Running

When the Revit plugin is not running, the TCP handshake to port 8080 cannot complete. The system follows this strict failure path:

1. Tool Invocation: A tool like tag_all_walls calls withRevitConnection to execute an operation.
2. Socket Initialization: ConnectionManager.ts creates a new RevitClientConnection instance targeting localhost:8080.
3. Connection Attempt: The code attaches event listeners for "connect" and "error", then calls revitClient.connect().
4. Timeout Trigger: Since no process is listening on port 8080, the connection hangs until the 5-second timeout fires.

The 5-Second Timeout Mechanism

The timeout is hardcoded in src/utils/ConnectionManager.ts:

setTimeout(() => {
  reject(new Error("连接到Revit客户端失败"));
}, 5000);

This rejects the connection promise with the message "连接到Revit客户端失败" (Connection to Revit client failed). The promise rejection propagates up the call stack to the tool's error handler.

Error Propagation to Tools

Each tool wraps the withRevitConnection call in a try/catch block. For example, in src/tools/tag_all_walls.ts:

try {
  const response = await withRevitConnection(async (client) => {
    return await client.sendCommand("tag_walls", args);
  });
  return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
} catch (error) {
  return {
    content: [{ 
      type: "text", 
      text: `Wall tagging failed: ${error instanceof Error ? error.message : String(error)}` 
    }],
  };
}

The result is a structured MCP content object containing the error message, which the client (ChatGPT, Claude, or a CLI) can display to the user without crashing the server.

Handling Transient Connection Failures

If the Revit plugin stops running after a connection is established, SocketClient.ts detects the disconnect through socket events:

this.socket.on("error", (error) => {
  console.error("RevitClientConnection error:", error);
  this.isConnected = false;
});

this.socket.on("close", () => {
  this.isConnected = false;
});

When isConnected is false, subsequent tool calls trigger a new connection attempt via withRevitConnection, which will again timeout if Revit remains unavailable. This ensures the server remains stable and can recover once Revit is restarted.

Summary

• When the Revit plugin is not running, the MCP server attempts to connect to localhost:8080 and fails after a 5-second timeout.
• The error message "连接到Revit客户端失败" propagates through withRevitConnection to the calling tool.
• Tools catch these errors and return structured error payloads instead of crashing the server.
• SocketClient.ts logs connection errors to the console and sets isConnected = false when the socket closes.
• The architecture ensures graceful degradation—the server remains operational and retries connections on subsequent tool calls.

Frequently Asked Questions

How long does the server wait before reporting a connection failure?

The server waits exactly 5 seconds before timing out. This is hardcoded in src/utils/ConnectionManager.ts using setTimeout. If the Revit plugin does not accept the TCP connection within this window, the promise rejects with "连接到Revit客户端失败".

Can I change the port or host where the server looks for the Revit plugin?

Currently, the host and port (localhost:8080) are hardcoded in the connection utilities. To change them, you would need to modify src/utils/ConnectionManager.ts where RevitClientConnection is instantiated, or update the SocketClient.ts defaults. Future versions may expose these as environment variables.

Will the MCP server crash if Revit closes unexpectedly while a tool is running?

No. The server uses try/catch blocks in every tool implementation to handle promise rejections. If Revit closes mid-operation, SocketClient.ts emits an error or close event, sets isConnected = false, and the active command promise rejects. The tool catches this and returns a structured error message to the client without terminating the server process.

What error message will I see in my AI assistant or CLI when Revit is not running?

You will see a message formatted as [Tool Name] failed: 连接到Revit客户端失败. For example, if using the wall tagging tool, the response will be Wall tagging failed: 连接到Revit客户端失败. This is returned as a text content block in the MCP response structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}