convez.ai
MCP ServerIntegração & APIsAvançado
KenLP

ACC Forma MCP Server

KenLP/acc-forma-mcp-server

Conecta Claude ao Autodesk Forma com segurança, auditoria e dry-run

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP seguro para integração com Autodesk Forma (Autodesk Construction Cloud). Oferece leitura e escrita completa em issues, reviews e dados BIM com dry-run preview, auditoria tamper-evident e governança de permissões por projeto.

Instalação

$npx convez-ai KenLP/acc-forma-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
v0.3.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automatizar criação e atualização de issues em projetos de construção
  • Consultar dados BIM e posicionamento de elementos AECDM
  • Gerenciar reviews e comentários com rastreamento de auditoria
  • Integrar fluxos de trabalho de construção digital no Claude

Veredito

Excelente integração empresarial para o ecossistema AEC. Diferenciam-se por implementar dry-run, auditoria hash-chain e governança per-tool — recursos ausentes em servidores concorrentes. Requer setup inicial rigoroso de credenciais APS e permissões de projeto.

README

A tradução para o português deste README ainda está na fila.

acc-forma-mcp-server

Safety-first MCP server for Autodesk Forma (formerly Autodesk Construction Cloud). Every write is dry-runnable, audit-logged, and scope-guarded.

Read everything · Preview every write · Audit every action.

CI License: MIT Node ≥20


Why this server?

CapabilityOther ACC/APS MCP serversacc-forma-mcp-server
Issues read + write (full CRUD + comments + attachments)Partial✅
Reviews read + writePartial✅
AEC Data Model (BIM element queries)Separate .NET server only✅
AECDM element position queries (Issue pushpin support)❌✅
Dry-run preview before any write❌✅
Tamper-evident audit log (JSONL + hash chain)❌✅
Project/hub allow-list enforcement❌✅
Read-only mode toggle (FORMA_READONLY=true)❌✅
Per-tool hourly rate governance❌✅
Business-rule validators❌✅
TypeScript strict modePartial✅

Quickstart

Step 1 — APS credentials (one-time)

You need an Autodesk Platform Services (APS) application with an SSA (Secure Service Account). SSA is a bot identity that can be scoped to specific projects without a human login.

See docs/AUTH.md for the full walkthrough. Quick summary:

  1. Create an app at aps.autodesk.com → enable Autodesk Construction Cloud APIs
  2. App → Security → Service Accounts → generate key pair → download the PEM private key (never commit it)
  3. Note your APS_CLIENT_ID, APS_CLIENT_SECRET, SSA_ID, SSA_KEY_ID, and the path to the PEM file
  4. Hub Admin → Members → invite the SSA email → assign Project Admin role
  5. Hub Admin → Custom Integrations → add your app by Client ID (required — without this, all project calls return 403)

Step 2 — Configure env

Create a .env file in the project root (or pass these as env vars in your MCP client config — see Step 3):

APS_AUTH_MODE=ssa
APS_CLIENT_ID=your_client_id
APS_CLIENT_SECRET=your_client_secret
SSA_ID=your_ssa_id
SSA_KEY_ID=your_key_id
SSA_KEY_PATH=/absolute/path/to/private-key.pem

Full variable reference: Configuration

Step 3 — Add to your MCP client

This server communicates over stdio (JSON-RPC). It is spawned by your MCP client — not run standalone in a terminal.

Option A — npx (no clone needed; requires the package to be published on npm)

{
  "mcpServers": {
    "forma": {
      "command": "npx",
      "args": ["-y", "acc-forma-mcp-server"],
      "env": {
        "APS_CLIENT_ID": "your_client_id",
        "APS_CLIENT_SECRET": "your_client_secret",
        "APS_AUTH_MODE": "ssa",
        "SSA_ID": "your_ssa_id",
        "SSA_KEY_ID": "your_key_id",
        "SSA_KEY_PATH": "/absolute/path/to/private-key.pem"
      }
    }
  }
}

Option B — Clone and build locally

git clone https://github.com/KenLP/acc-forma-mcp-server.git
cd acc-forma-mcp-server
pnpm install
pnpm build

Then point your MCP client at the built file:

