Macroforge MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:483-547 (handler)

  The main handler function that implements the 'expand-code' tool. It dynamically imports @macroforge/core, calls expandSync to expand macros in the provided TypeScript code, processes any diagnostics, and returns formatted markdown output containing the expanded code and diagnostic information.
  async function handleExpandCode(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: 'Native Macroforge bindings not available. Install @macroforge/core to enable code expansion.', }, ], }; } const result = macroforge.expandSync(args.code, filename, {}); const diagnostics = result.diagnostics || []; // Build structured output const output: ExpandResult = { expandedCode: result.code, diagnostics: diagnostics.map((d) => ({ level: normalizeLevel(d.level), message: d.message, location: d.span?.start, help: d.help || undefined, })), hasErrors: diagnostics.some((d) => d.level === 'Error'), }; // Format human-readable text let text = `## Expanded Code\n\n\`\`\`typescript\n${result.code}\n\`\`\``; if (diagnostics.length > 0) { text += '\n\n## Diagnostics\n\n'; for (const d of diagnostics) { const loc = d.span ? ` (line ${d.span.start.line}, col ${d.span.start.column})` : ''; text += `- **[${normalizeLevel(d.level)}]**${loc} ${d.message}\n`; if (d.help) { text += ` - Help: ${d.help}\n`; } if (d.notes && d.notes.length > 0) { for (const note of d.notes) { text += ` - Note: ${note}\n`; } } } } return { content: [{ type: 'text' as const, text }], }; } catch (error) { const message = error instanceof Error ? error.message : String(error); return { content: [ { type: 'text' as const, text: `Error expanding code: ${message}`, }, ], }; }
• src/tools/index.ts:155-182 (registration)

  The tool registration definition in the ListToolsRequestSchema handler, including the tool name, description, and input schema.
  { name: 'expand-code', description: `Expands Macroforge macros in TypeScript code and returns the transformed result. Shows: - The fully expanded TypeScript code with all generated methods - Any diagnostics (errors, warnings, info) with line/column locations - Help text for fixing issues (when available) Useful for: - Seeing what code the macros generate - Understanding how @derive decorators transform your classes - Debugging macro expansion issues`, inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'TypeScript code with @derive decorators to expand', }, filename: { type: 'string', description: 'Filename for the code (default: input.ts)', }, }, required: ['code'], }, },
• src/tools/index.ts:830-843 (schema)

  TypeScript interface defining the structured output format used internally by the expand-code handler.
  interface ExpandResult { expandedCode: string; 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; }>; hasErrors: boolean; }
• src/tools/index.ts:222-223 (registration)

  Dispatch case in the CallToolRequestSchema handler that routes 'expand-code' calls to the handleExpandCode function.
  case 'expand-code': return handleExpandCode(args as { code: string; filename?: string });
• src/tools/index.ts:547-869 (helper)

  Helper functions used by the handler: importMacroforge dynamically loads the optional @macroforge/core dependency, and normalizeLevel converts diagnostic levels to lowercase.
  } } /** * 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}`, }, ], }; } } // ============================================================================ // Types - Match Rust's Diagnostic structure from macroforge_ts_syn/src/abi/patch.rs // ============================================================================ /** * Represents a location span in source code. * * Used by diagnostics to indicate where an error or warning occurred. * Matches the Rust `Span` type from the macroforge_ts_syn crate. * * @property start - Starting position (line and column, 1-indexed) * @property end - Ending position (line and column, 1-indexed) */ interface DiagnosticSpan { start: { line: number; column: number }; end: { line: number; column: number }; } /** * Represents a diagnostic message from the Macroforge analyzer. * * Diagnostics are produced during code validation and expansion to report * errors, warnings, and informational messages. Matches the Rust `Diagnostic` * type from macroforge_ts_syn/src/abi/patch.rs. * * @property level - Severity level: 'Error', 'Warning', or 'Info' * @property message - Human-readable description of the issue * @property span - Optional source location where the issue occurred * @property notes - Additional context or explanatory notes * @property help - Optional suggestion for how to fix the issue */ interface Diagnostic { level: 'Error' | 'Warning' | 'Info'; message: string; span?: DiagnosticSpan; notes: string[]; help?: string; } /** * Metadata for a Macroforge macro in the manifest. * * Describes a @derive macro that can be applied to classes. * * @property name - Macro name as used in @derive (e.g., "Debug", "Serialize") * @property kind - Type of macro (e.g., "derive") * @property description - Human-readable description of what the macro does * @property package - Package that provides this macro */ interface MacroManifestEntry { name: string; kind: string; description: string; package: string; } /** * Metadata for a field decorator in the manifest. * * Describes a decorator that can be applied to class fields to customize * macro behavior (e.g., @serde.skip, @debug.format). * * @property module - Module path where the decorator is defined * @property export - Export name of the decorator * @property kind - Type of decorator (e.g., "field") * @property docs - Documentation string for the decorator */ interface DecoratorManifestEntry { module: string; export: string; kind: string; docs: string; } /** * Complete manifest of available Macroforge macros and decorators. * * Returned by the native bindings to provide documentation and metadata * for all available macros and field decorators. * * @property version - Manifest format version * @property macros - Array of available @derive macros * @property decorators - Array of available field decorators */ interface MacroManifest { version: number; macros: MacroManifestEntry[]; decorators: DecoratorManifestEntry[]; } /** * Interface for the native Macroforge module (@macroforge/core). * * Defines the expected API surface of the optional native bindings that * provide code validation, expansion, and manifest access. * * @property expandSync - Synchronously expands macros in TypeScript code * @property __macroforgeGetManifest - Optional function to retrieve the macro manifest */ interface MacroforgeModule { /** * Synchronously expands Macroforge macros in TypeScript code. * * @param code - TypeScript source code with @derive decorators * @param filename - Filename for error reporting * @param options - Expansion options (currently unused) * @returns Object with expanded code and any diagnostics */ expandSync: (code: string, filename: string, options: object) => { code: string; diagnostics?: Diagnostic[]; }; /** * Retrieves the macro manifest with all available macros and decorators. * Optional - may not be available in all versions. */ __macroforgeGetManifest?: () => MacroManifest; } // ============================================================================ // Output types for structured responses // ============================================================================ /** * Structured output format for the `macroforge-autofixer` tool. * * Provides a JSON response that clients can parse to display errors, * navigate to problem locations, and determine if re-validation is needed. * * @property diagnostics - Array of diagnostic messages with locations * @property summary - Counts of errors, warnings, and info messages * @property require_another_tool_call_after_fixing - True if errors exist and client should revalidate after fixing */ 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; } /** * Structured output format for the `expand-code` tool. * * Contains the fully expanded code along with any diagnostics produced * during expansion. * * @property expandedCode - The TypeScript code after macro expansion * @property diagnostics - Array of diagnostic messages from expansion * @property hasErrors - True if any error-level diagnostics were produced */ interface ExpandResult { expandedCode: string; 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; }>; hasErrors: boolean; } // ============================================================================ // Helper functions // ============================================================================ /** * Dynamically imports the native Macroforge bindings. * * The @macroforge/core package is an optional peer dependency that provides * native Rust-based code analysis and expansion. This function attempts to * load it at runtime and gracefully returns null if unavailable. * * Using dynamic import allows the MCP server to run and serve documentation * even when the native bindings are not installed. * * @returns The Macroforge module if available, or null if not installed * * @example * ```typescript * const macroforge = await importMacroforge(); * if (macroforge) { * const result = macroforge.expandSync(code, 'input.ts', {}); * } * ``` */ async function importMacroforge(): Promise<MacroforgeModule | null> {