Architecture of Element Creation Tools in Revit-MCP: Point, Line, and Surface-Based Design

Revit-MCP implements element creation through three specialized MCP tools—create_point_based_element, create_line_based_element, and create_surface_based_element—each utilizing Zod schema validation and a shared socket connection manager to translate JSON payloads into native Revit geometry.

The mcp-servers-for-revit/revit-mcp repository provides a Model Context Protocol (MCP) server that bridges AI assistants with Autodesk Revit. Understanding the architecture of element creation tools in Revit-MCP reveals how geometric primitives flow from high-level JSON commands to concrete Building Information Modeling (BIM) elements through a consistent, type-safe pipeline.

Core Architectural Components

MCP Server Registration Pattern

Each element creation tool registers itself on the central McpServer instance via the server.tool() method. This registration pattern isolates concerns by placing each tool in its own source file under src/tools/.

• Point-based registration – src/tools/create_point_based_element.ts exposes the create_point_based_element command
• Line-based registration – src/tools/create_line_based_element.ts exposes the create_line_based_element command
• Surface-based registration – src/tools/create_surface_based_element.ts exposes the create_surface_based_element command

Zod Schema Validation Layer

Before any Revit communication occurs, each tool validates incoming parameters using Zod schemas. This guarantees type safety and immediate error feedback for malformed requests.

The point-based tool expects an array of objects containing name, optional typeId, a nested locationPoint with x, y, z coordinates, dimensional fields (width, depth, height), level identifiers, and optional rotation.

The line-based tool validates locationLine objects containing p0 and p1 coordinate pairs, plus thickness, height, and level data.

The surface-based tool requires a boundary.outerLoop array containing at least three line segments (each with p0 and p1), ensuring closed polygon geometry suitable for floors, ceilings, or roofs.

Connection Management via withRevitConnection

All three tools delegate socket lifecycle management to withRevitConnection in src/utils/ConnectionManager.ts. This helper:

1. Instantiates a RevitClientConnection targeting localhost:8080
2. Enforces a 5-second connection timeout
3. Executes the supplied async operation containing the actual Revit command
4. Guarantees cleanup by disconnecting the socket regardless of success or failure

This pattern prevents resource leaks and standardizes error handling across the element creation architecture.

Point-Based Element Creation

Point-based creation handles families that require a single insertion point, such as doors, windows, furniture, and equipment. The tool transmits the 3D coordinate along with rotation and dimensional constraints to Revit.

// Client invocation example
const result = await mcpClient.callTool(
  "create_point_based_element",
  [
    {
      name: "Exterior Door",
      typeId: 1012,
      locationPoint: { x: 5000, y: 2000, z: 0 },
      width: 900,
      depth: 210,
      height: 2100,
      baseLevel: 0,
      baseOffset: 0,
      rotation: 0
    }
  ]
);

Line-Based Element Creation

Line-based creation supports linear elements such as walls, beams, pipes, and ducts. The architecture requires start and end coordinates to define the element's path, plus cross-sectional dimensions like thickness and height.

// Client invocation example
await mcpClient.callTool(
  "create_line_based_element",
  [
    {
      name: "Exterior Wall",
      typeId: 3001,
      locationLine: {
        p0: { x: 0, y: 0, z: 0 },
        p1: { x: 8000, y: 0, z: 0 }
      },
      thickness: 300,
      height: 3000,
      baseLevel: 0,
      baseOffset: 0
    }
  ]
);

Surface-Based Element Creation

Surface-based creation manages planar elements including floors, ceilings, and roofs. The tool validates that the provided outerLoop forms a closed polygon with at least three segments before transmitting to Revit.

// Client invocation example
await mcpClient.callTool(
  "create_surface_based_element",
  [
    {
      name: "Level 1 Floor",
      typeId: 4002,
      boundary: {
        outerLoop: [
          { p0: { x: 0, y: 0, z: 0 }, p1: { x: 10000, y: 0, z: 0 } },
          { p0: { x: 10000, y: 0, z: 0 }, p1: { x: 10000, y: 8000, z: 0 } },
          { p0: { x: 10000, y: 8000, z: 0 }, p1: { x: 0, y: 8000, z: 0 } },
          { p0: { x: 0, y: 8000, z: 0 }, p1: { x: 0, y: 0, z: 0 } }
        ]
      },
      thickness: 200,
      baseLevel: 0,
      baseOffset: 0
    }
  ]
);

Key Source Files and Implementation Details

The architecture of element creation tools in Revit-MCP relies on these specific source files:

• src/tools/create_point_based_element.ts – Registers the point-based creation tool, validates single-point geometry payloads, and forwards commands to Revit.

• src/tools/create_line_based_element.ts – Registers the line-based creation tool, validates linear geometry with start/end coordinates, and manages wall or beam creation workflows.

• src/tools/create_surface_based_element.ts – Registers the surface-based creation tool, validates closed boundary loops for planar elements, and handles floor, ceiling, and roof generation.

• src/utils/ConnectionManager.ts – Provides the withRevitConnection helper that manages RevitClientConnection lifecycle, connection timeouts, and socket cleanup.

• src/utils/SocketClient.ts – Implements the low-level TCP client used by ConnectionManager to communicate with the Revit add-in on localhost:8080.

• src/index.ts – Server bootstrap file where all three element creation tools are registered on the McpServer instance.

Summary

• Revit-MCP exposes three specialized MCP tools—create_point_based_element, create_line_based_element, and create_surface_based_element—to handle distinct geometric primitives.

• Each tool implements Zod schema validation to enforce type safety and prevent invalid payloads from reaching Revit.

• The connection management layer (withRevitConnection in src/utils/ConnectionManager.ts) standardizes socket lifecycle handling, ensuring reliable TCP communication with the Revit add-in at localhost:8080.

• Tool registration occurs in isolated source files under src/tools/, promoting modularity and maintainability within the server architecture.

Frequently Asked Questions

How does Revit-MCP validate incoming geometry data before sending it to Revit?

Each element creation tool uses Zod schemas to validate JSON payloads immediately upon invocation. For example, the surface-based tool verifies that boundary.outerLoop contains at least three line segments forming a closed polygon, while the point-based tool validates 3D coordinate objects. This schema validation occurs before any socket connection to Revit is established, ensuring only well-formed data reaches the BIM environment.

What is the purpose of the withRevitConnection helper in the element creation workflow?

The withRevitConnection function in src/utils/ConnectionManager.ts encapsulates the entire lifecycle of a TCP connection to the Revit add-in. It instantiates a RevitClientConnection, enforces a 5-second connection timeout, executes the specific creation command, and guarantees socket cleanup regardless of success or failure. This pattern prevents resource leaks and eliminates repetitive connection boilerplate across the three element creation tools.

Can Revit-MCP create complex curved walls or non-rectangular floors?

The current architecture supports linear segments for line-based elements and closed polygonal loops for surface-based elements. The line-based tool accepts start and end points (p0 and p1), implying straight segments, while the surface-based tool requires a closed outerLoop of line segments. Curved geometry would require extending the Zod schemas to accept additional curve parameters and corresponding updates to the Revit add-in command handlers.

How are the element creation tools registered when the MCP server starts?

Registration occurs in src/index.ts, where the server imports registration functions from each tool file under src/tools/. The registerCreatePointBasedElementTool, registerCreateLineBasedElementTool, and registerCreateSurfaceBasedElementTool functions each call server.tool() on the McpServer instance, binding the tool name to its handler function and Zod schema. This modular registration pattern keeps the server bootstrap clean while isolating tool-specific logic in dedicated source files.

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