APS-ACC-MCP-server

# aps-mcp-server-nodejs Simple [Model Context Protocol](https://modelcontextprotocol.io) server built with Node.js, providing access to [Autodesk Platform Services](https://aps.autodesk.com) API, with fine-grained access control using [Secure Service Accounts](https://aps.autodesk.com/en/docs/ssa/v1/developers_guide/overview/).  [YouTube Video](https://youtu.be/6DRSR9HlIds) ## Overview This MCP server enables AI assistants (like GitHub Copilot, Claude, and Cursor) to interact with your Autodesk Construction Cloud (ACC) projects through natural language. By connecting AI chat interfaces to APS APIs, you can query project data, browse files, and analyze issues without leaving your development environment. ### How It Works The Model Context Protocol (MCP) creates a standardized way for AI assistants to access external data sources: ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ VS Code + │ MCP │ aps-mcp-server │ APS │ Autodesk ACC │ │ GitHub Copilot │ ◄─────► │ (Node.js) │ ◄─────► │ Projects │ └─────────────────┘ stdio └──────────────────┘ API └─────────────────┘ ``` 1. **AI Client** (VS Code/Claude/Cursor) sends natural language queries 2. **MCP Server** translates queries into APS API calls using Secure Service Account credentials 3. **APS APIs** fetch data from your ACC projects 4. **MCP Server** returns structured data to the AI client 5. **AI Client** formats and presents the information to you ### Available MCP Tools This server provides **18 tools** across multiple functional areas: #### Projects & Files (2 tools) | Tool | Description | Parameters | Returns | |------|-------------|------------|---------| | **getProjectsTool** | Retrieves all ACC accounts and projects accessible to your service account | None | List of accounts with nested projects (IDs and names) | | **getFolderContentsTool** | Browses folder and file structure within a project | `accountId`, `projectId`, `folderId` (optional) | List of folders and files with IDs and display names | #### Issues Management (7 tools) | Tool | Description | Parameters | Returns | |------|-------------|------------|---------| | **getIssuesTool** | Fetches all issues from a project | `projectId` | List of issues with IDs, titles, statuses, types, assignments, due dates, and 3D coordinates | | **getIssueTypesTool** | Gets available issue types and subtypes | `projectId` | List of issue types with subtypes (for issue classification) | | **createIssueTool** | Creates a new issue in a project | `projectId`, `title`, `issueSubtypeId`, `status`, and many optional fields | Created issue with full details including ID, display ID, and timestamps | | **getIssueDetailsTool** | Retrieves detailed information about a specific issue | `projectId`, `issueId`, `includeComments`, `includeAttachments` | Complete issue details including description, assignee, dates, location, comments, attachments, custom attributes, and audit trail | | **updateIssueTool** | Updates an existing issue | `projectId`, `issueId`, plus any fields to update | Updated issue details | | **addIssueCommentTool** | Adds a comment to an issue | `projectId`, `issueId`, `body` | Comment confirmation with ID and timestamp | | **addIssueAttachmentTool** | Documents the process for adding attachments to issues | `projectId`, `issueId`, `fileName`, `fileUrl` | Documentation/guidance (placeholder - requires Data Management API) | #### RFIs Management (4 tools) | Tool | Description | Parameters | Returns | |------|-------------|------------|---------| | **listRFIsTool** | Retrieves all RFIs (Requests for Information) from a project | `projectId`, optional filters: `searchText`, `status`, `assignedTo`, `limit`, `offset` | List of RFIs with IDs, titles, questions, statuses, assignments, and due dates | | **getRFITypesTool** | Gets available RFI types and categories | `projectId` | List of RFI types for classification | | **getRFIDetailsTool** | Retrieves detailed information about a specific RFI | `projectId`, `rfiId` | Complete RFI details including question, responses, attachments, workflow history, and linked documents | | **createRFITool** | Creates a new RFI in a project | `projectId`, `title`, `question`, `dueDate`, `assignedTo`, and optional fields | Created RFI with full details including ID and timestamps | #### Photos Management (2 tools) - Read-Only | Tool | Description | Parameters | Returns | |------|-------------|------------|---------| | **listPhotosTool** | Retrieves photos and videos from a project with filtering | `projectId`, optional: `createdFrom`, `createdTo`, `mediaType`, `limit`, `offset` | List of photos/videos with IDs, names, types, creation dates, and URLs | | **getPhotoDetailsTool** | Retrieves detailed information about a specific photo or video | `projectId`, `photoId` | Complete photo/video details including metadata, location, tags, and custom attributes | **Note:** Photos tools require 3-legged OAuth authentication. Run `npm run oauth-login` before using these tools. See [OAUTH_SETUP.md](OAUTH_SETUP.md) for details. **Important:** ACC Photos API v1 is read-only. Photo uploads must be done through ACC Mobile App or Web Interface. #### Submittals Management (3 tools) ⭐ | Tool | Description | Parameters | Returns | |------|-------------|------------|---------| | **listSubmittalsTool** | Retrieves all submittals from a project with filtering | `projectId`, optional: `status`, `type`, `assignedTo`, `limit`, `offset` | List of submittals with IDs, numbers, titles, statuses, types, due dates, and assignments | | **getSubmittalTypesTool** | Gets available submittal types configured in the project | `projectId` | List of submittal types with IDs, names, codes, and workflows | | **createSubmittalTool** | Creates a new submittal in a project | `projectId`, `title`, `submittalTypeId`, `dueDate`, optional: `number`, `description`, `assignedTo`, `status` | Created submittal with full details including ID, number, status, and timestamps | **Note:** Submittals tools require 3-legged OAuth authentication. Run `npm run oauth-login` before using these tools. See [OAUTH_SETUP.md](OAUTH_SETUP.md) for details. ### VS Code MCP Client Integration When you use this server with **VS Code + GitHub Copilot**: 1. **Configuration**: The `.vscode/mcp.json` file tells VS Code where to find the MCP server 2. **Connection**: VS Code starts the Node.js server and connects via stdio (standard input/output) 3. **Authentication**: The server uses Secure Service Account credentials from `.env` for API access 4. **Tool Discovery**: Copilot learns what tools are available from the server 5. **Natural Queries**: You ask questions in Copilot Chat using plain English 6. **Tool Execution**: Copilot decides which tools to call and with what parameters 7. **Response**: Results are formatted and displayed in the chat interface **Example interaction:** ``` You: "What projects do I have access to?" Copilot: [calls getProjectsTool] → "You have 1 project: Construction: Sample Project..." You: "List all issues" Copilot: [calls getIssuesTool with projectId] → "You have 3 open issues..." You: "Show me details of issue abc123" Copilot: [calls getIssueDetailsTool] → "Issue: Concrete Surface Finish... Status: Open..." You: "Create a new issue for the Level 2 rework" Copilot: [calls createIssueTool] → "✅ Issue created successfully! ID: xyz789..." You: "List all RFIs in my project" Copilot: [calls listRFIsTool] → "You have 5 RFIs: 2 open, 3 answered..." You: "Create an RFI about the concrete specifications" Copilot: [calls createRFITool] → "✅ RFI created successfully! ID: rfi-001..." You: "Show me photos from this project" Copilot: [calls listPhotosTool] → "Found 12 photos: Site inspection, Foundation work..." You: "Get details of photo abc123" Copilot: [calls getPhotoDetailsTool] → "Photo: Site Inspection... Created: 2025-01-10..." ``` ### Comparison with ACC Native Features | Feature | ACC Web Interface | ACC Project Beta | APS MCP Server | |---------|-------------------|------------------|----------------| | **Access Method** | Web browser | Web browser | AI chat in IDE | | **Query Interface** | GUI navigation | Conversational AI | Conversational AI | | **Integration** | Standalone app | Standalone app | Embedded in VS Code/Claude/Cursor | | **Authentication** | User login | User login | Service Account (programmatic) | | **Data Access** | Full ACC features | Limited to conversation context | API-based (read and write access) | | **Customization** | Fixed UI | Fixed AI behavior | Custom tools & scripts | | **Use Case** | Manual project management | Quick queries & assistance | Developer workflows & automation | | **Multi-Project** | Switch between projects | Context limited | Access all authorized projects | | **Offline Mode** | ❌ No | ❌ No | ❌ No (requires API) | | **File Upload** | ✅ Yes | ✅ Yes | ❌ No (read-only for files) | | **Issue Creation** | ✅ Yes | ✅ Yes | ✅ Yes (implemented) | | **Real-time Collaboration** | ✅ Yes | Limited | ❌ No | **Key Differences:** - **ACC Project Beta**: Autodesk's native AI assistant integrated into the ACC web interface, designed for project managers and teams working directly in ACC - **APS MCP Server**: Developer-focused tool that brings ACC data into your coding environment, ideal for: - Building automation scripts - Creating custom reports - Integrating ACC data with other systems - Quick project status checks without leaving your IDE - Prototyping new ACC integrations **When to use each:** - Use **ACC Web Interface** for full project management, file uploads, and team collaboration - Use **ACC Project Beta** for quick questions while working in ACC web - Use **APS MCP Server** for development workflows, custom automation, and IDE-native queries ## Customer Value & Use Cases ### 🎯 Value Proposition The APS MCP Server bridges the gap between construction data and AI-powered development tools, enabling customers to: 1. **Reduce Context Switching** - Access ACC data without leaving your IDE 2. **Accelerate Development** - Build integrations faster with AI assistance 3. **Improve Data Visibility** - Query project data conversationally in natural language 4. **Enable Automation** - Foundation for building custom workflows and scripts 5. **Prototype Rapidly** - Test API integrations before full implementation ### 👥 Target Customer Segments #### 1. **Construction Technology Teams** Organizations building custom integrations on top of ACC: - **Pain Point**: Manual API exploration and testing is time-consuming - **Solution**: Query ACC data conversationally while writing integration code - **Example**: "Show me the issue schema for this project" while building an issue tracking integration #### 2. **BIM/VDC Developers** Developers creating automation for construction workflows: - **Pain Point**: Need to understand project structure before writing automation scripts - **Solution**: Explore project data, folder structures, and issue patterns without leaving the code editor - **Example**: "List all RVT files and their locations" while building a model coordination script #### 3. **System Integrators** Teams connecting ACC with other enterprise systems (ERP, PM tools): - **Pain Point**: Understanding data models and testing connections across multiple systems - **Solution**: Quick data validation and testing during integration development - **Example**: "What fields are available in issues?" while mapping data between systems #### 4. **DevOps/Infrastructure Teams** Teams managing APS applications and monitoring project health: - **Pain Point**: Need quick insights without building full dashboards - **Solution**: Ad-hoc queries for monitoring and troubleshooting - **Example**: "How many open issues are in production projects?" for health checks #### 5. **Independent Developers/Consultants** Freelancers building APS solutions: - **Pain Point**: Limited time for API exploration and testing - **Solution**: Rapid prototyping and validation of ideas - **Example**: Test API responses before committing to implementation approach ### 💼 Real-World Use Cases #### Use Case 1: **Rapid Integration Development** **Scenario**: Developer building a custom dashboard that displays project issues **Traditional Workflow**: 1. Open browser → Navigate to APS API docs 2. Set up Postman/Insomnia for API testing 3. Configure authentication 4. Test API endpoints manually 5. Copy response structure 6. Switch back to IDE 7. Write code based on manual testing **With MCP Server**: 1. In VS Code: "Show me all issues in my project" 2. Review data structure in chat 3. Ask: "What fields are available for filtering?" 4. Immediately start writing code with accurate data models 5. **Time saved**: 30-60 minutes per API endpoint #### Use Case 2: **Project Health Monitoring** **Scenario**: DevOps team needs to check project status across multiple sites **Query Examples**: ``` "How many projects do I have access to?" "List all open issues across projects" "Show me projects with issues overdue by more than 7 days" "What are the most common issue types?" "Get detailed information for issue abc123" "Create a new issue for the concrete rework on Level 2" ``` **Value**: Quick health checks without building custom reporting tools #### Use Case 3: **Debugging Production Issues** **Scenario**: Support team investigating customer-reported problems **Workflow**: ``` Developer: "What issue types are available in project X?" Copilot: [Returns actual issue types from customer's project] Developer: "Show me all issues created in the last 24 hours" Copilot: [Returns recent issues with details] Developer: "Get full details for issue abc123" Copilot: [Shows complete issue information including comments and attachments] Developer: "Create a test issue to verify the API" Copilot: [Creates issue and returns confirmation with issue ID] Developer: "What's the folder structure of this project?" Copilot: [Shows actual folder hierarchy] ``` **Value**: Faster troubleshooting with real-time data access #### Use Case 4: **Data Migration Planning** **Scenario**: Migrating data from legacy system to ACC **Queries**: ``` "Show me the folder structure of all projects" "What custom fields are configured for issues?" "List all file types in the project" "Get a sample issue with all its fields to understand the data structure" "Create a test issue to validate the target system can receive ACC data" ``` **Value**: Understand target system structure before migration scripting #### Use Case 5: **Training & Documentation** **Scenario**: Training new developers on APS APIs **Interactive Learning**: ``` Trainee: "What data can I get from an issue?" Copilot: [Shows real issue structure with actual data using getIssueDetailsTool] Trainee: "How do I create an issue?" Copilot: [Demonstrates with createIssueTool showing required and optional fields] Trainee: "How are folders organized?" Copilot: [Demonstrates with live project data] ``` **Value**: Learn with real examples instead of abstract documentation ### 🔄 Customer Workflow Examples #### For Construction Tech Companies: ``` Morning Standup: PM: "What's blocking us today?" Dev: [Opens VS Code] "Show me all high-priority issues" Result: Team sees real blockers in 5 seconds During Development: Dev: "List all .dwg files in the structural folder" Copilot: [Returns file list] Dev: Uses list to build file processing automation Before Deployment: Dev: "How many projects will this affect?" Copilot: [Lists all accessible projects] Dev: Plans rollout strategy ``` #### For System Integrators: ``` Discovery Phase: "What issue types exist?" → Map to target system "Show me all custom attributes" → Plan data transformation "List all projects by region" → Scope integration effort Development Phase: "Get sample issue data" → Test transformation logic "What's the folder structure?" → Plan file sync strategy "Show project metadata" → Validate connection Testing Phase: "Create test issue" → Validate write operations "Get issue details" → Verify data completeness "List recent changes" → Verify sync accuracy ``` ### 📊 ROI & Metrics **Time Savings**: - API exploration: 30-60 min → 2-5 min (90% reduction) - Data structure discovery: 45 min → 5 min (89% reduction) - Integration prototyping: 4 hours → 1 hour (75% reduction) **Productivity Gains**: - Developers stay in IDE: 80% less context switching - Faster debugging: Real-time data access vs manual API calls - Reduced errors: AI-assisted queries vs manual Postman testing **Business Impact**: - Faster time-to-market for integrations - Lower training costs for new developers - Improved developer experience and satisfaction - Enables rapid prototyping and innovation ### 🚀 Future Expansion Opportunities **Planned Enhancements**: 1. ✅ **Issue Creation** - Create new issues (IMPLEMENTED) 2. ✅ **Issue Details** - Get detailed issue information (IMPLEMENTED) 3. ⏳ **Issue Updates** - Update existing issues (IN PROGRESS) 4. ⏳ **Issue Comments** - Add comments to issues (IN PROGRESS) 5. ⏳ **Issue Attachments** - Upload files to issues (IN PROGRESS) 6. 🔜 **Advanced Queries**: Filter, sort, aggregate data 7. 🔜 **Multi-Project Operations**: Bulk queries across projects 8. 🔜 **File Operations**: Upload/download files 9. 🔜 **Webhooks Integration**: Real-time notifications in IDE 10. 🔜 **Cost Management**: Query budget and cost data 11. 🔜 **Schedule Data**: Access project timelines and milestones 12. 🔜 **RFI Management**: Query and manage RFIs 13. 🔜 **Document Management**: Search and analyze documents **Extended Use Cases**: - ✅ Issue creation from natural language descriptions - Automated issue creation from code comments - Project health dashboards in IDE - Compliance checking and reporting - Automated status updates to stakeholders - Integration testing frameworks - Detailed issue analysis with comments and attachments ### 🎓 Getting Started for Customers **For Construction Tech Teams**: 1. Set up Secure Service Account (15 min) 2. Configure MCP server in VS Code (5 min) 3. Start querying your projects (immediate) 4. Build on top with custom tools (ongoing) **For Consultants/Freelancers**: 1. Use for rapid prototyping (Day 1) 2. Validate customer requirements (Day 2-3) 3. Build production integrations (Week 1+) 4. Deliver faster, more accurate solutions **For Enterprise Teams**: 1. Pilot with 2-3 developers (Week 1) 2. Measure time savings and productivity (Week 2-4) 3. Roll out to entire team (Month 2) 4. Expand with custom tools (Ongoing) ### 💡 Success Stories (Potential) **Example 1: BIM Coordination Company** - **Before**: 4 hours to explore API and build issue reporter - **After**: 1 hour with MCP-assisted development - **Result**: 75% time reduction, faster client delivery **Example 2: Construction Software Vendor** - **Before**: Support team manually checked API responses - **After**: Instant troubleshooting with natural language queries - **Result**: 60% faster issue resolution **Example 3: Enterprise General Contractor** - **Before**: Developers built custom API testing tools - **After**: Used MCP server for all API exploration - **Result**: Eliminated 20 hours/month of tool maintenance ## Development ### Prerequisites - [Node.js](https://nodejs.org) - [APS application](https://aps.autodesk.com/en/docs/oauth/v2/tutorials/create-app) (must be of type _Server-to-Server_) - [Provisioned access to ACC](https://get-started.aps.autodesk.com/#provision-access-in-other-products) ### Setup #### Secure Service Account Our MCP server will need a secure service account and a private key. Instead of implementing the logic in this code sample, we will use https://ssa-manager.autodesk.io: - Go to https://ssa-manager.autodesk.io, and log in with your APS client ID and secret - Create a new secure service account using the _Create Account With Name:_ button; don't forget to specify the first name and last name - Make sure the new account is selected in the _Accounts_ list - Make note of the `serviceAccountId` and `email` values under _Account Details_ - Create a new private key using the _Create Key_ button; a _*.pem_ file will be automatically downloaded to your machine - Make sure the new private key is selected in the _Keys_ list - Make note of the `kid` value under _Key Details_ #### Autodesk Construction Cloud - Make sure you've provisioned access to ACC for your APS application - Invite the secure service account (the `email` value from earlier) as a new member to your selected ACC projects #### Server - Clone this repository - Install dependencies: `yarn install` - Create a _.env_ file in the root folder of this project, and define the following environment variables: - `APS_CLIENT_ID` - your APS application client ID - `APS_CLIENT_SECRET` - your APS application client secret - `SSA_ID` - your service account ID (the `serviceAccountId` field from earlier) - `SSA_KEY_ID` - your private key ID (the `kid` field from earlier) - `SSA_KEY_PATH` - full path to your downloaded *.pem file - The _.env_ file might look something like this: ```bash APS_CLIENT_ID="AhH9..." APS_CLIENT_SECRET="1FS4..." SSA_ID="ZCU2TJH5PK8A5KQ9" SSA_KEY_ID="8a4ee790-3378-44f3-bbab-5acb35ec35ce" SSA_KEY_PATH="/Users/brozp/aps-mcp-server-nodejs/8a4ee790-3378-44f3-bbab-5acb35ec35ce.pem" ``` ## Usage ### MCP Inspector - Run the [Model Context Protocol Inspector](https://modelcontextprotocol.io/docs/tools/inspector): `npx @modelcontextprotocol/inspector` - Hit `Connect` to connect to the MCP server ### Claude Desktop - Make sure you have [Claude Desktop](https://claude.ai/download) installed - Create a Claude Desktop config file if you don't have one yet: - On macOS: _~/Library/Application Support/Claude/claude\_desktop\_config.json_ - On Windows: _%APPDATA%\Claude\claude\_desktop\_config.json_ - Add this MCP server to the config, using the absolute path of the _server.js_ file on your system, for example: ```json { "mcpServers": { "aps-mcp-server-nodejs": { "command": "node", "args": [ "/path/to/aps-mcp-server-nodejs/server.js" ] } } } ``` - Restart Claude Desktop and verify the server is running in **Settings** → **Developer**:  - Open Claude Desktop, and try some of the following test prompts: - What ACC projects do I have access to? - Give me a visual dashboard of all issues in project XYZ - List all issues in my project - Show me the folder structure - Get detailed information for issue [issue-id] - Create a new issue titled "Test Issue" with status "open" **Example: Visual Dashboard Generation** Claude can create interactive visualizations and dashboards from your ACC data:  The MCP server enables Claude to: - Query real-time project data from ACC - Generate visual dashboards with issue statistics - Create charts showing issues by type, status, and more - Provide detailed project insights through natural conversation > For more details on how to add MCP servers to Claude Desktop, see the [official documentation](https://modelcontextprotocol.io/quickstart/user). ### Visual Studio Code & GitHub Copilot - Make sure you have [enabled MCP servers in Visual Studio Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_enable-mcp-support-in-vs-code) - Create _.vscode/mcp.json_ file in your workspace, and add the following JSON to it: ```json { "servers": { "aps-mcp-server-nodejs": { "type": "stdio", "command": "node", "args": [ "/path/to/aps-mcp-server-nodejs/server.js" ] } } } ``` > For more details on how to add MCP servers to Visual Studio Code, see the [documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) ### Cursor - Create _.cursor/mcp.json_ file in your workspace, and add the following JSON to it: ```json { "mcpServers": { "aps-mcp-server-nodejs": { "command": "node", "args": [ "/path/to/aps-mcp-server-nodejs/server.js" ] } } } ``` > For more details on how to add MCP servers to Cursor, see the [documentation](https://docs.cursor.com/context/model-context-protocol)