@macroforge/mcp-server 0.1.17

package/docs/integration/vite-plugin.md

@@ -0,0 +1,126 @@
+# Vite Plugin
+
+*The Vite plugin provides build-time macro expansion, transforming your code during development and production builds.*
+
+## Installation
+
+```bash
+npm install -D @macroforge/vite-plugin
+```
+
+## Configuration
+
+Add the plugin to your `vite.config.ts`:
+
+`vite.config.ts`
+```typescript
+import macroforge from "@macroforge/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    macroforge()
+  ]
+});
+```
+
+## Options
+
+```typescript
+macroforge({
+  // Generate .d.ts files for expanded code
+  generateTypes: true,
+
+  // Output directory for generated types
+  typesOutputDir: ".macroforge/types",
+
+  // Emit metadata files for debugging
+  emitMetadata: false,
+
+  // Keep @derive decorators in output (for debugging)
+  keepDecorators: false,
+
+  // File patterns to process
+  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
+import macroforge from "@macroforge/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    macroforge(),  // Before React plugin
+    react()
+  ]
+});
+```
+
+### SvelteKit
+
+`vite.config.ts`
+```typescript
+import macroforge from "@macroforge/vite-plugin";
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    macroforge(),  // Before SvelteKit
+    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

package/docs/language-servers/ls-overview.md

@@ -0,0 +1,47 @@
+# Language Servers
+
+*Macroforge provides language server integrations for enhanced IDE support beyond the TypeScript plugin.*
+
+<Alert type="warning" title="Work in Progress">
+Language server integrations are currently experimental. They work in the repository but are not yet published as official extensions. You'll need to fork the repo and install them as developer extensions.
+</Alert>
+
+## Overview
+
+While the [TypeScript Plugin]({base}/docs/integration/typescript-plugin) provides macro support in any TypeScript-aware editor, dedicated language servers offer deeper integration for specific frameworks and editors.
+
+| [Svelte Language Server]({base}/docs/language-servers/svelte) 
+| Full Svelte support with macroforge 
+| Working (dev install) 
+
+| [Zed Extensions]({base}/docs/language-servers/zed) 
+| VTSLS and Svelte for Zed editor 
+| Working (dev install)
+
+## Current Status
+
+The language servers are functional and used during development of macroforge itself. However, they require manual installation:
+
+1. Fork or clone the [macroforge-ts repository](https://github.com/rymskip/macroforge-ts)
+
+2. Build the extension you need
+
+3. Install it as a developer extension in your editor
+
+See the individual pages for detailed installation instructions.
+
+## Roadmap
+
+We're working on official extension releases for:
+
+- VS Code (via VTSLS)
+
+- Zed (native extensions)
+
+- Other editors with LSP support
+
+## Detailed Guides
+
+- [Svelte Language Server]({base}/docs/language-servers/svelte) - Full Svelte IDE support
+
+- [Zed Extensions]({base}/docs/language-servers/zed) - VTSLS and Svelte for Zed

package/docs/language-servers/svelte-ls.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-extensions.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/sections.json

@@ -0,0 +1,258 @@
+[
+  {
+    "id": "installation",
+    "title": "Installation",
+    "category": "getting-started",
+    "category_title": "Getting Started",
+    "path": "getting-started/installation.md",
+    "use_cases": "setup, install, npm, getting started, quick start, init"
+  },
+  {
+    "id": "first-macro",
+    "title": "First Macro",
+    "category": "getting-started",
+    "category_title": "Getting Started",
+    "path": "getting-started/first-macro.md",
+    "use_cases": "tutorial, example, hello world, beginner, learn"
+  },
+  {
+    "id": "how-macros-work",
+    "title": "How Macros Work",
+    "category": "concepts",
+    "category_title": "Core Concepts",
+    "path": "concepts/how-macros-work.md",
+    "use_cases": "architecture, overview, understanding, basics, fundamentals"
+  },
+  {
+    "id": "derive-system",
+    "title": "The Derive System",
+    "category": "concepts",
+    "category_title": "Core Concepts",
+    "path": "concepts/derive-system.md",
+    "use_cases": "@derive, decorator, annotation, derive macro"
+  },
+  {
+    "id": "architecture",
+    "title": "Architecture",
+    "category": "concepts",
+    "category_title": "Core Concepts",
+    "path": "concepts/architecture.md",
+    "use_cases": "internals, rust, swc, napi, how it works"
+  },
+  {
+    "id": "macros-overview",
+    "title": "Overview",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/macros-overview.md",
+    "use_cases": "all macros, list, available macros, macro list"
+  },
+  {
+    "id": "debug",
+    "title": "Debug",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/debug.md",
+    "use_cases": "toString, debugging, logging, output, print"
+  },
+  {
+    "id": "clone",
+    "title": "Clone",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/clone.md",
+    "use_cases": "copy, clone, duplicate, shallow copy, immutable"
+  },
+  {
+    "id": "default",
+    "title": "Default",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/default.md",
+    "use_cases": "default values, factory, initialization, constructor"
+  },
+  {
+    "id": "hash",
+    "title": "Hash",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/hash.md",
+    "use_cases": "hashCode, hashing, hash map, equality, hash function"
+  },
+  {
+    "id": "ord",
+    "title": "Ord",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/ord.md",
+    "use_cases": "compareTo, ordering, sorting, comparison, total order"
+  },
+  {
+    "id": "partial-eq",
+    "title": "PartialEq",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/partial-eq.md",
+    "use_cases": "equals, equality, comparison, value equality"
+  },
+  {
+    "id": "partial-ord",
+    "title": "PartialOrd",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/partial-ord.md",
+    "use_cases": "compareTo, partial ordering, sorting, nullable comparison"
+  },
+  {
+    "id": "serialize",
+    "title": "Serialize",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/serialize.md",
+    "use_cases": "toJSON, serialization, json, api, data transfer"
+  },
+  {
+    "id": "deserialize",
+    "title": "Deserialize",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize.md",
+    "use_cases": "fromJSON, deserialization, parsing, validation, json"
+  },
+  {
+    "id": "custom-overview",
+    "title": "Overview",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/custom-overview.md",
+    "use_cases": "custom, extending, creating macros, own macro"
+  },
+  {
+    "id": "rust-setup",
+    "title": "Rust Setup",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/rust-setup.md",
+    "use_cases": "rust, cargo, napi, compilation, building"
+  },
+  {
+    "id": "ts-macro-derive",
+    "title": "ts_macro_derive",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-macro-derive.md",
+    "use_cases": "attribute, proc macro, derive attribute, rust macro"
+  },
+  {
+    "id": "ts-quote",
+    "title": "Template Syntax",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote.md",
+    "use_cases": "ts_quote, template, code generation, interpolation"
+  },
+  {
+    "id": "integration-overview",
+    "title": "Overview",
+    "category": "integration",
+    "category_title": "Integration",
+    "path": "integration/integration-overview.md",
+    "use_cases": "setup, integration, tools, ecosystem"
+  },
+  {
+    "id": "cli",
+    "title": "CLI",
+    "category": "integration",
+    "category_title": "Integration",
+    "path": "integration/cli.md",
+    "use_cases": "command line, macroforge command, expand, terminal"
+  },
+  {
+    "id": "typescript-plugin",
+    "title": "TypeScript Plugin",
+    "category": "integration",
+    "category_title": "Integration",
+    "path": "integration/typescript-plugin.md",
+    "use_cases": "vscode, ide, language server, intellisense, autocomplete"
+  },
+  {
+    "id": "vite-plugin",
+    "title": "Vite Plugin",
+    "category": "integration",
+    "category_title": "Integration",
+    "path": "integration/vite-plugin.md",
+    "use_cases": "vite, build, bundler, react, svelte, sveltekit"
+  },
+  {
+    "id": "configuration",
+    "title": "Configuration",
+    "category": "integration",
+    "category_title": "Integration",
+    "path": "integration/configuration.md",
+    "use_cases": "macroforge.json, config, settings, options"
+  },
+  {
+    "id": "ls-overview",
+    "title": "Overview",
+    "category": "language-servers",
+    "category_title": "Language Servers",
+    "path": "language-servers/ls-overview.md",
+    "use_cases": "lsp, language server, editor support"
+  },
+  {
+    "id": "svelte-ls",
+    "title": "Svelte",
+    "category": "language-servers",
+    "category_title": "Language Servers",
+    "path": "language-servers/svelte-ls.md",
+    "use_cases": "svelte, svelte language server, .svelte files"
+  },
+  {
+    "id": "zed-extensions",
+    "title": "Zed Extensions",
+    "category": "language-servers",
+    "category_title": "Language Servers",
+    "path": "language-servers/zed-extensions.md",
+    "use_cases": "zed, zed editor, extension"
+  },
+  {
+    "id": "api-overview",
+    "title": "Overview",
+    "category": "api",
+    "category_title": "API Reference",
+    "path": "api/api-overview.md",
+    "use_cases": "api, functions, exports, programmatic"
+  },
+  {
+    "id": "expand-sync",
+    "title": "expandSync()",
+    "category": "api",
+    "category_title": "API Reference",
+    "path": "api/expand-sync.md",
+    "use_cases": "expandSync, expand, transform, macro expansion"
+  },
+  {
+    "id": "transform-sync",
+    "title": "transformSync()",
+    "category": "api",
+    "category_title": "API Reference",
+    "path": "api/transform-sync.md",
+    "use_cases": "transformSync, transform, metadata, low-level"
+  },
+  {
+    "id": "native-plugin",
+    "title": "NativePlugin",
+    "category": "api",
+    "category_title": "API Reference",
+    "path": "api/native-plugin.md",
+    "use_cases": "NativePlugin, caching, language server, stateful"
+  },
+  {
+    "id": "position-mapper",
+    "title": "PositionMapper",
+    "category": "api",
+    "category_title": "API Reference",
+    "path": "api/position-mapper.md",
+    "use_cases": "PositionMapper, source map, diagnostics, position"
+  }
+]

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@macroforge/mcp-server",
+  "version": "0.1.17",
+  "description": "MCP server for Macroforge documentation and code analysis",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "macroforge-mcp": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rymskip/macroforge-ts.git",
+    "directory": "packages/mcp-server"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "build:docs": "node scripts/extract-docs.cjs",
+    "dev": "npx @modelcontextprotocol/inspector dist/index.js",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "macroforge": "^0.1.17"
+  },
+  "peerDependenciesMeta": {
+    "macroforge": {
+      "optional": true
+    }
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "keywords": [
+    "mcp",
+    "macroforge",
+    "typescript",
+    "macros",
+    "documentation"
+  ],
+  "license": "MIT"
+}