aps-sample-revit-mcp-tools-bundle

# Revit MCP Tools for APS Automation API

A sample AppBundle for Automation API for Revit 2027 that executes custom tools on Revit Cloud Models. Designed to work with MCP 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
• Overview
• Features
• Prerequisites
• Installation
• Usage
  • Configuration
  • Creating Custom Tools
  • Registering Tools
• Sample Tools
• Development
• 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

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

2. Restore Dependencies

dotnet restore

3. Build the Project

dotnet build -c Release

4. Package for Automation API

Create an AppBundle for Automation API for Revit following Autodesk's guidelines.

5. Create Activity

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

{
  "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:

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

Configuration Options:

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:

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:

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

{  
  "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

{
  "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 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.
Please see the LICENSE file for full details.

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