@macroforge/mcp-server 0.1.17 → 0.1.20

package/docs/getting-started/first-macro.md

@@ -6,59 +6,7 @@
 
 Start by creating a simple `User` class. We'll use the `@derive` decorator to automatically generate methods.
 
-`user.ts`
-```typescript
-import { Debug, Clone, Eq } from "macroforge";
-
-/** @derive(Debug, Clone, Eq) */
-export class User {
-  name: string;
-  age: number;
-  email: string;
-
-  constructor(name: string, age: number, email: string) {
-    this.name = name;
-    this.age = age;
-    this.email = email;
-  }
-}
-```
-
-## What Gets Generated
-
-After macro expansion, your class will have these methods:
-
-`user.ts (expanded)`
-```typescript
-export class User {
-  name: string;
-  age: number;
-  email: string;
-
-  constructor(name: string, age: number, email: string) {
-    this.name = name;
-    this.age = age;
-    this.email = email;
-  }
-
-  // Generated by Debug
-  toString(): string {
-    return \`User { name: \${this.name}, age: \${this.age}, email: \${this.email} }\`;
-  }
-
-  // Generated by Clone
-  clone(): User {
-    return new User(this.name, this.age, this.email);
-  }
-
-  // Generated by Eq
-  equals(other: User): boolean {
-    return this.name === other.name
-      && this.age === other.age
-      && this.email === other.email;
-  }
-}
-```
+<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
 
 ## Using the Generated Methods
 
@@ -84,32 +32,18 @@ console.log(user.equals(different)); // false
 
 You can customize how macros work using field-level decorators. For example, with the Debug macro:
 
-```typescript
-/** @derive(Debug) */
-export class User {
-  /** @debug({ rename: "userId" }) */
-  id: number;
-
-  name: string;
-
-  /** @debug({ skip: true }) */
-  password: string;
-
-  constructor(id: number, name: string, password: string) {
-    this.id = id;
-    this.name = name;
-    this.password = password;
-  }
-}
+<MacroExample before={data.examples.customizing.before} after={data.examples.customizing.after} />
 
+```typescript
 const user = new User(42, "Alice", "secret123");
 console.log(user.toString());
 // Output: User { userId: 42, name: Alice }
 // Note: 'id' is renamed to 'userId', 'password' is skipped
 ```
 
->
-> Field-level decorators let you control exactly how each field is handled by the macro.
+<Alert type="tip" title="Field-level decorators">
+Field-level decorators let you control exactly how each field is handled by the macro.
+</Alert>
 
 ## Next Steps
 

package/docs/getting-started/installation.md

@@ -4,9 +4,9 @@
 
 ## Requirements
 
-- Node.js 18.0 or later
+- Node.js 24.0 or later
 
-- TypeScript 5.0 or later
+- TypeScript 5.9 or later
 
 ## Install the Package
 

package/docs/integration/integration-overview.md

@@ -27,20 +27,27 @@ npm install -D @macroforge/typescript-plugin @macroforge/vite-plugin
 
 ## How They Work Together
 
-```text
-┌────────────────────────────────────────────────────────┐
-│                   Development Flow                      │
-├────────────────────────────────────────────────────────┤
-│                                                         │
-│  Your Code ──► TypeScript Plugin ──► IDE Feedback       │
-│      │                                                  │
-│      │                                                  │
-│      └──────► Vite Plugin ────────► Dev Server          │
-│                     │                                   │
-│                     └─────────────► Production Build    │
-│                                                         │
-└────────────────────────────────────────────────────────┘
-```
+<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
 

package/docs/integration/mcp-server.md

@@ -0,0 +1,84 @@
+# 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
+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`
+```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`
+```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:
+
+```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:
+
+| `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`.

package/docs/integration/svelte-preprocessor.md

