Macroforge MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:393-462 (handler)

  Implements the core logic for the macroforge-autofixer tool by invoking the native Macroforge expander synchronously, processing diagnostics, and returning structured JSON output.

  async function handleAutofixer(args: { code: string; filename?: string }) {
    const filename = args.filename || 'input.ts';
  
    try {
      const macroforge = await importMacroforge();
  
      if (!macroforge) {
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                diagnostics: [{
                  level: 'error',
                  message: 'Native Macroforge bindings not available. Install @macroforge/core.',
                }],
                summary: { errors: 1, warnings: 0, info: 0 },
                require_another_tool_call_after_fixing: false,
              }, null, 2),
            },
          ],
        };
      }
  
      const result = macroforge.expandSync(args.code, filename, {});
      const diagnostics = result.diagnostics || [];
  
      const output: AutofixerResult = {
        diagnostics: diagnostics.map((d) => ({
          level: normalizeLevel(d.level),
          message: d.message,
          location: d.span ? { line: d.span.start.line, column: d.span.start.column } : undefined,
          help: d.help || undefined,
          notes: d.notes && d.notes.length > 0 ? d.notes : undefined,
        })),
        summary: {
          errors: diagnostics.filter((d) => d.level === 'Error').length,
          warnings: diagnostics.filter((d) => d.level === 'Warning').length,
          info: diagnostics.filter((d) => d.level === 'Info').length,
        },
        require_another_tool_call_after_fixing: diagnostics.some((d) => d.level === 'Error'),
      };
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(output, null, 2),
          },
        ],
      };
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify({
              diagnostics: [{
                level: 'error',
                message: `Error during analysis: ${message}`,
              }],
              summary: { errors: 1, warnings: 0, info: 0 },
              require_another_tool_call_after_fixing: false,
            }, null, 2),
          },
        ],
      };
    }
  }

• src/tools/index.ts:119-154 (registration)

  Registers the macroforge-autofixer tool with the MCP server in the listTools response, providing name, description, and input schema.

          {
            name: 'macroforge-autofixer',
            description: `Validates TypeScript code with @derive decorators using Macroforge's native validation.
  
  Returns structured JSON diagnostics with:
  - level: error | warning | info
  - message: What's wrong
  - location: Line and column number (when available)
  - help: Suggested fix (when available)
  - notes: Additional context (when available)
  - summary: Count of errors, warnings, and info messages
  
  This tool MUST be used before sending Macroforge code to the user.
  If require_another_tool_call_after_fixing is true, fix the issues and validate again.
  
  Detects:
  - Invalid/unknown macro names
  - Malformed @derive decorators
  - @serde validator issues (email, url, length, etc.)
  - Macro expansion failures
  - Syntax errors in generated code`,
            inputSchema: {
              type: 'object',
              properties: {
                code: {
                  type: 'string',
                  description: 'TypeScript code with @derive decorators to validate',
                },
                filename: {
                  type: 'string',
                  description: 'Filename for the code (default: input.ts)',
                },
              },
              required: ['code'],
            },
          },

• src/tools/index.ts:219-220 (registration)

  Dispatches incoming tool calls for macroforge-autofixer to the handleAutofixer function within the main tools/call handler switch statement.

  case 'macroforge-autofixer':
    return handleAutofixer(args as { code: string; filename?: string });

• src/tools/index.ts:797-819 (schema)

  Defines the TypeScript interface for the structured JSON output returned by the macroforge-autofixer handler.

  interface AutofixerResult {
    diagnostics: Array<{
      /** Severity level: "error", "warning", or "info" */
      level: string;
      /** Human-readable description of the issue */
      message: string;
      /** Source location (line and column) if available */
      location?: { line: number; column: number };
      /** Suggested fix for the issue */
      help?: string;
      /** Additional context or explanatory notes */
      notes?: string[];
    }>;
    /** Summary counts for quick overview */
    summary: {
      errors: number;
      warnings: number;
      info: number;
    };
    /** If true, client should fix issues and call autofixer again */
    require_another_tool_call_after_fixing: boolean;
  }

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

  Helper function that dynamically loads the optional @macroforge/core native module used for code validation and expansion in the handler.

  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;
    }
  }