# autodesk-platform-services/aps-aecdm-mcp-dotnet architecture

> Architecture diagram of the GitHub repository autodesk-platform-services/aps-aecdm-mcp-dotnet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/autodesk-platform-services/aps-aecdm-mcp-dotnet
- Repository: https://github.com/autodesk-platform-services/aps-aecdm-mcp-dotnet

## Overview

##### Project type and purpose
- This is a .NET Core “Model Context Protocol” (MCP) server: a console application that plugs into Claude Desktop via the MCP SDK and exposes a set of tools for querying Autodesk’s AEC Data Model API, Data Management API, and driving a Viewer. It acts as middleware between the Claude agent and Autodesk services.

##### File structure
- Top-level: a single Visual Studio solution (`.sln`) and project (`mcp-server-aecdm.csproj`).
- Source files:
- Program.cs – the host that kicks off the MCP server and registers tools
- AuthTools.cs – handles OAuth2 PKCE token acquisition
- AECDMTools.cs – contains methods to call Hubs, Projects, ElementGroups, Elements endpoints
- ViewerTool.cs – issues commands to a Viewer (render, highlight)
- Global.cs – holds shared configuration/state
- No separate frontend directory; the only “client” is the MCP protocol client inside Claude Desktop.
- Configuration: `launchSettings.json` for local debugging.

##### README for insights
- The README confirms the seven tools exposed by the server and the external services used (OAuth2, Data Management v2, AEC Data Model v1, Viewer).
- It describes how to register the server in Claude’s config file (JSON).

##### Components & relationships
a. Main components
1) Claude Desktop (MCP client)
2) .NET MCP Server
– Program.cs (host)
– AuthTools
– AECDMTools
– ViewerTool
– Global config
3) Autodesk OAuth2 Service
4) Autodesk Data Management API (Hubs & Projects)
5) Autodesk AEC Data Model API (ElementGroups & Elements)
6) Viewer Engine / Viewer SDK

b. Interactions & data flow
- Claude Desktop ⇄ .NET MCP Server (ModelContextProtocol messages)
- .NET Server → Auth Service (GetToken) → receives access token
- .NET Server → Data Management API (GetHubs, GetProjects) → receives hubs/projects
- .NET Server → AEC Data Model API (GetElementGroupsByProject, GetElementsByElementGroup) → receives element data
- .NET Server → Viewer Engine (RenderModel, HighlightElements) → updates visual output
- .NET Server → Claude Desktop (returns JSON responses or viewer session info)

c. Architectural patterns & principles
- Plugin pattern: each “Tool” (AuthTools, AECDMTools, ViewerTool) implements a known interface and is registered by Program.cs
- Single-process console host, no external database
- Clear separation of concerns: authentication, data access, rendering
- Async messaging via ModelContextProtocol

d. Key technologies/frameworks
- .NET 8 / C# console app
- ModelContextProtocol .NET SDK (NuGet)
- Autodesk OAuth2 (PKCE)
- Autodesk Data Management API v2
- Autodesk AEC Data Model API v1
- Autodesk Viewer (via ViewerTool)

##### Don’t overthink—capture all essential elements
- Every tool is represented as a subcomponent.
- Clearly label API calls (e.g., “GET /hubs”, “GET /projects”, “GetElementGroupsByProject”).
- Call out the OAuth2 handshake separately, since it underpins all subsequent API calls.
- Data flow from natural-language query → Claude → MCP Server → Autodesk services → Viewer → back to Claude.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    subgraph "Claude Desktop (MCP Client)"
        CD["Claude Desktop"]:::frontend
    end

    %% Backend Server with Tools and Configuration
    subgraph ".NET MCP Server"
        direction TB
        Prog["Program.cs"]:::backend
        Auth["AuthTools.cs"]:::backend
        AECDM["AECDMTools.cs"]:::backend
        Viewer["ViewerTool.cs"]:::backend
        Global["Global.cs"]:::backend

        subgraph "Configuration"
            direction TB
            Launch["launchSettings.json"]:::backend
            Csproj["mcp-server-aecdm.csproj"]:::backend
            Sln["mcp-server-aecdm.sln"]:::backend
        end
    end

    %% External Services
    subgraph "Autodesk Cloud Services"
        direction TB
        OAuth["OAuth2 Service"]:::service
        DMAPI["Data Management API"]:::service
        AECAPI["AEC Data Model API"]:::service
        ViewerEngine["Viewer Engine"]:::service
    end

    %% Data Flows
    CD -->|"ModelContextProtocol"| Prog
    Prog -->|registers| Auth
    Prog -->|registers| AECDM
    Prog -->|registers| Viewer
    Auth -->|"GetToken"| OAuth
    AECDM -->|"GET /hubs, GET /projects"| DMAPI
    AECDM -->|"GetElementGroupsByProject, GetElementsByElementGroup"| AECAPI
    Viewer -->|"RenderModel, HighlightElements"| ViewerEngine
    Prog -->|"JSON responses / Viewer session"| CD

    %% Click Events
    click Prog "https://github.com/autodesk-platform-services/aps-aecdm-mcp-dotnet/blob/main/mcp-server-aecdm/Program.cs"
    click Auth "https://github.com/autodesk-platform-services/aps-aecdm-mcp-dotnet/blob/main/mcp-server-aecdm/AuthTools.cs"
    click AECDM "https://github.com/autodesk-platform-services/aps-aecdm-mcp-dotnet/blob/main/mcp-server-aecdm/AECDMTools.cs"
    click Viewer "https://github.com/autodesk-platform-services/aps-aecdm-mcp-dotnet/blob/main/mcp-server-aecdm/ViewerTool.cs"
    click Global "https://github.com/autodesk-platform-services/aps-aecdm-mcp-dotnet/blob/main/mcp-server-aecdm/Global.cs"
    click Launch "https://github.com/autodesk-platform-services/aps-aecdm-mcp-dotnet/blob/main/mcp-server-aecdm/Properties/launchSettings.json"
    click Csproj "https://github.com/autodesk-platform-services/aps-aecdm-mcp-dotnet/blob/main/mcp-server-aecdm/mcp-server-aecdm.csproj"
    click Sln "https://github.com/autodesk-platform-services/aps-aecdm-mcp-dotnet/blob/main/mcp-server-aecdm/mcp-server-aecdm.sln"

    %% Styles
    classDef frontend fill:#FFA500,stroke:#333,stroke-width:1px
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
```