@@ -0,0 +1,152 @@
+# Svelte Preprocessor
+
+*The Svelte preprocessor expands Macroforge macros in `<script>` blocks before Svelte compilation, enabling seamless macro usage in Svelte components.*
+
+## Installation
+
+```bash
+npm install -D @macroforge/svelte-preprocessor
+```
+
+## Configuration
+
+Add the preprocessor to your `svelte.config.js`:
+
+`svelte.config.js`
+```javascript
+import adapter from '@sveltejs/adapter-auto';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+import { macroforgePreprocess } from '@macroforge/svelte-preprocessor';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  preprocess: [
+    macroforgePreprocess(),  // Expand macros FIRST
+    vitePreprocess()          // Then handle TypeScript/CSS
+  ],
+
+  kit: {
+    adapter: adapter()
+  }
+};
+
+export default config;
+```
+
+> **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:
+
+`UserCard.svelte`
+```svelte
+User: {user.name}
+
+```
+
+## Options
+
+```typescript
+macroforgePreprocess({
+  // Keep @derive decorators in output (for debugging)
+  keepDecorators: false,
+
+  // 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
+// svelte.config.js
+import { macroforgePreprocess } from '@macroforge/svelte-preprocessor';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+export default {
+  preprocess: [
+    macroforgePreprocess(),
+    vitePreprocess()
+  ]
+};
+```
+
+`vite.config.ts`
+```typescript
+// vite.config.ts
+import macroforge from '@macroforge/vite-plugin';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    macroforge(),  // For .ts files
+    sveltekit()
+  ]
+});
+```
+
+## Using with Vitest
+
+The preprocessor works seamlessly with Vitest for testing Svelte components:
+
+`vitest.config.ts`
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { svelteTesting } from '@testing-library/svelte/vite';
+import macroforge from '@macroforge/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    macroforge(),
+    sveltekit(),
+    svelteTesting()
+  ],
+  test: {
+    environment: 'jsdom',
+    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
+
+```

package/docs/language-servers/svelte.md

@@ -0,0 +1,80 @@
+# Svelte Language Server
+
+*`@macroforge/svelte-language-server` provides full Svelte IDE support with macroforge integration.*
+
+<Alert type="warning" title="Developer Installation Required">
+This package is not yet published as an official extension. You'll need to build and install it manually.
+</Alert>
+
+## Features
+
+- **Svelte syntax diagnostics** - Errors and warnings in .svelte files
+
+- **HTML support** - Hover info, autocompletions, Emmet, outline symbols
+
+- **CSS/SCSS/LESS** - Diagnostics, hover, completions, formatting, Emmet, color picking
+
+- **TypeScript/JavaScript** - Full language features with macroforge macro expansion
+
+- **Go-to-definition** - Navigate to macro-generated code
+
+- **Code actions** - Quick fixes and refactorings
+
+## Installation
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/rymskip/macroforge-ts.git
+cd macroforge-ts
+```
+
+### 2. Build the Language Server
+
+```bash
+# Install dependencies
+npm install
+
+# Build the Svelte language server
+cd packages/svelte-language-server
+npm run build
+```
+
+### 3. Configure Your Editor
+
+The language server exposes a `svelteserver` binary that implements the Language Server Protocol (LSP). Configure your editor to use it:
+
+```bash
+# The binary is located at:
+./packages/svelte-language-server/bin/server.js
+```
+
+## Package Info
+
+| Package 
+| `@macroforge/svelte-language-server` 
+
+| Version 
+| 0.1.7 
+
+| CLI Command 
+| `svelteserver` 
+
+| Node Version 
+| >= 18.0.0
+
+## How It Works
+
+The Svelte language server extends the standard Svelte language tooling with macroforge integration:
+
+1. Parses `.svelte` files and extracts TypeScript/JavaScript blocks
+
+2. Expands macros using the `@macroforge/typescript-plugin`
+
+3. Maps diagnostics back to original source positions
+
+4. Provides completions for macro-generated methods
+
+## Using with Zed
+
+For Zed editor, see the [Zed Extensions]({base}/docs/language-servers/zed) page for the dedicated `svelte-macroforge` extension.

package/docs/language-servers/zed.md

@@ -0,0 +1,84 @@
+# Zed Extensions
+
+*Macroforge provides two extensions for the [Zed editor](https://zed.dev): one for TypeScript via VTSLS, and one for Svelte.*
+
+<Alert type="warning" title="Developer Installation Required">
+These extensions are not yet in the Zed extension registry. You'll need to install them as developer extensions.
+</Alert>
+
+## Available Extensions
+
+| `vtsls-macroforge` 
+| VTSLS with macroforge support for TypeScript 
+| `crates/extensions/vtsls-macroforge` 
+
+| `svelte-macroforge` 
+| Svelte language support with macroforge 
+| `crates/extensions/svelte-macroforge`
+
+## Installation
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/rymskip/macroforge-ts.git
+cd macroforge-ts
+```
+
+### 2. Build the Extension
+
+Build the extension you want to use:
+
+```bash
+# For VTSLS (TypeScript)
+cd crates/extensions/vtsls-macroforge
+
+# Or for Svelte
+cd crates/extensions/svelte-macroforge
+```
+
+### 3. Install as Dev Extension in Zed
+
+In Zed, open the command palette and run **zed: install dev extension**, then select the extension directory.
+
+Alternatively, symlink the extension to your Zed extensions directory:
+
+```bash
+# macOS
+ln -s /path/to/macroforge-ts/crates/extensions/vtsls-macroforge ~/Library/Application\\ Support/Zed/extensions/installed/vtsls-macroforge
+
+# Linux
+ln -s /path/to/macroforge-ts/crates/extensions/vtsls-macroforge ~/.config/zed/extensions/installed/vtsls-macroforge
+```
+
+## vtsls-macroforge
+
+This extension wraps [VTSLS](https://github.com/yioneko/vtsls) (a TypeScript language server) with macroforge integration. It provides:
+
+- Full TypeScript language features
+
+- Macro expansion at edit time
+
+- Accurate error positions in original source
+
+- Completions for macro-generated methods
+
+## svelte-macroforge
+
+This extension provides Svelte support using the `@macroforge/svelte-language-server`. It includes:
+
+- Svelte component syntax support
+
+- HTML, CSS, and TypeScript features
+
+- Macroforge integration in script blocks
+
+## Troubleshooting
+
+### Extension not loading
+
+Make sure you've restarted Zed after installing the extension. Check the Zed logs for any error messages.
+
+### Macros not expanding
+
+Ensure your project has the `macroforge` package installed and a valid `tsconfig.json` with the TypeScript plugin configured.

package/docs/roadmap/roadmap.md

@@ -0,0 +1,131 @@
+# Roadmap
+
+*Planned features and improvements for Macroforge. This roadmap reflects our current priorities but may change based on community feedback.*
+
+## IDE Extensions
+
+Bring Macroforge support directly into your favorite editors with native extensions.
+
+| VS Code / Cursor 
+| Planned 
+| Native extension with macro expansion preview, error highlighting, and completions 
+
+| Zed 
+| Available 
+| Full support via vtsls-macroforge and svelte-macroforge extensions 
+
+| Neovim 
+| Considering 
+| LSP integration for Neovim users 
+
+| JetBrains (WebStorm) 
+| Considering 
+| Plugin for WebStorm and other JetBrains IDEs
+
+## Framework Support
+
+Expanding Macroforge to work seamlessly with popular frontend frameworks.
+
+| Svelte / SvelteKit 
+| Available 
+| Full support via svelte-language-server and Vite plugin 
+
+| React 
+| Planned 
+| React-specific macros and integration with React tooling 
+
+| Vue 
+| Planned 
+| Vue SFC support and Vue-specific derive macros 
+
+| Angular 
+| Planned 
+| Angular decorator integration and CLI support 
+
+| Solid 
+| Planned 
+| SolidJS integration
+
+## Pure TypeScript Macro Creation
+
+While Rust provides the best performance and type safety, we recognize that not everyone wants to write Rust. We're exploring options for writing macros in pure TypeScript.
+
+| TypeScript Macro API 
+| Planned 
+| Define macros using TypeScript with a simple API 
+
+| Template Strings 
+| Planned 
+| Generate code using tagged template literals 
+
+| AST Helpers 
+| Planned 
+| TypeScript utilities for working with the AST
+
+## Built-in Macros
+
+Expanding the library of built-in derive macros.
+
+| Debug, Clone, PartialEq, Ord, Hash 
+| Available 
+| Core derive macros 
+
+| Serialize, Deserialize 
+| Available 
+| JSON serialization with validation 
+
+| Builder 
+| Planned 
+| Generate builder pattern for classes 
+
+| Immutable 
+| Considering 
+| Generate immutable update methods (with, set)
+
+## Distribution & Packaging
+
+Making it easier to publish and share custom macros.
+
+| Native Node Binaries 
+| Available 
+| Platform-specific binaries for maximum performance 
+
+| WASM Binary Generation 
+| Planned 
+| Cross-platform WebAssembly binaries for easier macro distribution 
+
+| Macro Registry 
+| Considering 
+| Central registry for discovering and sharing community macros
+
+## Tooling & DX
+
+Improvements to the developer experience.
+
+| CLI Expansion 
+| Available 
+| Expand macros from the command line 
+
+| Macro Playground 
+| Planned 
+| Web-based playground to test macros 
+
+| create-macroforge 
+| Planned 
+| Scaffolding tool for new macro projects 
+
+| Macro Debugging 
+| Considering 
+| Step-through debugging for macro expansion
+
+## Contributing
+
+Interested in helping? We welcome contributions of all kinds:
+
+- Feature requests and feedback on [GitHub Issues](https://github.com/rymskip/macroforge-ts/issues)
+
+- Pull requests for new macros or improvements
+
+- Documentation improvements
+
+- Framework integrations