Revit MCP

Instructions

Implementation Reference

• src/tools/color_elements.ts:32-82 (handler)

  The handler function for the 'color_elements' MCP tool. It processes input arguments, sends a 'color_splash' command to the Revit client via withRevitConnection, handles the response by formatting colored groups into a text output, and returns success or error content.

      async (args, extra) => {
        const params = args;
        try {
          const response = await withRevitConnection(async (revitClient) => {
            return await revitClient.sendCommand("color_splash", params);
          });
  
          // Format the response into a more user-friendly output
          if (response.success) {
            const coloredGroups = response.results || [];
  
            let resultText = `Successfully colored ${response.totalElements} elements across ${response.coloredGroups} groups.\n\n`;
            resultText += "Parameter Value Groups:\n";
  
            coloredGroups.forEach((group: any) => {
              const rgb = group.color;
              resultText += `- "${group.parameterValue}": ${group.count} elements colored with RGB(${rgb.r}, ${rgb.g}, ${rgb.b})\n`;
            });
  
            return {
              content: [
                {
                  type: "text",
                  text: resultText,
                },
              ],
            };
          } else {
            return {
              content: [
                {
                  type: "text",
                  text: `Color operation failed: ${response.message}`,
                },
              ],
            };
          }
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `Color operation failed: ${
                    error instanceof Error ? error.message : String(error)
                }`,
              },
            ],
          };
        }
      }
  );

• src/tools/color_elements.ts:9-31 (schema)

  Zod schema for input validation of the 'color_elements' tool parameters: categoryName, parameterName, useGradient, and optional customColors array of RGB objects.

  {
    categoryName: z
        .string()
        .describe("The name of the Revit category to color (e.g., 'Walls', 'Doors', 'Rooms')"),
    parameterName: z
        .string()
        .describe("The name of the parameter to use for grouping and coloring elements"),
    useGradient: z
        .boolean()
        .optional()
        .default(false)
        .describe("Whether to use a gradient color scheme instead of random colors"),
    customColors: z
        .array(
            z.object({
              r: z.number().int().min(0).max(255),
              g: z.number().int().min(0).max(255),
              b: z.number().int().min(0).max(255),
            })
        )
        .optional()
        .describe("Optional array of custom RGB colors to use for specific parameter values"),
  },

• src/tools/color_elements.ts:5-83 (registration)

  Registration function that adds the 'color_elements' tool to the MCP server, including name, description, schema, and handler.

  export function registerColorElementsTool(server: McpServer) {
    server.tool(
        "color_elements",
        "Color elements in the current view based on a category and parameter value. Each unique parameter value gets assigned a distinct color.",
        {
          categoryName: z
              .string()
              .describe("The name of the Revit category to color (e.g., 'Walls', 'Doors', 'Rooms')"),
          parameterName: z
              .string()
              .describe("The name of the parameter to use for grouping and coloring elements"),
          useGradient: z
              .boolean()
              .optional()
              .default(false)
              .describe("Whether to use a gradient color scheme instead of random colors"),
          customColors: z
              .array(
                  z.object({
                    r: z.number().int().min(0).max(255),
                    g: z.number().int().min(0).max(255),
                    b: z.number().int().min(0).max(255),
                  })
              )
              .optional()
              .describe("Optional array of custom RGB colors to use for specific parameter values"),
        },
        async (args, extra) => {
          const params = args;
          try {
            const response = await withRevitConnection(async (revitClient) => {
              return await revitClient.sendCommand("color_splash", params);
            });
  
            // Format the response into a more user-friendly output
            if (response.success) {
              const coloredGroups = response.results || [];
  
              let resultText = `Successfully colored ${response.totalElements} elements across ${response.coloredGroups} groups.\n\n`;
              resultText += "Parameter Value Groups:\n";
  
              coloredGroups.forEach((group: any) => {
                const rgb = group.color;
                resultText += `- "${group.parameterValue}": ${group.count} elements colored with RGB(${rgb.r}, ${rgb.g}, ${rgb.b})\n`;
              });
  
              return {
                content: [
                  {
                    type: "text",
                    text: resultText,
                  },
                ],
              };
            } else {
              return {
                content: [
                  {
                    type: "text",
                    text: `Color operation failed: ${response.message}`,
                  },
                ],
              };
            }
          } catch (error) {
            return {
              content: [
                {
                  type: "text",
                  text: `Color operation failed: ${
                      error instanceof Error ? error.message : String(error)
                  }`,
                },
              ],
            };
          }
        }
    );
  }