@macroforge/mcp-server 0.1.40 → 0.1.49

package/docs/integration/configuration.md

@@ -1,73 +1,116 @@
 # Configuration
- *Macroforge can be configured with a `macroforge.json` file in your project root.*
- ## Configuration File
- Create a `macroforge.json` file:
- ```
-{
-  "allowNativeMacros": true,
-  "macroPackages": [],
-  "keepDecorators": false,
-  "limits": {
-    "maxExecutionTimeMs": 5000,
-    "maxMemoryBytes": 104857600,
-    "maxOutputSize": 10485760,
-    "maxDiagnostics": 100
-  }
-}
-``` ## Options Reference
- ### allowNativeMacros
- | Type | `boolean` |
-| Default | `true` |
- Enable or disable native (Rust) macro packages. Set to `false` to only allow built-in macros.
- ### macroPackages
- | Type | `string[]` |
-| Default | `[]` |
- List of npm packages that provide macros. Macroforge will look for macros in these packages.
- ```
-{
-  "macroPackages": [
-    "@my-org/custom-macros",
-    "community-macros"
-  ]
-}
-``` ### keepDecorators
- | Type | `boolean` |
-| Default | `false` |
- Keep `@derive` decorators in the output. Useful for debugging.
- ### limits
- Configure resource limits for macro expansion:
- ```
-{
-  "limits": {
-    // Maximum time for a single macro expansion (ms)
-    "maxExecutionTimeMs": 5000,
-
-    // Maximum memory usage (bytes)
-    "maxMemoryBytes": 104857600,  // 100MB
-
-    // Maximum size of generated code (bytes)
-    "maxOutputSize": 10485760,    // 10MB
-
-    // Maximum number of diagnostics per file
-    "maxDiagnostics": 100
-  }
-}
-``` ## Macro Runtime Overrides
- Override settings for specific macros:
- ```
-{
-  "macroRuntimeOverrides": {
-    "@my-org/macros": {
-      "maxExecutionTimeMs": 10000
-    }
-  }
-}
-```  **Warning Be careful when increasing limits, as this could allow malicious macros to consume excessive resources. ## Environment Variables
- Some settings can be overridden with environment variables:
- | Variable | Description |
-| --- | --- |
-| `MACROFORGE_DEBUG` | Enable debug logging |
+
+Macroforge can be configured with a `macroforge.json` file in your project root.
+
+## Configuration File
+
+Create a `macroforge.json` file:
+
+macroforge.json 
+
+```
+{
+  "allowNativeMacros": true,
+  "macroPackages": [],
+  "keepDecorators": false,
+  "limits": {
+    "maxExecutionTimeMs": 5000,
+    "maxMemoryBytes": 104857600,
+    "maxOutputSize": 10485760,
+    "maxDiagnostics": 100
+  }
+}
+```
+
+## Options Reference
+
+### allowNativeMacros
+
+| Type    | `boolean` |
+| Default | `true`    |
+
+Enable or disable native (Rust) macro packages. Set to `false` to only allow built-in macros.
+
+### macroPackages
+
+| Type    | `string[]` |
+| Default | `[]`       |
+
+List of npm packages that provide macros. Macroforge will look for macros in these packages.
+
+JSON
+
+```
+{
+  "macroPackages": [
+    "@my-org/custom-macros",
+    "community-macros"
+  ]
+}
+```
+
+### keepDecorators
+
+| Type    | `boolean` |
+| Default | `false`   |
+
+Keep `@derive` decorators in the output. Useful for debugging.
+
+### limits
+
+Configure resource limits for macro expansion:
+
+JSON
+
+```
+{
+  "limits": {
+    // Maximum time for a single macro expansion (ms)
+    "maxExecutionTimeMs": 5000,
+
+    // Maximum memory usage (bytes)
+    "maxMemoryBytes": 104857600,  // 100MB
+
+    // Maximum size of generated code (bytes)
+    "maxOutputSize": 10485760,    // 10MB
+
+    // Maximum number of diagnostics per file
+    "maxDiagnostics": 100
+  }
+}
+```
+
+## Macro Runtime Overrides
+
+Override settings for specific macros:
+
+JSON
+
+```
+{
+  "macroRuntimeOverrides": {
+    "@my-org/macros": {
+      "maxExecutionTimeMs": 10000
+    }
+  }
+}
+```
+
+Warning
+
+Be careful when increasing limits, as this could allow malicious macros to consume excessive resources.
+
+## Environment Variables
+
+Some settings can be overridden with environment variables:
+
+| Variable              | Description          |
+| --------------------- | -------------------- |
+| `MACROFORGE_DEBUG`    | Enable debug logging |
 | `MACROFORGE_LOG_FILE` | Write logs to a file |
- ```
-MACROFORGE_DEBUG=1 npm run dev
-```**
+
+Bash
+
+```
+MACROFORGE_DEBUG=1 npm run dev
+```

package/docs/integration/integration-overview.md

@@ -1,19 +1,56 @@
 # Integration
- *Macroforge integrates with your development workflow through IDE plugins and build tool integration.*
- ## Overview
- | Integration | Purpose | Package |
-| --- | --- | --- |
+
+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
- <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)
+| 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
+
+```
+# Install both plugins
+npm install -D @macroforge/typescript-plugin @macroforge/vite-plugin
+```
+
+## How They Work Together
+
+Your Code
+
+TypeScript with @derive decorators
+
+TypeScript Plugin
+
+Language service integration
+
+IDE Feedback
+
+Errors & completions
+
+Vite Plugin
+
+Build-time transformation
+
+Dev Server
+
+Hot reload
+
+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,45 +1,86 @@
 # 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`:
- ```
-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:
- ```
-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:
- ```
-{
-    "mcpServers": {
-        "macroforge": {
-            "command": "npx",
-            "args": ["-y", "@macroforge/mcp-server"]
-        }
-    }
-}
-``` ## 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):
- ```
+
+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
+
+```
+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
+
+```
+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 
+
+```
+{
+    "mcpServers": {
+        "macroforge": {
+            "command": "npx",
+            "args": ["-y", "@macroforge/mcp-server"]
+        }
+    }
+}
+```
+
+## 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 
+
+```
 [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:
- ```
-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:
- | Tool | Description |
-| --- | --- |
-| `list-sections` | Lists all available Macroforge documentation sections |
-| `get-documentation` | Retrieves full documentation for one or more sections |
+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 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:
+
+| 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.
+| `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`.