@rui.branco/revit-mcp 1.0.0

package/lib/tools/read.js

@@ -0,0 +1,142 @@
+// Read-only tools. Intent-level, not a mirror of the Revit API: every response
+// is compact JSON — element ids plus only the parameters that were asked for.
+// Dumping full parameter sets would bury the model in noise for no gain.
+
+import { z } from "zod";
+
+export const DEFAULT_QUERY_LIMIT = 100;
+export const MAX_QUERY_LIMIT = 500;
+
+// A model that asks for 10000 rows gets 500, not an error — the response always
+// carries `total`, so it can see what it did not get and page with offset.
+export function clampLimit(limit) {
+  if (!Number.isFinite(limit)) return DEFAULT_QUERY_LIMIT;
+  return Math.min(Math.max(Math.trunc(limit), 1), MAX_QUERY_LIMIT);
+}
+
+export function registerReadTools(server, bridge) {
+  server.tool(
+    "revit_status",
+    "Check whether Revit is reachable: version, active document name/path, and whether the model is workshared. Run this first when any other Revit tool fails.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/status");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_list_levels",
+    "List the levels in the active document: id, name and elevation (Revit internal units, decimal feet).",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/levels");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_list_categories",
+    "List the categories present in the active document with an element count each. Use this to find the exact category name to pass to revit_query_elements.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/categories");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_query_elements",
+    "Find elements by category and/or level and/or type name. Returns compact rows (id, name, category, level, type) plus the total match count, so you always know how much you did not see. Page with offset.",
+    {
+      category: z
+        .string()
+        .optional()
+        .describe("Category name as shown by revit_list_categories (e.g. 'Walls')"),
+      level: z.string().optional().describe("Level name (e.g. 'Level 1')"),
+      type_name: z
+        .string()
+        .optional()
+        .describe("Element type name, matched case-insensitively as a substring"),
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .default(DEFAULT_QUERY_LIMIT)
+        .describe(
+          `Max rows to return (default ${DEFAULT_QUERY_LIMIT}, hard cap ${MAX_QUERY_LIMIT} — higher values are clamped, not rejected)`,
+        ),
+      offset: z
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .describe("Rows to skip, for paging through a large result"),
+    },
+    async ({ category, level, type_name, limit, offset }) => {
+      try {
+        // The tool argument stays snake_case like every other tool's, but the
+        // bridge reads `typeName` — map it here rather than on the C# side.
+        const result = await bridge.call("/query", {
+          category,
+          level,
+          typeName: type_name,
+          limit: clampLimit(limit),
+          offset,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_get_elements",
+    "Read specific elements by id. Pass params to get exactly those parameters and nothing else; without params you get identity only (id, name, category, type).",
+    {
+      ids: z
+        .array(z.number().int())
+        .min(1)
+        .describe("Element ids (from revit_query_elements or revit_get_selection)"),
+      params: z
+        .array(z.string())
+        .optional()
+        .describe("Parameter names to read, e.g. ['Comments', 'Mark', 'Unconnected Height']"),
+    },
+    async ({ ids, params }) => {
+      try {
+        const result = await bridge.call("/elements", { ids, params });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_get_selection",
+    "Read what the user currently has selected in the Revit UI. Use this when the user says 'this wall', 'the selected elements' or similar.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/selection");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+}

package/lib/tools/reload.js

@@ -0,0 +1,27 @@
+// Hot reload: swap the bridge's routing and endpoint logic without restarting
+// Revit.
+//
+// A Revit restart means closing the model, which is precisely what a long
+// unattended run cannot afford — so the add-in is split in two. The half Revit
+// pins for the session owns the HTTP listener and the main-thread pump; the
+// half that changes (routes and endpoints) is loaded into a collectible load
+// context from a shadow copy, and this tool replaces it live.
+//
+// Maintainer tooling: it only does anything after the logic DLL has actually
+// been rebuilt on disk.
+
+export function registerReloadTools(server, bridge) {
+  server.tool(
+    "revit_reload_bridge",
+    "Reload the bridge's endpoint logic from disk without restarting Revit, after rebuilding the add-in. Use this while developing the bridge itself: it swaps the freshly built logic assembly into the running Revit, keeping the open model, the HTTP listener and any queued work alive. The response says whether the previous version was actually unloaded — if unloadedPrevious is false, the new logic IS live but the old one is still in memory, which is worth investigating rather than ignoring. Nothing changes until the DLL on disk changes, so build first.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/reload");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+}

package/lib/tools/sheet-collections.js

@@ -0,0 +1,62 @@
+// Sheet collections: Revit's own collapsible groups under Sheets in the Project
+// Browser. A native SheetCollection element, so the grouping is there when the
+// model opens — no browser-organisation parameter for the user to wire up by
+// hand, and no renaming or renumbering of the sheets themselves.
+
+import { z } from "zod";
+
+export function registerSheetCollectionTools(server, bridge) {
+  server.tool(
+    "revit_list_sheet_collections",
+    "List the sheet collections in the active document — the collapsible groups Revit draws under Sheets in the Project Browser — with each collection's id, name and member sheets (id, number, name). 'unassignedSheets' is every sheet in no collection. Read-only.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/sheets/collections");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_set_sheet_collections",
+    "Put sheets into native sheet collections, so the Project Browser shows them as collapsible groups. Pass every collection in one call: together they are one undo step. A collection whose name already exists is REUSED, not duplicated, and one whose membership already matches is reported 'unchanged' and left alone. dry_run defaults to TRUE — the call reports the plan and writes nothing until you pass dry_run: false. Nothing else about the sheets is touched: numbers and names are left as they are, and collections this call does not mention keep their members. A sheet belongs to one collection, so an id may appear in only one entry, and assembly sheets cannot join a collection at all. Collections are one level deep; the views under a sheet stay where Revit puts them. The reply reports 'action' (created / reused / unchanged) per collection and, once applied, the membership read back off the committed document.",
+    {
+      collections: z
+        .array(
+          z.object({
+            name: z
+              .string()
+              .min(1)
+              .describe(
+                "Collection name as it should read in the browser, e.g. 'L.02'. Matched exactly against existing collections; Revit prohibits the characters {}[]|;<>?`~ in one.",
+              ),
+            sheet_ids: z
+              .array(z.number().int())
+              .min(1)
+              .describe("Ids of the sheets that belong in it, from revit_list_sheets"),
+          }),
+        )
+        .min(1)
+        .describe("The collections to build, all in this one call"),
+      dry_run: z
+        .boolean()
+        .optional()
+        .describe("Defaults to true: report the plan without writing. Pass false to apply it."),
+    },
+    async ({ collections, dry_run }) => {
+      try {
+        // Tool arguments stay snake_case; the bridge reads sheetIds / dryRun.
+        const result = await bridge.call("/sheets/set-collections", {
+          collections: collections.map(({ name, sheet_ids }) => ({ name, sheetIds: sheet_ids })),
+          dryRun: dry_run,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+}

package/lib/tools/sheets.js

@@ -0,0 +1,76 @@
+// Sheet tools: the two reads a caller needs before creating sheets, and the
+// batch create itself.
+//
+// A sheet cannot exist without a title block family type, so the read that
+// lists them is part of this set rather than of the general reads.
+
+import { z } from "zod";
+
+export function registerSheetTools(server, bridge) {
+  server.tool(
+    "revit_list_titleblocks",
+    "List the title block family types loaded in the active document: id, family name and type name. Call this before revit_create_sheets — every sheet needs a title block, and this is where its id comes from. An empty list means no title block family is loaded, so sheets cannot be created yet.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/titleblocks");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_list_sheets",
+    "List the sheets in the active document: id, sheet number and name, ordered by sheet number.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/sheets");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_create_sheets",
+    "Create sheets in the active document. Pass every sheet in one call: all of them together are one undo step. A sheet number that already exists is skipped and reported in 'skipped' rather than erroring, so re-running the same call is safe.",
+    {
+      sheets: z
+        .array(
+          z.object({
+            number: z
+              .string()
+              .min(1)
+              .describe("Sheet number, e.g. 'A101'. Must be unique; an existing one is skipped."),
+            name: z.string().min(1).describe("Sheet name, e.g. 'Ground Floor Plan'"),
+          }),
+        )
+        .min(1)
+        .describe("Sheets to create, all in this one call"),
+      title_block_id: z
+        .number()
+        .int()
+        .optional()
+        .describe(
+          "Title block family type id from revit_list_titleblocks. Omit it to use the first one loaded.",
+        ),
+    },
+    async ({ sheets, title_block_id }) => {
+      try {
+        // The tool argument stays snake_case like every other tool's, but the
+        // bridge reads `titleBlockId` — map it here rather than on the C# side.
+        const result = await bridge.call("/sheets/create", {
+          sheets,
+          titleBlockId: title_block_id,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+}

package/lib/tools/titleblocks.js

@@ -0,0 +1,152 @@
+// Title block families, read from the inside.
+//
+// `revit_list_titleblocks` says which title block types are loaded and nothing
+// more. What is actually printed on the sheet — the logo, the consultant
+// placeholders somebody typed into the stock family, the label that grows to
+// hold a long project name — lives in the FAMILY, and Document.EditFamily is
+// the only way to see it from the API.
+//
+// That call hands back an independent copy of the family as its own document.
+// The inspect tool reads it and closes it without saving, inside a finally:
+// nothing in the project, the loaded family or the .rfa on disk changes.
+//
+// `revit_edit_titleblock_family` is the write half, and it takes the ids the
+// inspection reported. It edits the same copy and loads it back into the SAME
+// project with Document.LoadFamily — no SaveAs, no second project file. Reading
+// first is not optional: every id is a family id, and the edit is refused unless
+// expected_family_name matches the family those ids came out of.
+
+import { z } from "zod";
+
+// A point on the sheet. Annotation in a title block is paper feet, so z is not a
+// dimension it has.
+const point2 = z.object({ x: z.number(), y: z.number() });
+
+export function registerTitleblockTools(server, bridge) {
+  server.tool(
+    "revit_inspect_titleblock_family",
+    "Read what is INSIDE a title block family: the only way to find out why a sheet prints a vendor logo, a literal consultant placeholder or a label that overlaps its neighbour. READ-ONLY — the family is opened with Document.EditFamily, which hands back an independent copy, and that copy is closed without saving in a finally; no transaction is opened, so the project, the loaded family and the .rfa on disk are untouched, and nothing here can be undone because nothing is done. Per element it reports id, the Revit API class, category, name, type id/name, the view it is drawn in, its location and its bounding box, plus: text (content, insertion point, width/height, both alignments, text type and that type's text size, and isTextNote — true is literal text somebody typed, false is the other kind of text element); images (size, scale, and the image type's path, source, status and pixel size); imports (whether linked, and the import type's name, which is the file it came from); curves (line style); dimensions (value, isLocked, segments, and the family parameter labelling it — the constraints holding the border together); reference planes (both ends and the normal). The dynamic half is familyParameters: every family parameter with its storage type, formula, instance/type flag, the current type's value, and associatedElementIds — the elements whose own parameters Revit has associated to it. The same association appears on each element row as labelOf. That association is the evidence for which content is parameter-driven and must be preserved and which is a literal string safe to remove; it is reported as the association Revit holds, not as a claim about what a reader sees. Lengths are Revit internal units (decimal feet) and annotation inside a title block is PAPER feet — 5 mm text reads 0.0164. symbol_id is a title block type id from revit_list_titleblocks; anything in another category is refused, and an in-place or non-editable family is refused before anything is opened.",
+    {
+      symbol_id: z
+        .number()
+        .int()
+        .describe("Id of the loaded title block TYPE (a FamilySymbol), from revit_list_titleblocks"),
+    },
+    async ({ symbol_id }) => {
+      try {
+        // Tool arguments stay snake_case; the bridge reads symbolId.
+        const result = await bridge.call("/families/titleblock-inspect", { symbolId: symbol_id });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${error.message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_edit_titleblock_family",
+    "Edit the INSIDE of a title block family and load it back into this same project: remove the stock logo and the literal consultant placeholders, retext the captions, resize labels, add notes. The ids are family ids from revit_inspect_titleblock_family, never project ids — inspect first, always. What makes it safe is what it refuses: expected_family_name is required and must match the family those ids came out of, or nothing is even opened; only a TextNote or an ImageInstance can be removed, and a label (a text element bound to a parameter) is refused by name, because deleting one takes that content off every sheet for good; Document.Delete is read back, so anything it would take that you did not name rolls the whole edit back, and so does any label or schedule instance that existed before the edit and not after it. label_sizes does NOT edit the text type in place — a type is shared, and editing it would resize everything on it. An existing type of that size is reused, otherwise the element's own type is duplicated and only the elements named are pointed at the copy; an element Revit will not retype comes back as action 'refused' with the reason, and the removals still stand. Sizes and points are Revit internal units (decimal feet), and annotation inside a title block is PAPER feet: 6 mm text is 0.019685, 3 mm is 0.009843, and 1032 mm across the sheet is 3.385827. dry_run DEFAULTS TO TRUE: it opens the family, resolves every id and every text type, reports exactly what it would do, and closes the copy without saving. Read that, then call again with dry_run false. Applying loads the edited family into the project — every sheet using it redraws — and writes nothing to the .rfa on disk.",
+    {
+      symbol_id: z
+        .number()
+        .int()
+        .describe("Id of the loaded title block TYPE (a FamilySymbol), from revit_list_titleblocks"),
+      expected_family_name: z
+        .string()
+        .describe(
+          "The family name the ids were read from, as revit_inspect_titleblock_family reported it. A mismatch is refused before the family is opened.",
+        ),
+      remove_ids: z
+        .array(z.number().int())
+        .optional()
+        .describe(
+          "Family ids to delete. TextNote and ImageInstance only — the stock logo and the literal placeholders. A label, a line, a dimension or a reference plane is refused.",
+        ),
+      text_edits: z
+        .array(
+          z.object({
+            id: z.number().int().describe("Family id of a TextNote — literal text, not a label"),
+            text: z.string().describe("The text it should read instead"),
+          }),
+        )
+        .optional()
+        .describe("Retext literal notes, e.g. translating the stock captions"),
+      label_sizes: z
+        .array(
+          z.object({
+            id: z.number().int().describe("Family id of a label or a text note"),
+            size: z
+              .number()
+              .positive()
+              .describe("Text size in decimal feet — PAPER feet: 6 mm is 0.019685"),
+          }),
+        )
+        .optional()
+        .describe(
+          "Retype text elements to a type of this size, reusing one the family has or duplicating theirs",
+        ),
+      new_notes: z
+        .array(
+          z.object({
+            text: z.string(),
+            point: point2.describe("Insertion point on the sheet, in decimal feet"),
+            size: z.number().positive().describe("Text size in decimal feet"),
+            width: z
+              .number()
+              .positive()
+              .optional()
+              .describe(
+                "Line-wrapping width in decimal feet. Omit for a single line sized to the text. A width outside what Revit allows for the type is refused with the allowed range.",
+              ),
+          }),
+        )
+        .optional()
+        .describe("Notes to add in the family's sheet view"),
+      view_id: z
+        .number()
+        .int()
+        .optional()
+        .describe(
+          "View inside the family to draw new_notes in. Defaults to the view the family's existing text is already in; only needed when it draws text in more than one.",
+        ),
+      dry_run: z
+        .boolean()
+        .default(true)
+        .describe(
+          "DEFAULTS TO TRUE. True resolves every id and text type and reports what it would do, changing nothing. Pass false to apply it and load the family back.",
+        ),
+    },
+    async ({
+      symbol_id,
+      expected_family_name,
+      remove_ids,
+      text_edits,
+      label_sizes,
+      new_notes,
+      view_id,
+      dry_run,
+    }) => {
+      try {
+        const result = await bridge.call("/families/titleblock-edit", {
+          symbolId: symbol_id,
+          expectedFamilyName: expected_family_name,
+          removeIds: remove_ids,
+          textEdits: text_edits,
+          labelSizes: label_sizes,
+          newNotes: new_notes,
+          viewId: view_id,
+          dryRun: dry_run,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${error.message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}