@rui.branco/revit-mcp 1.0.0

package/lib/bridge.js

@@ -0,0 +1,161 @@
+// HTTP client for the Revit-side bridge.
+//
+// Node cannot call the Revit API: it is in-process .NET inside revit.exe. So
+// every tool call becomes a small JSON POST to the bridge add-in listening on
+// localhost, which does the Revit work and answers with compact JSON.
+//
+// The whole point of this module is that the model never sees a raw socket
+// error. Each failure mode gets a message that says what is broken and what to
+// do about it.
+
+import http from "http";
+
+const DEFAULT_URL = "http://localhost:48884/revit-mcp";
+const DEFAULT_TIMEOUT_MS = 30000;
+
+// Raw POST. Resolves { statusCode, body } for ANY status code — status handling
+// belongs to call(), which knows the endpoint and can phrase a useful error.
+// Rejects only on transport failure (refused, reset, timeout).
+function httpRequest(url, payload, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const data = JSON.stringify(payload);
+    const req = http.request(
+      {
+        hostname: target.hostname,
+        port: target.port || 80,
+        path: target.pathname + target.search,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(data),
+        },
+      },
+      (res) => {
+        let body = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => (body += chunk));
+        res.on("end", () => resolve({ statusCode: res.statusCode, body }));
+      },
+    );
+    // Covers both "never connected" and "connected, then went quiet" — the
+    // second is what a modal dialog in Revit looks like from out here.
+    req.setTimeout(timeoutMs, () => {
+      const err = new Error(`no response within ${timeoutMs}ms`);
+      err.code = "ETIMEDOUT";
+      req.destroy(err);
+    });
+    req.on("error", reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+// The bridge reports handler failures as a JSON body with an `error` key,
+// either a bare string or { code, message, stack }. Returns null when the body
+// is not an error payload.
+function handlerError(parsed) {
+  if (!parsed || typeof parsed !== "object") return null;
+  const error = parsed.error;
+  if (!error) return null;
+  if (typeof error === "string") return { code: "", message: error, stack: "" };
+  return {
+    code: error.code || "",
+    message: error.message || "unknown error",
+    stack: error.stack || error.stackTrace || "",
+  };
+}
+
+// The only two codes that mean "this URL is not a route here". The router
+// answers an unrecognised path with UNKNOWN_PATH and an unrecognised route name
+// with UNKNOWN_ENDPOINT; every other 404 comes from a handler that ran and
+// found nothing (ELEMENT_NOT_FOUND, PARAMETER_NOT_FOUND, ...). Those two cases
+// need opposite advice, so the status code alone cannot decide it.
+const ROUTE_MISSING_CODES = new Set(["UNKNOWN_PATH", "UNKNOWN_ENDPOINT"]);
+
+function noHandlerMessage(endpoint, baseUrl, detail) {
+  return (
+    `Revit answered but has no handler for ${endpoint} (HTTP 404). Something is listening on ${baseUrl}, so the bridge add-in is not loaded or is an older build. Check the .addin manifest in %APPDATA%\\Autodesk\\Revit\\Addins\\<version>\\ and restart Revit.` +
+    (detail ? `\n${detail}` : "")
+  );
+}
+
+export function createBridge({ url, timeoutMs, request = httpRequest } = {}) {
+  // Trailing slashes make the joined path double up, and REVIT_MCP_URL is
+  // hand-typed often enough to be worth normalising here.
+  const baseUrl = (url || process.env.REVIT_MCP_URL || DEFAULT_URL).replace(
+    /\/+$/,
+    "",
+  );
+  const timeout =
+    timeoutMs ||
+    Number(process.env.REVIT_MCP_TIMEOUT) ||
+    DEFAULT_TIMEOUT_MS;
+
+  return {
+    baseUrl,
+    timeoutMs: timeout,
+
+    async call(endpoint, payload = {}) {
+      let response;
+      try {
+        response = await request(`${baseUrl}${endpoint}`, payload, timeout);
+      } catch (err) {
+        if (err.code === "ETIMEDOUT" || err.code === "ESOCKETTIMEDOUT") {
+          throw new Error(
+            `Revit did not answer ${endpoint} within ${timeout}ms. Revit is busy or blocked on a modal dialog — switch to Revit, dismiss any open dialog, and retry. Set REVIT_MCP_TIMEOUT (milliseconds) higher for long operations.`,
+          );
+        }
+        if (err.code === "ECONNREFUSED") {
+          throw new Error(
+            `Cannot reach Revit at ${baseUrl} — connection refused. Revit is not running, or the revit-mcp bridge add-in is not listening. Start Revit and confirm the add-in loaded, then retry. Override the address with REVIT_MCP_URL.`,
+          );
+        }
+        throw new Error(
+          `Cannot reach Revit at ${baseUrl} — ${err.code || "request failed"}: ${err.message}`,
+        );
+      }
+
+      let parsed;
+      try {
+        parsed = JSON.parse(response.body);
+      } catch {
+        // A 404 that is not even JSON is not this bridge answering.
+        if (response.statusCode === 404) {
+          throw new Error(noHandlerMessage(endpoint, baseUrl, ""));
+        }
+        throw new Error(
+          `Revit returned a non-JSON response for ${endpoint} (HTTP ${response.statusCode}): ${response.body.slice(0, 200)}`,
+        );
+      }
+
+      // A handler that blew up inside Revit — surface the Revit-side code,
+      // message and stack verbatim, that is the only place the real cause
+      // exists.
+      const failure = handlerError(parsed);
+
+      if (
+        response.statusCode === 404 &&
+        (!failure || ROUTE_MISSING_CODES.has(failure.code))
+      ) {
+        throw new Error(
+          noHandlerMessage(endpoint, baseUrl, failure ? failure.message : ""),
+        );
+      }
+
+      if (failure) {
+        throw new Error(
+          `Revit failed on ${endpoint}: ${failure.code ? `${failure.code} — ` : ""}${failure.message}${failure.stack ? `\n${failure.stack}` : ""}`,
+        );
+      }
+
+      if (response.statusCode >= 400) {
+        throw new Error(
+          `Revit returned HTTP ${response.statusCode} for ${endpoint}: ${response.body.slice(0, 200)}`,
+        );
+      }
+
+      return parsed;
+    },
+  };
+}

package/lib/tools/detail.js

@@ -0,0 +1,86 @@
+// Detail linework and annotation: what a detail sheet is actually made of.
+//
+// Nothing here touches the model. A detail line and a text note are
+// view-specific elements that exist in exactly one view, which is the whole
+// point of a drafting view — see revit_create_drafting_view.
+//
+// Coordinates are the view's own plan coordinates in feet (Revit internal
+// units). The elevation is supplied by the bridge, because Revit refuses a
+// detail curve that is not in the plane of the view, and the response says
+// which elevation it used.
+
+import { z } from "zod";
+
+const point2 = z.object({ x: z.number(), y: z.number() });
+
+export function registerDetailTools(server, bridge) {
+  server.tool(
+    "revit_draw_detail_lines",
+    "Draw detail lines in a drafting view or a plan — the linework of a construction detail. Coordinates are x/y in feet (Revit internal units); the bridge puts them in the plane of the view for you. 'line_style' names a line style loaded in the document ('Thin Lines', 'Medium Lines', whatever the template has); an unknown one is not an error — the lines are drawn in the default style and the response lists 'availableLineStyles' so you can correct it. A section, an elevation or a 3D view is refused with VIEW_CANNOT_HOST_DETAIL. Pass every line in one call: the whole batch is one undo step, and a line Revit refuses comes back under 'failed' with its index while the rest are still drawn.",
+    {
+      view_id: z
+        .number()
+        .int()
+        .describe("Drafting view or plan view id, from revit_list_views or revit_create_drafting_view"),
+      lines: z
+        .array(
+          z.object({
+            start: point2.describe("Start point in feet"),
+            end: point2.describe("End point in feet"),
+          }),
+        )
+        .min(1)
+        .describe("Lines to draw, all in this one call"),
+      line_style: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Line style name, e.g. 'Thin Lines'. Unknown names fall back to the default and are reported."),
+    },
+    async ({ view_id, lines, line_style }) => {
+      try {
+        // The tool arguments stay snake_case like every other tool's; the bridge
+        // reads viewId / lineStyle — map them here rather than on the C# side.
+        const result = await bridge.call("/detail/lines", {
+          viewId: view_id,
+          lines,
+          lineStyle: line_style,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_add_text_notes",
+    "Add text notes to a view — the annotation on a detail, a plan or a section. x/y are in feet (Revit internal units) and place the top-left corner of the note; the bridge puts them in the plane of the view. 'size' is the text height in feet on the PAPER (2.5 mm is 0.0082), and because Revit keeps text size on the type rather than the note, a size no loaded type carries gets a duplicated type — once per distinct size, reused on later calls. Schedules, sheets and view templates are refused with VIEW_CANNOT_HOST_TEXT. Pass every note in one call: the whole batch is one undo step, and a note Revit refuses comes back under 'failed' with its index.",
+    {
+      view_id: z.number().int().describe("View id from revit_list_views or revit_create_drafting_view"),
+      notes: z
+        .array(
+          z.object({
+            x: z.number().describe("X in feet"),
+            y: z.number().describe("Y in feet"),
+            text: z.string().min(1).describe("The text of the note"),
+            size: z
+              .number()
+              .positive()
+              .optional()
+              .describe("Text height in feet on the paper, e.g. 0.0082 for 2.5 mm. Omit for the default type."),
+          }),
+        )
+        .min(1)
+        .describe("Notes to place, all in this one call"),
+    },
+    async ({ view_id, notes }) => {
+      try {
+        const result = await bridge.call("/detail/text", { viewId: view_id, notes });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+}

package/lib/tools/diagnostics.js

@@ -0,0 +1,57 @@
+// Diagnostics: what the bridge answered on your behalf while you were not
+// looking.
+//
+// Unattended operation only works because the bridge clicks Revit's modal
+// dialogs and resolves its transaction warnings itself — otherwise Revit's main
+// thread parks on a dialog nobody is there to read and every call after it
+// times out. That is a trade, not a free win: a warning Revit raised and the
+// bridge resolved may mean the model did something the caller never asked for.
+// So suppressed is not swallowed — it all goes into a ring buffer on the Revit
+// side, and these are the tools that read it and switch it off.
+
+import { z } from "zod";
+
+export function registerDiagnosticsTools(server, bridge) {
+  server.tool(
+    "revit_diagnostics",
+    "Read what the bridge suppressed: the Revit dialogs it answered automatically and the transaction warnings it resolved, oldest first, plus whether auto-dismiss is currently on. CHECK THIS AFTER EVERY BATCH OF WRITES. A silently resolved warning usually means Revit changed something you did not ask for — walls joined differently, an element deleted as a side effect of another — and this buffer is the only record of it. An empty dialogs/failures list means the writes went through cleanly.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/diagnostics");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_set_auto_dismiss",
+    "Turn automatic dialog dismissal on or off, and optionally empty the diagnostics buffer. It is ON by default and that is what makes unattended runs possible: Revit's dialogs get an answer (OK, or Cancel for anything that sounds destructive) instead of parking Revit until a human clicks. Turn it OFF when somebody is working in Revit at the same time and should answer their own dialogs — with it off, a dialog makes calls fail with REVIT_BUSY until it is dismissed by hand. Clearing the buffer before a batch of writes makes the following revit_diagnostics show only that batch.",
+    {
+      enabled: z
+        .boolean()
+        .describe(
+          "true = the bridge answers Revit's dialogs itself (the default); false = dialogs wait for a human and calls time out meanwhile",
+        ),
+      clear: z
+        .boolean()
+        .default(false)
+        .describe("Also empty the dialog/warning buffer that revit_diagnostics reads"),
+    },
+    async ({ enabled, clear }) => {
+      try {
+        // The tool argument stays snake_case-free and plain, but the bridge
+        // reads `autoDismiss` — map it here rather than on the C# side.
+        const result = await bridge.call("/diagnostics/config", {
+          autoDismiss: enabled,
+          clear,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+}

package/lib/tools/document.js

@@ -0,0 +1,149 @@
+// Document-level tools: the lifecycle of the document itself — new, open,
+// save, save as, close.
+//
+// Unlike the write tools none of these is a model edit or an undo step —
+// creating, saving, opening and closing a document cannot happen inside a Revit
+// transaction — and revit_new_project / revit_open_project are the tools that
+// work with no document open, which is exactly the state Revit is in when
+// somebody asks for a new project.
+
+import { z } from "zod";
+
+// Revit ships its templates per version under ProgramData. The metric/English
+// one is the sane default: metric units with English level and parameter names,
+// so everything else in this MCP reads the way the user expects.
+export const DEFAULT_TEMPLATE_PATH =
+  "C:\\ProgramData\\Autodesk\\RVT 2027\\Templates\\Default_M_ENG.rte";
+
+export function registerDocumentTools(server, bridge) {
+  server.tool(
+    "revit_new_project",
+    "Create a new Revit project from a template and open it, without using the Revit UI. Works when no document is open. The default template is the metric one with English names. Rebuilding a project belongs at the same save_path with overwrite true — do not iterate into a new filename.",
+    {
+      save_path: z
+        .string()
+        .min(1)
+        .describe(
+          "Full path of the .rvt file to create, e.g. 'C:\\\\Projects\\\\House.rvt'. Fails if the file already exists unless overwrite is true; a missing parent folder is created.",
+        ),
+      template_path: z
+        .string()
+        .min(1)
+        .default(DEFAULT_TEMPLATE_PATH)
+        .describe(
+          `Full path of the .rte project template (default ${DEFAULT_TEMPLATE_PATH} — metric, English names)`,
+        ),
+      overwrite: z
+        .boolean()
+        .optional()
+        .describe(
+          "Rebuild the project in place: DELETES the existing save_path and the Revit backups beside it (House.0001.rvt, House.0002.rvt) and closes it in Revit first if it is open, then builds the project again at that same path. Defaults to false, which fails with FILE_EXISTS instead. A file something else still holds comes back as FILE_LOCKED — nothing is ever built under a different name.",
+        ),
+    },
+    async ({ save_path, template_path, overwrite }) => {
+      try {
+        // The tool arguments stay snake_case like every other tool's, but the
+        // bridge reads `savePath`/`templatePath` — map it here rather than on
+        // the C# side.
+        const payload = {
+          savePath: save_path,
+          templatePath: template_path,
+        };
+
+        // Left off the body entirely unless the caller said something, so the
+        // bridge's own default — never overwrite — is what answers for everyone
+        // who does not ask.
+        if (overwrite !== undefined) {
+          payload.overwrite = overwrite;
+        }
+
+        const result = await bridge.call("/document/new", payload);
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_save",
+    "Save the active document in place. A model that has never been saved has no path to save to and comes back as NOT_SAVEABLE — use revit_save_as for that one.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/document/save");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_save_as",
+    "Save the active document to a new path and carry on working in it. An existing file is an error unless overwrite is true; a missing parent folder is created.",
+    {
+      save_path: z
+        .string()
+        .min(1)
+        .describe(
+          "Full path of the .rvt file to write, e.g. 'C:\\\\Projects\\\\House.rvt'. Must not exist unless overwrite is true.",
+        ),
+      overwrite: z
+        .boolean()
+        .default(false)
+        .describe("Replace save_path if it already exists. Default false: an existing file fails with FILE_EXISTS."),
+    },
+    async ({ save_path, overwrite }) => {
+      try {
+        // The tool arguments stay snake_case like every other tool's, but the
+        // bridge reads `savePath` — map it here rather than on the C# side.
+        const result = await bridge.call("/document/save-as", {
+          savePath: save_path,
+          overwrite,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_open_project",
+    "Open an existing .rvt file and make it the active document, without using the Revit UI. Works when no document is open. A path that does not exist comes back as FILE_NOT_FOUND.",
+    {
+      path: z
+        .string()
+        .min(1)
+        .describe("Full path of the existing .rvt file to open, e.g. 'C:\\\\Projects\\\\House.rvt'"),
+    },
+    async ({ path }) => {
+      try {
+        const result = await bridge.call("/document/open", { path });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_close_project",
+    "Close the active document. Unsaved changes are DISCARDED unless save is true, so save first if the work matters. Closing when nothing is open is not an error — it answers {\"closed\":false}. Revit will not close the active document outright, so the bridge makes another open document active first — a blank scratch project under %TEMP% when this was the only one — and the response reports what became active in activePath / activeTitle / activeIsScratch.",
+    {
+      save: z
+        .boolean()
+        .default(false)
+        .describe("Save the document before closing it. Default false: unsaved changes are discarded."),
+    },
+    async ({ save }) => {
+      try {
+        const result = await bridge.call("/document/close", { save });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+}