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

> Explore the architecture of element creation tools in revit-mcp. Learn how point, line, and surface-based designs are translated from JSON to Revit geometry using Zod schema validation and socket connections.

- Repository: [MCP servers for Revit/revit-mcp](https://github.com/mcp-servers-for-revit/revit-mcp)
- Tags: architecture
- Published: 2026-02-16

---

**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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/create_point_based_element.ts) exposes the `create_point_based_element` command
- **Line-based registration** – [`src/tools/create_line_based_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/create_line_based_element.ts) exposes the `create_line_based_element` command  
- **Surface-based registration** – [`src/tools/create_surface_based_element.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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.

```typescript
// 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.

```typescript
// 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.

```typescript
// 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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts)** – Provides the `withRevitConnection` helper that manages `RevitClientConnection` lifecycle, connection timeouts, and socket cleanup.

- **[`src/utils/SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/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.