@macroforge/mcp-server 0.1.33 → 0.1.35

package/docs/integration/integration-overview.md

@@ -1,58 +1,19 @@
 # Integration
-
-*Macroforge integrates with your development workflow through IDE plugins and build tool integration.*
-
-## Overview
-
-| TypeScript Plugin 
-| IDE support (errors, completions) 
-| `@macroforge/typescript-plugin` 
-
-| Vite Plugin 
-| Build-time macro expansion 
-| `@macroforge/vite-plugin`
-
-## Recommended Setup
-
-For the best development experience, use both integrations:
-
-1. **TypeScript Plugin**: Provides real-time feedback in your IDE
-
-2. **Vite Plugin**: Expands macros during development and production builds
-
-```bash
+ *Macroforge integrates with your development workflow through IDE plugins and build tool integration.*
+ ## Overview
+ | Integration | Purpose | Package |
+| --- | --- | --- |
+| TypeScript Plugin | IDE support (errors, completions) | `@macroforge/typescript-plugin` |
+| Vite Plugin | Build-time macro expansion | `@macroforge/vite-plugin` |
+ ## Recommended Setup
+ For the best development experience, use both integrations:
+ 1. **TypeScript Plugin**: Provides real-time feedback in your IDE
+ 2. **Vite Plugin**: Expands macros during development and production builds
+ ```
 # Install both plugins
 npm install -D @macroforge/typescript-plugin @macroforge/vite-plugin
-```
-
-## How They Work Together
-
-<IntegrationFlow
-source="Your Code"
-sourceDesc="TypeScript with @derive decorators"
-branches={[
-{
-plugin: 'TypeScript Plugin',
-pluginDesc: 'Language service integration',
-outputs: [
-{ label: 'IDE Feedback', desc: 'Errors & completions' }
-]
-},
-{
-plugin: 'Vite Plugin',
-pluginDesc: 'Build-time transformation',
-outputs: [
-{ label: 'Dev Server', desc: 'Hot reload' },
-{ label: 'Production Build', desc: 'Optimized output' }
-]
-}
-]}
-/>
-
-## Detailed Guides
-
-- [TypeScript Plugin setup]({base}/docs/integration/typescript-plugin)
-
-- [Vite Plugin configuration]({base}/docs/integration/vite-plugin)
-
-- [Configuration options]({base}/docs/integration/configuration)
+``` ## How They Work Together
+ <div class="flex justify-center"><div class="border-2 border-primary bg-primary/10 rounded-lg px-6 py-3 text-center"><div class="font-semibold text-primary">Your Code TypeScript with @derive decorators  <div class="absolute top-0 h-px bg-border" style="width: 50%; left: 25%;"> <div class="flex flex-col items-center">  <div class="border border-border bg-card rounded-lg px-4 py-3 text-center w-full mt-1"><div class="font-medium text-foreground">TypeScript Plugin Language service integration   <div class="border border-success/30 bg-success/10 rounded-md px-3 py-2 text-center"><div class="text-sm font-medium text-success-foreground">IDE Feedback Errors & completions  <div class="border border-border bg-card rounded-lg px-4 py-3 text-center w-full mt-1"><div class="font-medium text-foreground">Vite Plugin Build-time transformation   <div class="border border-success/30 bg-success/10 rounded-md px-3 py-2 text-center"><div class="text-sm font-medium text-success-foreground">Dev Server Hot reload<div class="text-sm font-medium text-success-foreground">Production Build Optimized output ## Detailed Guides
+ - [TypeScript Plugin setup](../docs/integration/typescript-plugin)
+ - [Vite Plugin configuration](../docs/integration/vite-plugin)
+ - [Configuration options](../docs/integration/configuration)

package/docs/integration/mcp-server.md

@@ -1,31 +1,17 @@
 # MCP Server