{
  "mcpServers": {
    "forma": {
      "command": "node",
      "args": ["/absolute/path/to/acc-forma-mcp-server/dist/index.js"],
      "env": {
        "APS_CLIENT_ID": "your_client_id",
        "APS_CLIENT_SECRET": "your_client_secret",
        "APS_AUTH_MODE": "ssa",
        "SSA_ID": "your_ssa_id",
        "SSA_KEY_ID": "your_key_id",
        "SSA_KEY_PATH": "/absolute/path/to/private-key.pem"
      }
    }
  }
}

Tip: Pass credentials via env in the MCP client config (as shown above) rather than relying on a .env file. The working directory when your client spawns the process may not be the repo root.

MCP client config file locations

ClientConfig path
Claude Desktop (macOS)~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)%APPDATA%\Claude\claude_desktop_config.json
VS Code (MCP extension).vscode/mcp.json in your workspace

Available Tools

Tools (38)

All tools are grouped by domain. Read tools take no approval; write/mutation tools (marked ✍️) follow the two-call dry-run protocol.

Account Admin (4)

ToolPurpose
admin_list_projectsList all projects under a hub (hub-wide visibility via 2LO).
admin_get_projectFetch a single project's metadata, scopes, and relationships.
admin_list_usersList users in the account / project membership.
admin_list_companiesList companies registered on the account.

Data Management (6)

ToolPurpose
dm_list_hubsList ACC/BIM 360 hubs accessible to the app.
dm_list_projectsList projects in a hub.
dm_list_top_foldersList the top-level folders of a project (Plans, Project Files, etc.).
dm_list_folder_contentsList items (files + subfolders) in a folder.
dm_get_itemGet metadata for a single item (file or folder).
dm_list_versionsList all versions of a file with version numbers and timestamps.

Issues (11)

ToolPurpose
issues_listList issues in a project with filters (status, type, assignee).
issues_getGet a single issue with full details, including permittedStatuses and permittedAttributes for the current user.
issues_create ✍️Create a new issue with subtype, location, due date, assignment, and optional pushpin links.
issues_update ✍️Update an existing issue — status, title, description, assignee, due date, subtype, location (sparse PATCH; only provided fields change).
issues_add_comment ✍️Add a comment to an existing issue.
issues_list_commentsList the comment thread on an issue, paginated.
issues_list_typesList valid issue types and subtypes (with isActive flag) for a project.
issues_list_root_causesList configured root cause categories for a project.
issues_get_user_meGet the current identity's permission flags for the Issues module (canCreate, canUpdate, canCreateComments).
issues_list_attrsList custom attribute definitions for a project — use to get UUIDs needed by customAttributes in create/update.
issues_list_attachmentsList files and links attached to an issue, paginated.

Status values (confirmed from live ACC API): draft | open | pending | in_review | closed | void. Valid transitions depend on the project workflow — check permittedStatuses from issues_get before updating.

Reviews (4)

ToolPurpose
reviews_listList reviews in a project's Reviews container.
reviews_getGet a single review including status and reviewers.
reviews_create ✍️Create a new review with reviewers, due date, workflow, linked documents.
reviews_transition ✍️Submit / approve / reject / void / reopen a review.

AEC Data Model — BIM GraphQL (8)

ToolPurpose
aecdm_list_hubsList AECDM-native hubs (distinct from DM hubs). Start here for any AECDM workflow.
aecdm_list_projectsList projects in an AECDM hub.
aecdm_list_element_groupsList BIM model files (Revit/IFC) published to an AECDM project, including fileVersionUrn.
aecdm_list_categoriesList BIM categories present in an element group (Walls, Structural Columns, MEP equipment, etc.) by parallel-probing ~60 well-known Revit categories.
aecdm_query_elementsQuery BIM elements by category with full properties. Supports multi-word categories like Structural Columns, Electrical Equipment.
aecdm_get_element_propertiesRe-fetch full properties for a specific element by node ID (requires the originating category).
aecdm_aggregate_by_parameterCount elements grouped by a parameter value within a category (e.g. walls by type name) — fast take-off queries.
aecdm_query_element_positionsQuery elements with origin position (x, y, z) decoded from geometry transform. Primary use: populate ACC Issue pushpins (linked_documents[].details.position). Optionally filter by a reference bounding box. NOTE: returns an origin point (not an AABB). Only point-placed elements (Pipe Fittings, Fixtures, Columns, Doors) have geometry data — linear (Pipes, Ducts) and planar (Walls, Floors) elements return position: null. Uses the AECDM geometryDataByElements Public Beta field.

