aps-sample-revit-mcp-tools-bundle

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

aps-sample-revit-mcp-tools-bundle

★ 14 Open GitHub ↗

Sample AppBundle for Automation API for Revit that enables AI assistants to execute custom tools on Revit Cloud Models through the MCP.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Revit MCP Tools for APS Automation API

[![APS Automation API](https://img.shields.io/badge/Design%20Automation-v3-green.svg)](https://aps.autodesk.com/developer/overview/automation-api)
[![Revit API-2027](https://img.shields.io/badge/Revit-2027-lightgrey.svg)](https://aps.autodesk.com/developer/overview/revit)
[![.NET](https://img.shields.io/badge/.NET-10.0-512BD4?logo=dotnet)](https://dotnet.microsoft.com/)
[![C#](https://img.shields.io/badge/C%23-14.0-239120?logo=csharp)](https://docs.microsoft.com/en-us/dotnet/csharp/)

A sample AppBundle for Automation API for Revit 2027 that executes custom tools on Revit Cloud Models. Designed to work with **[MCP Revit Automation](https://github.com/autodesk-platform-services/aps-sample-mcp-server-revit-automation)** - allowing AI assistants like Claude or VS Code Copilot to orchestrate Revit operations through natural language.

---

> **⚠️ Disclaimer**  
> This is a **vibe-coded sample solution** - an exploratory proof-of-concept developed iteratively. It demonstrates patterns and possibilities but may not follow all production-grade practices. This README was generated by **GitHub Copilot** based on analyzing the actual codebase, ensuring documentation matches implementation.

---

## How It Works

This AppBundle is deployed to Autodesk Automation API for Revit and invoked by the **MCP Revit Automation** server:

```
┌─────────────────┐      ┌──────────────────────┐      ┌─────────────────────┐
│   AI Assistant  │──────│  MCP Revit Server    │──────│  Automation API     │
│ (Claude/VS Code)│      │ (Orchestration)      │      │  (Revit Engine)     │
└─────────────────┘      └──────────────────────┘      └─────────────────────┘
        │                         │                              │
        │  "Link these models"    │                              │
        ├────────────────────────>│                              │
        │                         │  Create WorkItem             │
        │                         ├─────────────────────────────>│
        │                         │                              │
        │                         │                    ┌─────────┴─────────┐
        │                         │                    │ This AppBundle    │
        │                         │                    │ - Load tool       │
        │                         │                    │ - Execute logic   │
        │                         │                    │ - Save model      │
        │                         │                    └─────────┬─────────┘
        │                         │  Results                     │
        │                         │<─────────────────────────────┤
        │  "Links added!"         │                              │
        │<────────────────────────┤                              │
```

---

## Table of Contents

- [How It Works](#how-it-works)
- [Overview](#overview)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
  - [Configuration](#configuration)
  - [Creating Custom Tools](#creating-custom-tools)
  - [Registering Tools](#registering-tools)
- [Sample Tools](#sample-tools)
- [Development](#development)
- [Integration with MCP Revit Automation](#integration-with-mcp-revit-automation)

## Overview

**Revit MCP Tools** is an AppBundle that provides a plugin-based architecture for executing automated operations on Revit Cloud Models. When deployed to Automation API for Revit 2027, it can be invoked by the **MCP Revit Automation** server, enabling AI assistants to perform Revit operations through natural language commands.

### Problem It Solves

When building AI-powered Revit automation workflows, developers need:
- **Reusable Tool Library**: A collection of common Revit operations that AI can call
- **Model Lifecycle Management**: Automatic opening, processing, and saving of Cloud Models
- **Flexible Tool Registration**: Easy addition of custom tools without modifying core code
- **Worksharing Support**: Automatic handling of both workshared and non-workshared models
- **JSON-based Configuration**: Simple way to specify which model and tool to execute

This AppBundle abstracts away the complexity of Revit API operations, allowing AI assistants to focus on user intent while the tools handle the technical details.

### Who It's For

- Developers building AI-powered Revit automation solutions
- Teams implementing MCP (Model Context Protocol) servers for AEC workflows
- Organizations wanting to enable natural language control of Revit operations
- AEC firms exploring AI assistants for model coordination tasks

## Features

- **🤖 AI Assistant Ready**: Designed to be invoked by MCP servers and AI assistants
- **🔧 Plugin Architecture**: Easy registration of custom tools via attributes
- **☁️ Cloud Model Support**: Seamless opening and saving of Autodesk Forma models
- **🔄 Worksharing Aware**: Automatically handles workshared vs. non-workshared models
- **⚙️ JSON Configuration**: Simple JSON-based configuration for model and tool selection
- **🏗️ Builder Pattern**: Fluent API for setting up the toolbox
- **📝 Comprehensive Logging**: Built-in console logging for debugging and monitoring
- **🔌 Extensible**: Easy to add new tools without modifying core framework

## Prerequisites

- .NET 10.0 SDK

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/autodesk-platform-services/aps-sample-revit-mcp-tools-bundle.git
cd RevitMcpTools
```

### 2. Restore Dependencies

```bash
dotnet restore
```

### 3. Build the Project

```bash
dotnet build -c Release
```

### 4. Package for Automation API

Create an AppBundle for Automation API for Revit following [Autodesk's guidelines](https://aps.autodesk.com/en/docs/design-automation/v3/tutorials/revit/step1-convert-addin/).

### 5. Create Activity

When creating an Activity for this AppBundle, use the following configuration:

```json
{
  "activity": {
    "id": "RevitMcpToolsActivity",
    "description": "Revit MCP Tools for Automation API",
    "engine": "Autodesk.Revit+2027",
    "alias": "dev",
    "commandLine": [
      "$(engine.path)\\RevitCoreConsole.exe /al \"$(appbundles[RevitMcpTools].path)\""
    ],
    "parameters": {
      "revitmodel": {
        "verb": "get",
        "localName": "revitmodel.json"
      },
      "toolinputs": {
        "verb": "get",
        "localName": "toolinputs.json"
      }
    },
    "appbundles": [
      "{{nickname}}.RevitMcpTools+dev"
    ],
    "settings": {}
  }
}
```

**Key Configuration Points:**

- **Input Parameters**:
  - `revitmodel`: The model configuration file (which model to open and which tool to execute)
  - `toolinputs`: Tool-specific input data (parameters for the selected tool)

Replace `{{nickname}}` with your Autodesk APS app nickname/Client Id.

## Usage

### Configuration

To open and process a Revit Cloud Model, the following configuration is required, which must be passed through the WorkItem parameters as `revitmodel.json`:

```json
{
  "region": "US",
  "projectGuid": "your-project-guid",
  "modelGuid": "your-model-guid",
  "toolName": "create_model",
  "save": true
}
```

**Configuration Options:**

| Property | Type | Description |
|----------|------|-------------|
| `region` | string | Forma region (e.g., "US", "EMEA") |
| `projectGuid` | string | GUID of the Forma project |
| `modelGuid` | string | GUID of the Revit model |
| `toolName` | string | Name of the tool to execute (matches tool attribute) |
| `save` | boolean | Whether to save the model after tool execution |

> **Note:** When using the MCP Revit Automation server, this configuration is automatically generated and passed to the WorkItem. Manual creation is only needed for direct Automation API testing.

### Creating Custom Tools

Implement the `IRevitMcpTool` interface and decorate your class with the `[RevitMcpTool]` attribute:

```csharp
using Autodesk.Revit.DB;
using DesignAutomationFramework;
using RevitMcpTools.Utils;

namespace RevitMcpTools.Tools
{
    [RevitMcpTool("my_custom_tool")]
    public class MyCustomTool : IRevitMcpTool
    {
        public bool Execute(DesignAutomationData data, Document doc)
        {
            try
            {
                Console.WriteLine("*** Executing My Custom Tool ***");
                
                // Your tool logic here
                using (Transaction trans = new Transaction(doc, "My Operation"))
                {
                    trans.Start();
                    
                    // Modify the model...
                    
                    trans.Commit();
                }
                
                Console.WriteLine("*** Tool completed successfully ***");
                return true;
            }
            catch (Exception ex)
            {
                Console.WriteLine($"*** Error: {ex.Message} ***");
                return false;
            }
        }
    }
}
```

### Registering Tools

Add your tool to the `AddMcpTools` extension method:

```csharp
public static RevitMcpToolBoxBuilder AddMcpTools(this RevitMcpToolBoxBuilder builder)
{
    return builder
        .AddTool<CreateModelTool>()
        .AddTool<LinkModelsTool>()
        .AddTool<MyCustomTool>();  // Add your tool here
}
```

## Sample Tools

### create_model

Creates a new Revit Cloud Model from a template with optional worksharing.

**Required Input File:** `toolinputs.json`

```json
{  
  "accountId": "00000000-0000-0000-0000-000000000000",
  "projectId": "00000000-0000-0000-0000-000000000000",
  "folderId": "urn:adsk.wipprod:fs.folder:co.example",
  "modelName": "NewModel.rvt",
  "enableWorksharing": true
}
```

### link_models

Add or remove multiple Revit Links into the current model.

**Required Input File:** `toolinputs.json`

```json
{
  "region": "US",
  "projectGuid": "00000000-0000-0000-0000-000000000000",
  "linksToAdd": [
    {
      "modelName": "Architectural_Link.rvt",
      "modelGuid": "11111111-1111-1111-1111-111111111111"
    },
    {
      "modelName": "Structural_Link.rvt",
      "modelGuid": "22222222-2222-2222-2222-222222222222"
    }
  ],
  "linksToRemove": [
    {
      "modelName": "Old_Link.rvt",
      "modelGuid": "99999999-9999-9999-9999-999999999999"
    }
  ]
}
```

## Development

### Project Structure

```
RevitMcpTools/
├── RevitMcpToolsHandler.cs          # Main entry point (IExternalDBApplication)
├── Utils/
│   ├── RevitMcpToolBox.cs           # Core orchestrator
│   ├── RevitMcpToolBoxBuilder.cs    # Fluent builder
│   ├── RevitMcpToolBoxBuilderExtensions.cs
│   ├── IRevitMcpTool.cs             # Tool interface
│   ├── RevitMcpToolAttribute.cs     # Tool registration attribute
│   └── ModelConfiguration.cs         # JSON config parser
├── Tools/
│   ├── CreateModelTool.cs           # Model creation tool
│   └── LinkModelsTool.cs            # Model linking tool
└── Examples/
    └── revitmodel.json              # Configuration example
```

## Integration with MCP Revit Automation

This AppBundle is designed to work seamlessly with the **[MCP Revit Automation](https://github.com/autodesk-platform-services/aps-sample-mcp-server-revit-automation.git)** server, which:

- Exposes tools to AI assistants via the Model Context Protocol (MCP)
- Translates natural language requests into WorkItem configurations
- Manages Automation API authentication and job submission

### Example Workflow

1. **User** (via Claude/VS Code): "Link the structural model to the current architectural model"
2. **MCP Server**: Translates request → creates `revitmodel.json` and `toolinputs.json`
3. **Automation API**: Executes this AppBundle with the tool `link_models`
4. **This AppBundle**: Opens model, links structural model, saves changes
5. **MCP Server**: Reports success back to the AI assistant
6. **User**: Receives confirmation and can continue with next request

---

**Note:** This AppBundle is designed for use with Autodesk Automation API for Revit 2027. It requires:
- Deployment to Automation API as an AppBundle (targeting Revit 2027)
- An MCP server (like MCP Revit Automation) to orchestrate work items
- Proper authentication and access to Autodesk Forma projects

This is a sample project intended as a reference implementation. Feel free to clone or fork it and adapt it to your specific needs.

---
## License

This sample is licensed under the terms of the [MIT License](http://opensource.org/licenses/MIT).
Please see the [LICENSE](LICENSE) file for full details.

---

Made with ❤️ for the AEC community | Vibe-coded with GitHub Copilot

aps-sample-revit-mcp-tools-bundle

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README