# OpenAEC MCP

OpenAEC MCP is an independent, safety-first Model Context Protocol platform for AEC applications. It separates MCP protocol handling from host-specific adapters so AI assistants can inspect, plan, validate, and—only after policy and approval checks—modify engineering documents.

Phase 1 is implemented: the server starts over stdio or authenticated Streamable HTTP, exposes tools/resources/prompts, negotiates capabilities, executes a complete plan → approve → transaction workflow against a synthetic in-memory adapter, emits redacted audit events, and passes protocol and safety tests. Desktop and cloud adapters remain explicitly unavailable until their public host APIs are implemented and verified.

> Engineering disclaimer: AI-generated or automated engineering output is not a substitute for professional judgment. A qualified professional must review and approve work products, assumptions, units, coordinate systems, and applicable standards.

## Architecture

```mermaid
flowchart LR
  Client["MCP client"] -->|"stdio or authenticated Streamable HTTP"| Server["MCP server core"]
  Server --> Catalog["Capability-gated tool catalog"]
  Catalog --> Safety["Safety and approval engine"]
  Safety --> Contract["Language-neutral adapter contract"]
  Contract --> Fake["In-memory CI adapter"]
  Contract -. "future verified adapters" .-> Hosts["AutoCAD · Civil 3D · Revit · QGIS · FreeCAD · APS"]
  Server --> Resources["Resources and prompts"]
  Safety --> Audit["Redacted audit log"]
  Contract --> Validation["Versioned validation rules"]
```

The detailed proposal, interaction model, risk register, milestones, final directory tree, and exact Phase 1 file manifest are in [docs/architecture/phase-1.md](docs/architecture/phase-1.md).

## Current support

| Application / adapter | Status | Capability advertised |
|---|---|---|
| Synthetic in-memory adapter | Implemented and tested | Document reads, line plan/write, transactions, validation |
| AutoCAD | Planned Phase 2 | None |
| Civil 3D | Planned Phase 3 | None |
| QGIS | Planned Phase 4 | None |
| Revit | Planned Phase 4 | None |
| FreeCAD | Planned Phase 4 | None |
| Autodesk Platform Services | Planned Phase 5 | None |

Unsupported applications are never simulated and their tools are not advertised. See [compatibility strategy](docs/adapters/compatibility.md).

## Quick start

Requirements: Node.js 22 or newer.

```sh
npm install
npm run build
node apps/mcp-server/dist/cli.js doctor
node apps/mcp-server/dist/cli.js
```

For a local MCP client after publication:

```json
{
  "mcpServers": {
    "open-aec": {
      "command": "npx",
      "args": ["-y", "@venkatchavan/open-aec-mcp"]
    }
  }
}
```

During repository development, replace the command and arguments with `node` and the absolute path to `apps/mcp-server/dist/cli.js`.

## Remote Streamable HTTP

HTTP binds to loopback by default and refuses to start without a bearer token of at least 32 characters.

```sh
OPENAEC_TRANSPORT=http \
OPENAEC_HTTP_TOKEN='replace-with-at-least-32-random-characters' \
node apps/mcp-server/dist/cli.js
```

Endpoints: `POST /mcp`, `GET /health`, and `GET /ready`. The MCP endpoint requires `Authorization: Bearer …`. Public binding is denied unless explicitly enabled; production remote deployment additionally requires a trusted TLS/authentication gateway.

## Safety workflow

The default mode is `inspect`. It permits reads, calculations, and dry-run plans but blocks approval and execution.

1. Call `aec.geometry.create_line_plan` with explicit units, expected document ID/revision, transaction name, and idempotency key.
2. Review affected objects, warnings, CRS, files, approval requirements, and rollback strategy.
3. In `assisted` mode, call `aec.transaction.approve_change_plan` as an identified operator.
4. Call `aec.transaction.execute_change_plan` with the short-lived, plan-scoped approval token.
5. The engine rechecks policy, expiry, adapter, document revision, object limits, idempotency, and the per-document write lock before dispatch.

The test adapter uses snapshot rollback. Real adapters must use valid host-native transactions, document locks, and main-thread dispatch where required.

## MCP surface

Phase 1 implements nine task-oriented tools under `aec.system.*`, `aec.document.*`, `aec.geometry.*`, `aec.transaction.*`, and `aec.validation.*`. Tool documentation is generated from source metadata with `npm run docs:tools`.

Resources include:

- `aec://applications`
- `aec://documents`
- `aec://documents/{documentId}`
- `aec://documents/{documentId}/validation/latest`
- `aec://capabilities`
- `aec://standards`
- `aec://audit/history`

All 14 requested engineering workflow prompts are registered. See [resources](docs/reference/resources.md) and [prompts](docs/reference/prompts.md).

## CLI

```sh
open-aec-mcp
open-aec-mcp doctor
open-aec-mcp configure
open-aec-mcp list-adapters
open-aec-mcp validate-config ./open-aec.json
```

`doctor` checks Node, parsed configuration, installed adapters, bridge readiness, authentication, port conflicts for HTTP, and transport readiness without printing secrets.

## Development and testing

```sh
npm run verify
npm run test:coverage
```

The test suite covers MCP discovery, policy enforcement, approval, stale revisions, idempotency, rollback, unit conversion, redaction, capability filtering, transport security, and validation reports. Use the official MCP Inspector as described in [docs/testing.md](docs/testing.md).

## Security

Drawing/model text, block attributes, metadata, external references, and linked-model content are untrusted data—not instructions. The server rejects public binding by default, hashes redacted inputs, never exposes a shell/eval tool, and never advertises unavailable host capabilities. Read [SECURITY.md](SECURITY.md) and the [threat model](docs/security/threat-model.md) before enabling writes.

## Roadmap

- Phase 1: core, contracts, fake adapter, safety, audit, configuration, protocol surface, tests—implemented.
- Phase 2: verified AutoCAD public API adapter and packaging.
- Phase 3: verified Civil 3D vertical workflows.
- Phase 4: QGIS, Revit, and FreeCAD adapters.
- Phase 5: APS adapter and hardened remote deployment.
- Phase 6: installers, conformance/performance hardening, signed release artifacts, and registry publishing.

## Limitations

- Only the synthetic adapter is enabled in Phase 1.
- Change plans and approvals are in memory; process restart invalidates them.
- HTTP is stateless at the MCP transport layer; application state is shared in the server runtime.
- Validation rules are examples and advisory, not jurisdiction-specific design standards.
- Binary desktop plugins, installers, signing, APS, and production database persistence are later-phase work.

## Trademark and affiliation disclaimer

OpenAEC MCP is independent community software. It is not affiliated with, endorsed by, sponsored by, or an official product of Autodesk, QGIS.org, the FreeCAD project, or any other vendor. Autodesk, AutoCAD, Civil 3D, Revit, QGIS, FreeCAD, and other product names are trademarks of their respective owners and are used only for truthful compatibility descriptions. No third-party logos are included.

Licensed under Apache-2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE), and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).