Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.
Python aecai-agentsautodeskautomationbimclaudeifcmcpmcp-servermodel-context-protocolnavisworksrevitrevit-addinrevit-apirhino
chore: tidy repo, add community-health files and a docs index
sammohammad5786f04a092bb93
diff --git a/.gitattributes b/.gitattributesindex dfe0770..ad1b5a8 100644--- a/.gitattributes+++ b/.gitattributes@@ -1,2 +1,16 @@-# Auto detect text files and perform LF normalization+# Text files are stored with LF in the repository.* text=auto++# Binary assets: never converted.+*.png binary+*.ico binary+*.bmp binary++# Windows-native formats keep CRLF in the working tree.+*.sln text eol=crlf++# Stay LF on every checkout (run in containers and CI).+Dockerfile text eol=lf+*.sh text eol=lf+*.yml text eol=lf+*.yaml text eol=lfdiff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlnew file mode 100644index 0000000..e021cc9--- /dev/null+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -0,0 +1,66 @@+name: Bug report+description: Something does not work as documented.+title: "[Bug]: "+labels: ["bug"]+body:+ - type: markdown+ attributes:+ value: |+ Thanks for the report. For security problems, do not open an issue. Use the private reporting steps in [SECURITY.md](https://github.com/Sam-AEC/aec-model-bridge/blob/main/SECURITY.md).+ - type: textarea+ id: what-happened+ attributes:+ label: What happened+ description: What you did, what you expected, and what you got instead.+ validations:+ required: true+ - type: textarea+ id: steps+ attributes:+ label: Steps to reproduce+ placeholder: |+ 1. Open a model in Revit 2026+ 2. Ask the assistant to ...+ 3. See the error+ validations:+ required: true+ - type: input+ id: version+ attributes:+ label: AEC Model Bridge version+ description: From the release name, or `python -m pip show aec-model-bridge`.+ placeholder: "1.3.2"+ validations:+ required: true+ - type: dropdown+ id: host+ attributes:+ label: Host application+ options:+ - Revit 2024+ - Revit 2025+ - Revit 2026+ - Revit 2027+ - Rhino / Grasshopper+ - Navisworks+ - IFC files only (no host)+ - Other+ validations:+ required: true+ - type: input+ id: client+ attributes:+ label: MCP client+ description: The client you connect with, and its version.+ placeholder: Claude Desktop 1.x, VS Code, Codex, ...+ - type: input+ id: os-python+ attributes:+ label: Windows and Python version+ placeholder: Windows 11, Python 3.11+ - type: textarea+ id: logs+ attributes:+ label: Logs or error output+ description: Remove file paths, project names and anything confidential first.+ render: textdiff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 0000000..0731ba7--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,5 @@+blank_issues_enabled: true+contact_links:+ - name: Report a security vulnerability+ url: https://github.com/Sam-AEC/aec-model-bridge/security/advisories/new+ about: Please report security problems privately, not as a public issue.diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.ymlnew file mode 100644index 0000000..d24fee5--- /dev/null+++ b/.github/ISSUE_TEMPLATE/feature_request.yml@@ -0,0 +1,38 @@+name: Feature request+description: Suggest a new tool, workflow or improvement.+title: "[Feature]: "+labels: ["enhancement"]+body:+ - type: textarea+ id: problem+ attributes:+ label: What are you trying to do+ description: Describe the task or problem, not the solution.+ validations:+ required: true+ - type: textarea+ id: proposal+ attributes:+ label: What you would like+ description: The tool, option or behaviour you have in mind, if any.+ - type: textarea+ id: alternatives+ attributes:+ label: What you do today+ description: Workarounds or other tools you have tried.+ - type: dropdown+ id: area+ attributes:+ label: Area+ options:+ - Revit tools+ - Rhino / Grasshopper+ - Navisworks+ - IFC / Speckle+ - Approval flow and security+ - Install and documentation+ - Other+ - type: markdown+ attributes:+ value: |+ If you plan to send a code pull request, please read [CONTRIBUTING.md](https://github.com/Sam-AEC/aec-model-bridge/blob/main/CONTRIBUTING.md) first. Code contributions need a signed contributor agreement.diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdnew file mode 100644index 0000000..4646489--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -0,0 +1,16 @@+## What this changes++<!-- One or two sentences. Link the issue it relates to. -->++## Checklist++- [ ] I opened or commented on an issue first, and signed the contributor agreement if this changes code (see [CONTRIBUTING.md](../CONTRIBUTING.md)).+- [ ] The change is scoped to one feature, fix or documentation update.+- [ ] `python -m ruff check packages/mcp-server-revit/src packages/mcp-server-revit/tests` passes.+- [ ] `python -m pytest packages/mcp-server-revit/tests` passes.+- [ ] Docs and examples are updated if behaviour changed.+- [ ] Local paths, machine names and credentials are removed from examples and logs.++## Revit and host versions tested++<!-- For example: Revit 2026 with the add-in built from this branch. Write "not applicable" for docs-only changes. -->diff --git a/.github/dependabot.yml b/.github/dependabot.ymlnew file mode 100644index 0000000..71f555e--- /dev/null+++ b/.github/dependabot.yml@@ -0,0 +1,37 @@+version: 2+updates:+ - package-ecosystem: pip+ directory: /packages/mcp-server-revit+ schedule:+ interval: weekly+ open-pull-requests-limit: 3++ - package-ecosystem: nuget+ directory: /packages/revit-bridge-addin+ schedule:+ interval: weekly+ open-pull-requests-limit: 2++ - package-ecosystem: nuget+ directory: /packages/rhino-bridge-addin+ schedule:+ interval: weekly+ open-pull-requests-limit: 2++ - package-ecosystem: nuget+ directory: /packages/navisworks-bridge-addin+ schedule:+ interval: weekly+ open-pull-requests-limit: 2++ - package-ecosystem: nuget+ directory: /packages/powerbi-bridge-tool+ schedule:+ interval: weekly+ open-pull-requests-limit: 2++ - package-ecosystem: github-actions+ directory: /+ schedule:+ interval: weekly+ open-pull-requests-limit: 3diff --git a/.gitignore b/.gitignoreindex fc5b987..96d19fb 100644--- a/.gitignore+++ b/.gitignore@@ -242,3 +242,34 @@ fixtures/canonical-model/generated/+# Scratch, backups and OS/sync clutter+scratch/+*.bak+*.orig+*.rej+*.disabled+*.disabled-*+*~+~$*+Thumbs.db+desktop.ini+.OneDrive*++# Packaging output+*.egg+.eggs/+*.whl+*.mcpb+*.nupkg++# Python virtual environments and tooling caches+.venv*/+.uv-cache/+.pytest_cache/++# JetBrains Rider+.idea_modules/+riderModule.iml++# Claude Code worktrees+.claude/worktrees/diff --git a/CITATION.cff b/CITATION.cffnew file mode 100644index 0000000..9d83564--- /dev/null+++ b/CITATION.cff@@ -0,0 +1,16 @@+cff-version: 1.2.0+message: "If you use AEC Model Bridge in your work, please cite it as below."+title: "AEC Model Bridge"+abstract: "An open-source Model Context Protocol server and native Revit add-in that lets AI assistants read and edit BIM models, with the user approving every change."+type: software+authors:+ - family-names: Mohammad+ given-names: A. Sam+repository-code: "https://github.com/Sam-AEC/aec-model-bridge"+url: "https://github.com/Sam-AEC/aec-model-bridge"+license: GPL-3.0-or-later+keywords:+ - mcp+ - revit+ - bim+ - aidiff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.mdnew file mode 100644index 0000000..fb08c9f--- /dev/null+++ b/CODE_OF_CONDUCT.md@@ -0,0 +1,37 @@+# Code of Conduct++This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).++## Our pledge++We want participation in this project to be a respectful, harassment-free experience for everyone, whatever their age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, appearance, race, religion, or sexual identity and orientation.++## Expected behaviour++- Be kind and patient, and assume good intent.+- Give and accept constructive feedback.+- Focus on what is best for the project and the people using it.+- Keep discussion on topic and free of personal attacks.++## Unacceptable behaviour++- Harassment, insults, or discriminatory jokes and language.+- Sexualised language or imagery, and unwelcome sexual attention.+- Trolling, deliberate disruption, or personal and political attacks.+- Publishing someone else's private information without permission.+- Other conduct that would reasonably be considered inappropriate in a professional setting.++## Enforcement++The maintainer is responsible for clarifying and enforcing these standards. They may remove, edit or reject comments, commits, issues and other contributions that do not follow this Code of Conduct, and may temporarily or permanently ban anyone whose behaviour is harmful.++This applies in all project spaces (issues, pull requests, discussions) and when someone is representing the project in public.++## Reporting++Report unacceptable behaviour to the maintainer, A. Sam Mohammad, at+[[email protected]](mailto:[email protected]). Reports are handled in confidence. Security vulnerabilities are a separate matter; follow [SECURITY.md](SECURITY.md) for those.++## Attribution++Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.mdindex 68c9b2d..deb2aff 100644--- a/CONTRIBUTORS.md+++ b/CONTRIBUTORS.md@@ -2,6 +2,6 @@Thanks to everyone who has helped improve AEC Model Bridge.-- [Yuhan Jiang](https://github.com/jyh100) — curated the [`Hermes.json`](Hermes.json) tool+- [Yuhan Jiang](https://github.com/jyh100) — curated the [`hermes-desktop.json`](docs/examples/hermes-desktop.json) toolsubset for running Hermes Desktop against local Ollama models([#19](https://github.com/Sam-AEC/aec-model-bridge/pull/19)).diff --git a/README.md b/README.mdindex cb605d4..721508c 100644--- a/README.md+++ b/README.md@@ -279,7 +279,7 @@ Set it to a year such as `2024` or `2026` to lock a client entry to that Revitversion. `MCP_REVIT_BRIDGE_URL` overrides the endpoint for advanced setups.VS Code users can start from [`.vscode/mcp.json`](.vscode/mcp.json). Hermes-Desktop users can start from [`Hermes.json`](Hermes.json) after replacing the+Desktop users can start from [`docs/examples/hermes-desktop.json`](docs/examples/hermes-desktop.json) after replacing theplaceholder Python path. Clients that support MCP Bundles can install the`.mcpb` file from the[latest release](https://github.com/Sam-AEC/aec-model-bridge/releases/latest).@@ -386,7 +386,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.- [Security](docs/security.md)- [MCP clients and registry](docs/marketplaces.md)- [Versioning and releases](docs/versioning.md)-- [Contributing](CONTRIBUTING.md)+- [All documentation](docs/README.md)+- [Contributing](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md)- [Contributors](CONTRIBUTORS.md)## Project and licensediff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 0000000..c08b2b6--- /dev/null+++ b/docs/README.md@@ -0,0 +1,39 @@+# Documentation index++Start with the [installation guide](install.md). The main [README](../README.md) covers what the project is and how to connect a client.++## Guides and reference++- [install.md](install.md): install the Revit add-in and the MCP server.+- [configuration-reference.md](configuration-reference.md): environment variables, package metadata and runtime settings.+- [tools-generated.md](tools-generated.md): the tool catalog, generated from the server (do not edit by hand).+- [security.md](security.md): trust boundaries, workspace sandboxing and enterprise hardening.+- [logging-and-audit.md](logging-and-audit.md): Python-side audit log and add-in logging.+- [marketplaces.md](marketplaces.md): MCP Registry, bundle and client distribution.+- [versioning.md](versioning.md): version numbers, release tags and release assets.++## For contributors++- [module-authoring.md](module-authoring.md): write a plugin module (commands, schemas, QA rules).+- [build-and-install-scripts.md](build-and-install-scripts.md): what each script in `scripts/` does.+- [target-frameworks-and-dependencies.md](target-frameworks-and-dependencies.md): Python and .NET targets per component.+- [revit-addin-lifecycle.md](revit-addin-lifecycle.md): how the Revit add-in starts up and runs commands.+- [design/tokens.md](design/tokens.md): design tokens for the add-in and panel UI ([design/review.html](design/review.html) is the visual review page).+- [examples/hermes-desktop.json](examples/hermes-desktop.json): sample client config for Hermes Desktop.++## Architecture decision records++- [0001](0001-multi-provider-architecture.md): multi-provider automation architecture.+- [0002](0002-switch-contract-v2.md): switch contract v2.+- [0007](0007-hub-performance-posture.md): hub performance posture.+- [0008](0008-approval-gate-lifecycle.md): approval gate and action plan lifecycle.+- [0009](0009-plugin-module-system.md): plugin module system.+- [0010](0010-snapshot-schema.md): semantic BIM snapshot and delta schema.+- [0011](0011-panel-architecture.md): WebView2 dockable panel and hub message bridge.+- [0012](0012-native-agent-chat-backend.md): native tool-calling loop for chat.++Numbers 0003 to 0006 are not in this repository.++## Diagrams++- [diagrams/](diagrams/): Mermaid sources for the architecture and approval-flow diagrams in the README. [images/](images/) holds the rendered light and dark PNGs; regenerate them with `scripts/render_diagrams.py`.diff --git a/Hermes.json b/docs/examples/hermes-desktop.jsonsimilarity index 100%rename from Hermes.jsonrename to docs/examples/hermes-desktop.json