-
-*The MCP (Model Context Protocol) server enables AI assistants to understand and work with Macroforge macros, providing documentation lookup, code validation, and macro expansion.*
-
-The local (stdio) version of the MCP server is available via the [`@macroforge/mcp-server`](https://www.npmjs.com/package/@macroforge/mcp-server) npm package. You can either install it globally and then reference it in your configuration or run it with `npx`:
-
-```bash
+ *The MCP (Model Context Protocol) server enables AI assistants to understand and work with Macroforge macros, providing documentation lookup, code validation, and macro expansion.*
+ The local (stdio) version of the MCP server is available via the [`@macroforge/mcp-server`](https://www.npmjs.com/package/@macroforge/mcp-server) npm package. You can either install it globally and then reference it in your configuration or run it with `npx`:
+ ```
 npx -y @macroforge/mcp-server
-```
-
-Here's how to set it up in some common MCP clients:
-
-## Claude Code
-
-To include the local MCP version in Claude Code, simply run the following command:
-
-```bash
+``` Here's how to set it up in some common MCP clients:
+ ## Claude Code
+ To include the local MCP version in Claude Code, simply run the following command:
+ ```
 claude mcp add -t stdio -s [scope] macroforge -- npx -y @macroforge/mcp-server
-```
-
-The `[scope]` must be `user`, `project` or `local`.
-
-## Claude Desktop
-
-In the Settings > Developer section, click on Edit Config. It will open the folder with a `claude_desktop_config.json` file in it. Edit the file to include the following configuration:
-
-`claude_desktop_config.json`
-```json
+``` The `[scope]` must be `user`, `project` or `local`.
+ ## Claude Desktop
+ In the Settings > Developer section, click on Edit Config. It will open the folder with a `claude_desktop_config.json` file in it. Edit the file to include the following configuration:
+ ```
 {
     "mcpServers": {
         "macroforge": {
@@ -34,51 +20,26 @@ In the Settings > Developer section, click on Edit Config. It will open the fold
         }
     }
 }
-```
-
-## Codex CLI
-
-Add the following to your `config.toml` (which defaults to `~/.codex/config.toml`, but refer to [the configuration documentation](https://github.com/openai/codex/blob/main/docs/config.md) for more advanced setups):
-
-`config.toml`
-```toml
+``` ## Codex CLI
+ Add the following to your `config.toml` (which defaults to `~/.codex/config.toml`, but refer to [the configuration documentation](https://github.com/openai/codex/blob/main/docs/config.md) for more advanced setups):
+ ```
 [mcp_servers.macroforge]
 command = "npx"
 args = ["-y", "@macroforge/mcp-server"]
-```
-
-## Gemini CLI
-
-To include the local MCP version in Gemini CLI, simply run the following command:
-
-```bash
+``` ## Gemini CLI
+ To include the local MCP version in Gemini CLI, simply run the following command:
+ ```
 gemini mcp add -t stdio -s [scope] macroforge npx -y @macroforge/mcp-server
-```
-
-The `[scope]` must be `user`, `project` or `local`.
-
-## Other Clients
-
-If we didn't include the MCP client you are using, refer to their documentation for `stdio` servers and use `npx` as the command and `-y @macroforge/mcp-server` as the arguments.
-
-## Available Tools
-
-The MCP server provides five tools for AI assistants:
-
-| `list-sections` 
-| Lists all available Macroforge documentation sections 
-
-| `get-documentation` 
-| Retrieves full documentation for one or more sections 
-
-| `macroforge-autofixer` 
-| Validates code with `@derive` decorators and returns diagnostics 
-
-| `expand-code` 
-| Expands macros and returns the transformed TypeScript code 
-
-| `get-macro-info` 
-| Retrieves documentation for macros and field decorators
-
->
-> For code validation and expansion features (`macroforge-autofixer`, `expand-code`, `get-macro-info`), the MCP server requires `macroforge` as a peer dependency. Install it in your project with `npm install macroforge`.
+``` The `[scope]` must be `user`, `project` or `local`.
+ ## Other Clients
+ If we didn't include the MCP client you are using, refer to their documentation for `stdio` servers and use `npx` as the command and `-y @macroforge/mcp-server` as the arguments.
+ ## Available Tools
+ The MCP server provides five tools for AI assistants:
+ | Tool | Description |
+| --- | --- |
+| `list-sections` | Lists all available Macroforge documentation sections |
+| `get-documentation` | Retrieves full documentation for one or more sections |
+| `macroforge-autofixer` | Validates code with `@derive` decorators and returns diagnostics |
+| `expand-code` | Expands macros and returns the transformed TypeScript code |
+| `get-macro-info` | Retrieves documentation for macros and field decorators |
+ > **Note:** For code validation and expansion features (macroforge-autofixer, expand-code, get-macro-info), the MCP server requires macroforge as a peer dependency. Install it in your project with npm install macroforge.

package/docs/integration/svelte-preprocessor.md

@@ -1,19 +1,11 @@
 # Svelte Preprocessor
-
-*The Svelte preprocessor expands Macroforge macros in `<script>` blocks before Svelte compilation, enabling seamless macro usage in Svelte components.*
-
-## Installation
-
-```bash
+ *The Svelte preprocessor expands Macroforge macros in `<script>` blocks before Svelte compilation, enabling seamless macro usage in Svelte components.*
+ ## Installation
+ ```
 npm install -D @macroforge/svelte-preprocessor
-```
-
-## Configuration
-
-Add the preprocessor to your `svelte.config.js`:
-
-`svelte.config.js`
-```javascript
+``` ## Configuration
+ Add the preprocessor to your `svelte.config.js`:
+ ```
 import adapter from '@sveltejs/adapter-auto';
 import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
 import { macroforgePreprocess } from '@macroforge/svelte-preprocessor';
@@ -31,24 +23,29 @@ const config = {
 };
 
 export default config;
-```
-
-> **Warning:**
-> Always place `macroforgePreprocess()` **before** other preprocessors like `vitePreprocess()`. This ensures macros are expanded before TypeScript compilation.
-
-## Usage
+```  **Warning Always place `macroforgePreprocess()` **before** other preprocessors like `vitePreprocess()`. This ensures macros are expanded before TypeScript compilation. ## Usage
+ Use `@derive` decorators directly in your Svelte component scripts:
+ ```
+**<script lang="ts">
+  /** @derive(Debug, Clone) */
+  class User {
+    name: string;
+    email: string;
+
+    constructor(name: string, email: string) {
+      this.name = name;
+      this.email = email;
+    }
+  }
 
-Use `@derive` decorators directly in your Svelte component scripts:
+  let user = new User("Alice", "alice@example.com");
+  console.log(user.toString());  // Generated by Debug macro
+</script>
 
-`UserCard.svelte`
-```svelte
 User: {user.name}
 
-```
-
-## Options
-
-```typescript
+``` ## Options
+ ```
 macroforgePreprocess({
   // Keep @derive decorators in output (for debugging)
   keepDecorators: false,
@@ -56,41 +53,20 @@ macroforgePreprocess({
   // Process JavaScript files (not just TypeScript)
   processJavaScript: false
 })
-```
-
-### Option Reference
-
-| `keepDecorators` 
-| `boolean` 
-| `false` 
-| Keep decorators in output 
-
-| `processJavaScript` 
-| `boolean` 
-| `false` 
-| Process `<script>` blocks without `lang="ts"`
-
-## How It Works
-
-The preprocessor:
-
-1. Intercepts `<script lang="ts">` blocks in `.svelte` files
-
-2. Checks for `@derive` decorators (skips files without them)
-
-3. Expands macros using the native Macroforge binary
-
-4. Returns the transformed code for Svelte compilation
-
->
-> Files without `@derive` decorators are passed through unchanged with zero overhead.
-
-## SvelteKit Integration
-
-For SvelteKit projects, you can use both the preprocessor (for `.svelte` files) and the Vite plugin (for standalone `.ts` files):
-
-`svelte.config.js`
-```javascript
+``` ### Option Reference
+ | Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `keepDecorators` | `boolean` | `false` | Keep decorators in output |
+| `processJavaScript` | `boolean` | `false` | Process `<script>` blocks without `lang="ts"` |
+ ## How It Works
+ The preprocessor:
+ 1. Intercepts `<script lang="ts">` blocks in `.svelte` files
+ 2. Checks for `@derive` decorators (skips files without them)
+ 3. Expands macros using the native Macroforge binary
+ 4. Returns the transformed code for Svelte compilation
+  **Tip Files without `@derive` decorators are passed through unchanged with zero overhead. ## SvelteKit Integration
+ For SvelteKit projects, you can use both the preprocessor (for `.svelte` files) and the Vite plugin (for standalone `.ts` files):
+ ```
 // svelte.config.js
 import { macroforgePreprocess } from '@macroforge/svelte-preprocessor';
 import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
@@ -101,10 +77,7 @@ export default {
     vitePreprocess()
   ]
 };
-```
-
-`vite.config.ts`
-```typescript
+``` ```
 // vite.config.ts
 import macroforge from '@macroforge/vite-plugin';
 import { sveltekit } from '@sveltejs/kit/vite';
@@ -116,14 +89,9 @@ export default defineConfig({
     sveltekit()
   ]
 });
-```
-
-## Using with Vitest
-
-The preprocessor works seamlessly with Vitest for testing Svelte components:
-
-`vitest.config.ts`
-```typescript
+``` ## Using with Vitest
+ The preprocessor works seamlessly with Vitest for testing Svelte components:
+ ```
 // vitest.config.ts
 import { defineConfig } from 'vitest/config';
 import { sveltekit } from '@sveltejs/kit/vite';
@@ -141,12 +109,21 @@ export default defineConfig({
     include: ['src/**/*.{test,spec}.{js,ts}']
   }
 });
