# sacred-g/civil3d-mcp architecture

> Architecture diagram of the GitHub repository sacred-g/civil3d-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sacred-g/civil3d-mcp
- Repository: https://github.com/sacred-g/civil3d-mcp

## Overview

Civil3D-MCP is an MCP server plus a native Civil 3D plugin: an AI client submits tool requests, the Node server routes and executes them over JSON-RPC/TCP, and the plugin operates on the live drawing. The map includes orchestration, domain tools, CAD execution, help, standards, and approval capabilities documented in the README. Several domain implementations and registrations are unsampled, so their documented capabilities are represented at directory level and uncertain internal call links are omitted.

Main entry points: [`src/tools/civil3d_orchestrate.ts`](https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/civil3d_orchestrate.ts) (Tool Orchestrator), [`src/index.ts`](https://github.com/sacred-g/civil3d-mcp/blob/main/src/index.ts) (MCP Server), [`src/tools/domains`](https://github.com/sacred-g/civil3d-mcp/tree/main/src/tools/domains) (Civil Design Tools), [`src/utils/ConnectionManager.ts`](https://github.com/sacred-g/civil3d-mcp/blob/main/src/utils/ConnectionManager.ts) (Connection Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client Interfaces"]
  node_node_server["MCP Server<br/>[index.ts]"]
  node_http_bridge["HTTP Bridge<br/>[httpBridge.ts]"]
end

subgraph group_coordination["Request Orchestration"]
  node_orchestrator["Tool Orchestrator"]
  node_intent_router["Intent Router<br/>[IntentRouter.ts]"]
  node_workflow_planner["Workflow Planner<br/>[WorkflowPlanner.ts]"]
  node_project_context["Project Context"]
  node_selection_resolver["Selection Resolver"]
  node_tool_registry["Tool Registry"]
  node_approval["Approval Policy<br/>[approvalPolicy.ts]"]
end

subgraph group_design["Civil Design Domains"]
  node_domain_tools["Civil Design Tools"]
  node_cad_domains["CAD Command Handlers"]
end

subgraph group_operations["Execution and State"]
  node_domain_runtime["Domain Runtime<br/>[domainRuntime.ts]"]
  node_connection_manager["Connection Manager"]
  node_socket_client["TCP JSON-RPC Client<br/>[SocketClient.ts]"]
  node_plugin["Civil 3D Plugin<br/>[PluginEntry.cs]"]
  node_dispatcher["Command Dispatcher"]
end

subgraph group_reference["Help and Standards"]
  node_help_tools["Help Tools<br/>[docsDomain.ts]"]
  node_help_index["Help Search<br/>[helpIndex.ts]"]
  node_help_parser["Help Parser<br/>[helpParser.ts]"]
  node_standards["Framework Standards"]
  node_video_catalog["Tutorial Videos<br/>[videoCatalog.ts]"]
end

node_mcp_client(("MCP Client"))
node_http_client(("HTTP Client"))
node_drawing[("Live Drawing")]
node_autodesk_help["Local Autodesk Help"]

node_mcp_client -->|"MCP requests"| node_node_server
node_http_client -->|"HTTP requests"| node_http_bridge
node_node_server -->|"starts"| node_http_bridge
node_http_bridge -->|"invokes tools"| node_tool_registry
node_node_server -->|"registers tool"| node_orchestrator
node_orchestrator -->|"routes intent"| node_intent_router
node_orchestrator -->|"plans workflow"| node_workflow_planner
node_orchestrator -->|"loads context"| node_project_context
node_orchestrator -->|"resolves selection"| node_selection_resolver
node_orchestrator -->|"executes tool"| node_tool_registry
node_node_server -->|"registers domains"| node_domain_tools
node_domain_tools -->|"uses runtime"| node_domain_runtime
node_domain_runtime -->|"dispatches commands"| node_connection_manager
node_connection_manager -->|"sends RPC"| node_socket_client
node_socket_client -->|"JSON-RPC/TCP"| node_plugin
node_plugin -->|"dispatches methods"| node_dispatcher
node_dispatcher -->|"invokes handlers"| node_cad_domains
node_cad_domains -->|"reads and modifies"| node_drawing
node_connection_manager -.->|"serves context request"| node_project_context
node_domain_tools -.->|"guards mutations"| node_approval
node_help_tools -->|"searches topics"| node_help_index
node_help_index -->|"parses topics"| node_help_parser
node_help_parser -->|"reads local files"| node_autodesk_help
node_help_tools -->|"finds videos"| node_video_catalog
node_domain_tools -.->|"looks up standards"| node_standards

click node_node_server "https://github.com/sacred-g/civil3d-mcp/blob/main/src/index.ts"
click node_http_bridge "https://github.com/sacred-g/civil3d-mcp/blob/main/src/httpBridge.ts"
click node_orchestrator "https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/civil3d_orchestrate.ts"
click node_intent_router "https://github.com/sacred-g/civil3d-mcp/blob/main/src/orchestration/IntentRouter.ts"
click node_workflow_planner "https://github.com/sacred-g/civil3d-mcp/blob/main/src/orchestration/WorkflowPlanner.ts"
click node_project_context "https://github.com/sacred-g/civil3d-mcp/blob/main/src/orchestration/ProjectContextService.ts"
click node_selection_resolver "https://github.com/sacred-g/civil3d-mcp/blob/main/src/orchestration/SelectionResolver.ts"
click node_tool_registry "https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/toolHandlerRegistry.ts"
click node_domain_tools "https://github.com/sacred-g/civil3d-mcp/tree/main/src/tools/domains"
click node_approval "https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/approvalPolicy.ts"
click node_help_tools "https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/domains/docsDomain.ts"
click node_help_index "https://github.com/sacred-g/civil3d-mcp/blob/main/src/help/helpIndex.ts"
click node_help_parser "https://github.com/sacred-g/civil3d-mcp/blob/main/src/help/helpParser.ts"
click node_standards "https://github.com/sacred-g/civil3d-mcp/blob/main/src/standards/FrameworkStandardsService.ts"
click node_domain_runtime "https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/domainRuntime.ts"
click node_connection_manager "https://github.com/sacred-g/civil3d-mcp/blob/main/src/utils/ConnectionManager.ts"
click node_socket_client "https://github.com/sacred-g/civil3d-mcp/blob/main/src/utils/SocketClient.ts"
click node_plugin "https://github.com/sacred-g/civil3d-mcp/blob/main/Civil3D-MCP-Plugin/PluginEntry.cs"
click node_dispatcher "https://github.com/sacred-g/civil3d-mcp/blob/main/Civil3D-MCP-Plugin/CommandDispatcher.cs"
click node_cad_domains "https://github.com/sacred-g/civil3d-mcp/tree/main/Civil3D-MCP-Plugin"
click node_video_catalog "https://github.com/sacred-g/civil3d-mcp/blob/main/src/help/videoCatalog.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_server,node_http_bridge,node_mcp_client,node_http_client toneBlue
class node_orchestrator,node_intent_router,node_workflow_planner,node_project_context,node_selection_resolver,node_tool_registry,node_approval,node_drawing toneAmber
class node_domain_tools,node_cad_domains toneMint
class node_domain_runtime,node_connection_manager,node_socket_client,node_plugin,node_dispatcher toneRose
class node_help_tools,node_help_index,node_help_parser,node_standards,node_video_catalog,node_autodesk_help toneIndigo
```

## Components

### Client Interfaces

- [MCP Server](https://github.com/sacred-g/civil3d-mcp/blob/main/src/index.ts): `src/index.ts`
- [HTTP Bridge](https://github.com/sacred-g/civil3d-mcp/blob/main/src/httpBridge.ts): `src/httpBridge.ts`

### Request Orchestration

- [Tool Orchestrator](https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/civil3d_orchestrate.ts): `src/tools/civil3d_orchestrate.ts`
- [Intent Router](https://github.com/sacred-g/civil3d-mcp/blob/main/src/orchestration/IntentRouter.ts): `src/orchestration/IntentRouter.ts`
- [Workflow Planner](https://github.com/sacred-g/civil3d-mcp/blob/main/src/orchestration/WorkflowPlanner.ts): `src/orchestration/WorkflowPlanner.ts`
- [Project Context](https://github.com/sacred-g/civil3d-mcp/blob/main/src/orchestration/ProjectContextService.ts): `src/orchestration/ProjectContextService.ts`
- [Selection Resolver](https://github.com/sacred-g/civil3d-mcp/blob/main/src/orchestration/SelectionResolver.ts): `src/orchestration/SelectionResolver.ts`
- [Tool Registry](https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/toolHandlerRegistry.ts): `src/tools/toolHandlerRegistry.ts`
- [Approval Policy](https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/approvalPolicy.ts): `src/tools/approvalPolicy.ts`

### Civil Design Domains

- [Civil Design Tools](https://github.com/sacred-g/civil3d-mcp/tree/main/src/tools/domains): `src/tools/domains`
- [CAD Command Handlers](https://github.com/sacred-g/civil3d-mcp/tree/main/Civil3D-MCP-Plugin): `Civil3D-MCP-Plugin`

### Execution and State

- [Domain Runtime](https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/domainRuntime.ts): `src/tools/domainRuntime.ts`
- [Connection Manager](https://github.com/sacred-g/civil3d-mcp/blob/main/src/utils/ConnectionManager.ts): `src/utils/ConnectionManager.ts`
- [TCP JSON-RPC Client](https://github.com/sacred-g/civil3d-mcp/blob/main/src/utils/SocketClient.ts): `src/utils/SocketClient.ts`
- [Civil 3D Plugin](https://github.com/sacred-g/civil3d-mcp/blob/main/Civil3D-MCP-Plugin/PluginEntry.cs): `Civil3D-MCP-Plugin/PluginEntry.cs`
- [Command Dispatcher](https://github.com/sacred-g/civil3d-mcp/blob/main/Civil3D-MCP-Plugin/CommandDispatcher.cs): `Civil3D-MCP-Plugin/CommandDispatcher.cs`

### Help and Standards

- [Help Tools](https://github.com/sacred-g/civil3d-mcp/blob/main/src/tools/domains/docsDomain.ts): `src/tools/domains/docsDomain.ts`
- [Help Search](https://github.com/sacred-g/civil3d-mcp/blob/main/src/help/helpIndex.ts): `src/help/helpIndex.ts`
- [Help Parser](https://github.com/sacred-g/civil3d-mcp/blob/main/src/help/helpParser.ts): `src/help/helpParser.ts`
- [Framework Standards](https://github.com/sacred-g/civil3d-mcp/blob/main/src/standards/FrameworkStandardsService.ts): `src/standards/FrameworkStandardsService.ts`
- [Tutorial Videos](https://github.com/sacred-g/civil3d-mcp/blob/main/src/help/videoCatalog.ts): `src/help/videoCatalog.ts`

### Other components

- **MCP Client**
- **HTTP Client**
- **Live Drawing**
- **Local Autodesk Help**

## Connections

- MCP Client → MCP Server: MCP requests
- HTTP Client → HTTP Bridge: HTTP requests
- MCP Server → HTTP Bridge: starts
- HTTP Bridge → Tool Registry: invokes tools
- MCP Server → Tool Orchestrator: registers tool
- Tool Orchestrator → Intent Router: routes intent
- Tool Orchestrator → Workflow Planner: plans workflow
- Tool Orchestrator → Project Context: loads context
- Tool Orchestrator → Selection Resolver: resolves selection
- Tool Orchestrator → Tool Registry: executes tool
- MCP Server → Civil Design Tools: registers domains
- Civil Design Tools → Domain Runtime: uses runtime
- Domain Runtime → Connection Manager: dispatches commands
- Connection Manager → TCP JSON-RPC Client: sends RPC
- TCP JSON-RPC Client → Civil 3D Plugin: JSON-RPC/TCP
- Civil 3D Plugin → Command Dispatcher: dispatches methods
- Command Dispatcher → CAD Command Handlers: invokes handlers
- CAD Command Handlers → Live Drawing: reads and modifies
- Connection Manager → Project Context: serves context request
- Civil Design Tools → Approval Policy: guards mutations
- Help Tools → Help Search: searches topics
- Help Search → Help Parser: parses topics
- Help Parser → Local Autodesk Help: reads local files
- Help Tools → Tutorial Videos: finds videos
- Civil Design Tools → Framework Standards: looks up standards