Model Derivative — SVF2 Translation (3)

ToolPurpose
md_get_manifestCheck SVF2 translation status and list available 3D/2D view GUIDs for a model version.
md_get_propertiesFetch Revit element properties (names, parameters, category) from an SVF2-translated model. Supports category and objectId filters.
md_trigger_translation ✍️Submit a new SVF2 translation job for a model version. Poll with md_get_manifest.

Note: bounding boxes are NOT available from the MD Properties API for any SVF2 model — this is an APS platform limitation. For element bboxes, the Model Properties API (/construction/index/v2/) is the correct path (requires 3LO auth — Phase 3).

Meta / Observability (2)

ToolPurpose
meta_list_changelogRead the local audit log entries with filters by tool, time, or project.
meta_verify_audit_chainVerify the audit log hash chain has not been tampered with.

More tools in Phase 3 (Model Properties API — bbox/clash; 3LO auth required).


Safety Guardrails

1. Dry-run by default

Every mutation tool defaults to dry_run=true. On first call, the server:

  • Validates allow-lists, read-only mode, rate limits, business rules
  • Resolves the exact APS API request (method, URL, body)
  • Returns a preview + single-use approval_token
  • Does not call APS

To execute, re-call the same tool with dry_run=false, approval_token=<token>.

Claude: "Create an issue titled 'Leak at Level 3' in project xyz"

Tool: issues_create(dry_run=true)
→ {
    preview: { method: "POST", url: "...issues", body: {...} },
    approval_token: "appr_01JXW...",
    next_step: "Re-call with dry_run=false and approval_token to execute"
  }

Tool: issues_create(dry_run=false, approval_token="appr_01JXW...")
→ Issue created: ID abc-456

2. Tamper-evident audit log

All tool calls are appended to ~/.acc-forma-mcp/audit/audit-YYYY-MM-DD.jsonl with SHA-256 hash chaining. Verify integrity at any time:

# Using the MCP tool
meta_verify_audit_chain()

# Or read the JSONL directly — one JSON object per line
cat ~/.acc-forma-mcp/audit/audit-$(date +%F).jsonl | jq .

3. Project allow-list

FORMA_ALLOWED_PROJECTS=proj-uuid-1,proj-uuid-2
FORMA_ALLOWED_HUBS=hub-id-1

The server rejects any tool call referencing a project/hub outside this list — independent of SSA permissions.

4. Read-only mode

FORMA_READONLY=true
# or
FORMA_MUTATION_MODE=readonly

Blocks all mutation tools instantly, without touching APS.

5. Mutation modes

FORMA_MUTATION_MODEBehavior
preview_required (default)Must dry_run=true first; re-call with approval_token
client_approval_onlySingle call; trust MCP client's built-in approval UI
readonlyAll mutations blocked

Configuration

Copy .env.example to .env and fill in your values. All options documented with comments in .env.example.

Key variables:

VariableDefaultDescription
APS_CLIENT_ID—Required
APS_CLIENT_SECRET—Required
APS_AUTH_MODEssassa, 2lo, or 3lo (3lo: Phase 3)
SSA_ID—Required for SSA mode
SSA_KEY_ID—Required for SSA mode
SSA_KEY_PATH—Path to PEM private key file
FORMA_READONLYfalseBlock all mutations
FORMA_MUTATION_MODEpreview_requiredSee Safety section
FORMA_ALLOWED_HUBS*Comma-separated hub IDs
FORMA_ALLOWED_PROJECTS*Comma-separated project UUIDs
FORMA_AUDIT_DIR~/.acc-forma-mcp/auditJSONL audit log directory
FORMA_AUDIT_FAIL_CLOSEDfalseSurface audit write failures as errors. When true and the write fails after an APS mutation, the response indicates whether the change was applied.

Development

# Install
pnpm install

# Build
pnpm run build

# Type check
pnpm run typecheck

# Tests
pnpm run test

# Watch mode
pnpm run test:watch

License

MIT — see LICENSE.

Not affiliated with Autodesk, Inc. Autodesk Forma®, Autodesk Construction Cloud®, and Autodesk Platform Services® are trademarks of Autodesk, Inc.

Ver o original no GitHub

Bom para

Relacionados