Macroforge MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:551-661 (handler)

  The main handler function that implements the 'get-macro-info' tool logic. It dynamically imports the native Macroforge module, retrieves the macro manifest, and formats documentation for either all macros/decorators or a specific one based on the input.

   * Handles the `get-macro-info` tool call.
   *
   * Retrieves documentation for Macroforge macros and field decorators from the
   * native manifest. Can return info for a specific macro/decorator or the full
   * manifest of all available macros and decorators.
   *
   * ## Usage Modes
   *
   * - **Without name**: Returns full manifest with all macros and decorators
   * - **With name**: Returns detailed info for the specific macro or decorator
   *
   * ## Manifest Contents
   *
   * - **Macros**: @derive decorators like Debug, Serialize, Clone
   * - **Decorators**: Field decorators like @serde.skip, @serde.rename
   *
   * @param args - Tool arguments
   * @param args.name - Optional macro or decorator name to look up
   * @returns MCP response with formatted macro/decorator documentation
   */
  async function handleGetMacroInfo(args: { name?: string }) {
    try {
      const macroforge = await importMacroforge();
  
      if (!macroforge || !macroforge.__macroforgeGetManifest) {
        return {
          content: [
            {
              type: 'text' as const,
              text: 'Native Macroforge bindings not available. Install @macroforge/core to access macro documentation.',
            },
          ],
        };
      }
  
      const manifest = macroforge.__macroforgeGetManifest();
  
      if (args.name) {
        // Look up specific macro or decorator
        const nameLower = args.name.toLowerCase();
        const macro = manifest.macros.find(m => m.name.toLowerCase() === nameLower);
        const decorator = manifest.decorators.find(d => d.export.toLowerCase() === nameLower);
  
        if (!macro && !decorator) {
          return {
            content: [
              {
                type: 'text' as const,
                text: `No macro or decorator found with name "${args.name}".
  
  Available macros: ${manifest.macros.map(m => m.name).join(', ')}
  Available decorators: ${manifest.decorators.map(d => d.export).join(', ')}`,
              },
            ],
          };
        }
  
        let result = '';
  
        if (macro) {
          result += `## Macro: @derive(${macro.name})\n\n`;
          result += `**Description:** ${macro.description || 'No description available'}\n`;
          result += `**Kind:** ${macro.kind}\n`;
          result += `**Package:** ${macro.package}\n`;
        }
  
        if (decorator) {
          if (result) result += '\n---\n\n';
          result += `## Decorator: @${decorator.export}\n\n`;
          result += `**Documentation:** ${decorator.docs || 'No documentation available'}\n`;
          result += `**Kind:** ${decorator.kind}\n`;
          result += `**Module:** ${decorator.module}\n`;
        }
  
        return {
          content: [{ type: 'text' as const, text: result }],
        };
      }
  
      // Return full manifest
      let result = '# Macroforge Macro Manifest\n\n';
  
      result += '## Available Macros\n\n';
      for (const macro of manifest.macros) {
        result += `### @derive(${macro.name})\n`;
        result += `${macro.description || 'No description'}\n\n`;
      }
  
      if (manifest.decorators.length > 0) {
        result += '## Available Field Decorators\n\n';
        for (const decorator of manifest.decorators) {
          result += `### @${decorator.export}\n`;
          result += `${decorator.docs || 'No documentation'}\n\n`;
        }
      }
  
      return {
        content: [{ type: 'text' as const, text: result }],
      };
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: 'text' as const,
            text: `Error getting macro info: ${message}`,
          },
        ],
      };
    }
  }

• src/tools/index.ts:183-203 (registration)

  Tool registration in the MCP tools/list handler, defining the name, description, and input schema for 'get-macro-info'.

          {
            name: 'get-macro-info',
            description: `Get documentation for Macroforge macros and decorators.
  
  Returns information about:
  - Macro descriptions (e.g., Debug, Serialize, Clone)
  - Decorator documentation (e.g., @serde, @debug field decorators)
  - Available macro options and configuration
  
  Use without parameters to get the full manifest of all available macros and decorators.
  Use with a name parameter to get info for a specific macro or decorator.`,
            inputSchema: {
              type: 'object',
              properties: {
                name: {
                  type: 'string',
                  description: 'Optional: specific macro or decorator name to look up',
                },
              },
            },
          },

• src/tools/index.ts:194-202 (schema)

  Input schema definition for the 'get-macro-info' tool, specifying an optional 'name' parameter.

  inputSchema: {
    type: 'object',
    properties: {
      name: {
        type: 'string',
        description: 'Optional: specific macro or decorator name to look up',
      },
    },
  },

• src/tools/index.ts:225-226 (registration)

  Dispatch case in the MCP tools/call handler that routes 'get-macro-info' requests to the handler function.

  case 'get-macro-info':
    return handleGetMacroInfo(args as { name?: string });

• src/tools/index.ts:869-878 (helper)

  Helper function used by the handler to dynamically load the optional @macroforge/core native bindings.

  async function importMacroforge(): Promise<MacroforgeModule | null> {
    try {
      // Dynamic import to avoid build-time errors when @macroforge/core is not installed
      // @ts-expect-error - dynamic import of optional dependency
      const mod = await import('@macroforge/core');
      return mod as MacroforgeModule;
    } catch {
      // Package not installed - return null to indicate unavailability
      return null;
    }