Macroforge MCP Server

# How Macros Work Macroforge performs compile-time code generation by parsing your TypeScript, expanding macros, and outputting transformed code. This happens before your code runs, resulting in zero runtime overhead. ## Compile-Time Expansion Unlike runtime solutions that use reflection or proxies, Macroforge expands macros at compile time: 1. **Parse**: Your TypeScript code is parsed into an AST using SWC 2. **Find**: Macroforge finds `@derive` decorators and their associated items 3. **Expand**: Each macro generates new code based on the class structure 4. **Output**: The transformed TypeScript is written out, ready for normal compilation Before (Your Code) ``` /** @derive(Debug) */ class User { name: string; } ``` After (Generated) ``` class User { name: string; static toString(value: User): string { return userToString(value); } } export function userToString(value: User): string { const parts: string[] = []; parts.push('name: ' + value.name); return 'User { ' + parts.join(', ') + ' }'; } ``` ## Zero Runtime Overhead Because code generation happens at compile time, there's no: * Runtime reflection or metadata * Proxy objects or wrappers * Additional dependencies in your bundle * Performance cost at runtime The generated code is plain TypeScript that compiles to efficient JavaScript. ## Source Mapping Macroforge tracks the relationship between your source code and the expanded output. This means: * Errors in generated code point back to your source * Debugging works correctly * IDE features like "go to definition" work as expected Error positioning The TypeScript plugin uses source mapping to show errors at the `@derive` decorator position, not in the generated code. ## Execution Flow Your Source Code with @derive decorators SWC Parser TypeScript → AST Macro Expansion Engine Finds @derive decorators, runs macros, generates new AST nodes Code Generator AST → TypeScript Expanded TypeScript ready for normal compilation ## Integration Points Macroforge integrates at two key points: ### IDE (TypeScript Plugin) The TypeScript plugin intercepts language server calls to provide: * Diagnostics that reference your source, not expanded code * Completions for generated methods * Hover information showing what macros generate ### Build (Vite Plugin) The Vite plugin runs macro expansion during the build process: * Transforms files before they reach the TypeScript compiler * Generates type declaration files (.d.ts) * Produces metadata for debugging ## Next Steps * [Learn about the derive system](../docs/concepts/derive-system) * [Explore the architecture](../docs/concepts/architecture)