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