-```
-
-## Svelte 5 Runes Compatibility
-
-The preprocessor is fully compatible with Svelte 5 runes (`$state`, `$derived`, `$props`, etc.). Files using runes but without `@derive` decorators are skipped entirely.
-
-```svelte
-
+``` ## Svelte 5 Runes Compatibility
+ The preprocessor is fully compatible with Svelte 5 runes (`$state`, `$derived`, `$props`, etc.). Files using runes but without `@derive` decorators are skipped entirely.
+ ```
+**<script lang="ts">
+  // Runes work normally
+  let count = $state(0);
+  let doubled = $derived(count * 2);
+
+  // Macros expand correctly
+  /** @derive(Debug) */
+  class Counter {
+    value: number;
+    constructor(value: number) {
+      this.value = value;
+    }
+  }
+</script>
 ```

package/docs/integration/typescript-plugin.md

@@ -1,19 +1,11 @@
 # TypeScript Plugin
-
-*The TypeScript plugin provides IDE integration for Macroforge, including error reporting, completions, and type checking for generated code.*
-
-## Installation
-
-```bash
+ *The TypeScript plugin provides IDE integration for Macroforge, including error reporting, completions, and type checking for generated code.*
+ ## Installation
+ ```
 npm install -D @macroforge/typescript-plugin
-```
-
-## Configuration
-
-Add the plugin to your `tsconfig.json`:
-
-`tsconfig.json`
-```json
+``` ## Configuration
+ Add the plugin to your `tsconfig.json`:
+ ```
 {
   "compilerOptions": {
     "plugins": [
@@ -23,74 +15,40 @@ Add the plugin to your `tsconfig.json`:
     ]
   }
 }
-```
-
-## VS Code Setup
-
-VS Code uses its own TypeScript version by default. To use the workspace version (which includes plugins):
-
-1. Open the Command Palette (`Cmd/Ctrl + Shift + P`)
-
-2. Search for "TypeScript: Select TypeScript Version"
-
-3. Choose "Use Workspace Version"
-
->
-> Add this setting to your `.vscode/settings.json` to make it permanent:
-
-`.vscode/settings.json`
-```json
+``` ## VS Code Setup
+ VS Code uses its own TypeScript version by default. To use the workspace version (which includes plugins):
+ 1. Open the Command Palette (`Cmd/Ctrl + Shift + P`)
+ 2. Search for "TypeScript: Select TypeScript Version"
+ 3. Choose "Use Workspace Version"
+  **Tip Add this setting to your `.vscode/settings.json` to make it permanent: ```
 {
   "typescript.tsdk": "node_modules/typescript/lib"
 }
-```
-
-## Features
-
-### Error Reporting
-
-Errors in macro-generated code are reported at the `@derive` decorator position:
-
-```typescript
-/** @derive(Debug) */  // <- Errors appear here
+``` ## Features
+ ### Error Reporting
+ Errors in macro-generated code are reported at the `@derive` decorator position:
+ ```
+/** @derive(Debug) */  // **<- Errors appear here
 class User {
   name: string;
 }
-```
-
-### Completions
-
-The plugin provides completions for generated methods:
-
-```typescript
+``` ### Completions
+ The plugin provides completions for generated methods:
+ ```
 const user = new User("Alice");
 user.to  // Suggests: toString(), toJSON(), etc.
-```
-
-### Type Information
-
-Hover over generated methods to see their types:
-
-```typescript
+``` ### Type Information
+ Hover over generated methods to see their types:
+ ```
 // Hover over 'clone' shows:
 // (method) User.clone(): User
 const copy = user.clone();
-```
-
-## Troubleshooting
-
-### Plugin Not Loading
-
-1. Ensure you're using the workspace TypeScript version
-
-2. Restart the TypeScript server (Command Palette → "TypeScript: Restart TS Server")
-
-3. Check that the plugin is listed in `tsconfig.json`
-
-### Errors Not Showing
-
-If errors from macros aren't appearing:
-
-1. Make sure the Vite plugin is also installed (for source file watching)
-
-2. Check that your file is saved (plugins process on save)
+``` ## Troubleshooting
+ ### Plugin Not Loading
+ 1. Ensure you're using the workspace TypeScript version
+ 2. Restart the TypeScript server (Command Palette → "TypeScript: Restart TS Server")
+ 3. Check that the plugin is listed in `tsconfig.json`
+ ### Errors Not Showing
+ If errors from macros aren't appearing:
+ 1. Make sure the Vite plugin is also installed (for source file watching)
+ 2. Check that your file is saved (plugins process on save)

package/docs/integration/vite-plugin.md

@@ -1,19 +1,11 @@
 # Vite Plugin
-
-*The Vite plugin provides build-time macro expansion, transforming your code during development and production builds.*
-
-## Installation
-
-```bash
+ *The Vite plugin provides build-time macro expansion, transforming your code during development and production builds.*
+ ## Installation
+ ```
 npm install -D @macroforge/vite-plugin
-```
-
-## Configuration
-
-Add the plugin to your `vite.config.ts`:
-
-`vite.config.ts`
-```typescript
+``` ## Configuration
+ Add the plugin to your `vite.config.ts`:
+ ```
 import macroforge from "@macroforge/vite-plugin";
 import { defineConfig } from "vite";
 
@@ -22,11 +14,8 @@ export default defineConfig({
     macroforge()
   ]
 });
-```
-
-## Options
-
-```typescript
+``` ## Options
+ ```
 macroforge({
   // Generate .d.ts files for expanded code
   generateTypes: true,
@@ -44,36 +33,16 @@ macroforge({
   include: ["**/*.ts", "**/*.tsx"],
   exclude: ["node_modules/**"]
 })
-```
-
-### Option Reference
-
-| `generateTypes` 
-| `boolean` 
-| `true` 
-| Generate .d.ts files 
-
-| `typesOutputDir` 
-| `string` 
-| `.macroforge/types` 
-| Where to write type files 
-
-| `emitMetadata` 
-| `boolean` 
-| `false` 
-| Emit macro metadata files 
-
-| `keepDecorators` 
-| `boolean` 
-| `false` 
-| Keep decorators in output
-
-## Framework Integration
-
-### React (Vite)
-
-`vite.config.ts`
-```typescript
+``` ### Option Reference
+ | Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `generateTypes` | `boolean` | `true` | Generate .d.ts files |
+| `typesOutputDir` | `string` | `.macroforge/types` | Where to write type files |
+| `emitMetadata` | `boolean` | `false` | Emit macro metadata files |
+| `keepDecorators` | `boolean` | `false` | Keep decorators in output |
+ ## Framework Integration
+ ### React (Vite)
+ ```
 import macroforge from "@macroforge/vite-plugin";
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
@@ -84,12 +53,8 @@ export default defineConfig({
     react()
   ]
 });
-```
-
-### SvelteKit
-
-`vite.config.ts`
-```typescript
+``` ### SvelteKit
+ ```
 import macroforge from "@macroforge/vite-plugin";
 import { sveltekit } from "@sveltejs/kit/vite";
 import { defineConfig } from "vite";
@@ -100,27 +65,13 @@ export default defineConfig({
     sveltekit()
   ]
 });
-```
-
->
-> Always place the Macroforge plugin before other framework plugins to ensure macros are expanded first.
-
-## Development Server
-
-During development, the plugin:
-
-- Watches for file changes
-
-- Expands macros on save
-
-- Provides HMR support for expanded code
-
-## Production Build
-
-During production builds, the plugin:
-
-- Expands all macros in the source files
-
-- Generates type declaration files
-
-- Strips `@derive` decorators from output
+``` > **Note:** Always place the Macroforge plugin before other framework plugins to ensure macros are expanded first. ## Development Server
+ During development, the plugin:
+ - Watches for file changes
+ - Expands macros on save
+ - Provides HMR support for expanded code
+ ## Production Build
+ During production builds, the plugin:
+ - Expands all macros in the source files
+ - Generates type declaration files
+ - Strips `@derive` decorators from output