@macroforge/mcp-server 0.1.33 → 0.1.35

package/README.md

@@ -0,0 +1,68 @@
+# @macroforge/mcp-server
+
+MCP server for Macroforge documentation and code analysis
+
+[![npm version](https://badge.fury.io/js/%40macroforge%2Fmcp-server.svg)](https://www.npmjs.com/package/@macroforge/mcp-server)
+
+## Overview
+
+@macroforge/mcp-server
+
+Macroforge MCP (Model Context Protocol) Server
+
+This module provides the main entry point for the Macroforge MCP server,
+which enables AI assistants and other MCP clients to access Macroforge
+documentation, validate code with @derive decorators, and expand macros.
+
+The server communicates over stdio transport and exposes the following tools:
+- `list-sections` - List available documentation sections
+- `get-documentation` - Retrieve documentation content
+- `macroforge-autofixer` - Validate TypeScript code with @derive decorators
+- `expand-code` - Expand Macroforge macros and show generated code
+- `get-macro-info` - Get documentation for macros and decorators
+
+@example
+```bash
+# Run the server directly
+npx @macroforge/mcp-server
+
+# Or configure in your MCP client settings
+{
+"mcpServers": {
+"macroforge": {
+"command": "npx",
+"args": ["@macroforge/mcp-server"]
+}
+}
+}
+```
+
+## Installation
+
+```bash
+npm install @macroforge/mcp-server
+```
+
+## Examples
+
+```typescript
+# Run the server directly
+npx @macroforge/mcp-server
+# Or configure in your MCP client settings
+{
+"mcpServers": {
+"macroforge": {
+"command": "npx",
+"args": ["@macroforge/mcp-server"]
+}
+}
+}
+```
+
+## Documentation
+
+See the [full documentation](https://macroforge.dev/docs/api/reference/typescript/mcp-server) on the Macroforge website.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,3 +1,35 @@
 #!/usr/bin/env node
+/**
+ * @module @macroforge/mcp-server
+ *
+ * Macroforge MCP (Model Context Protocol) Server
+ *
+ * This module provides the main entry point for the Macroforge MCP server,
+ * which enables AI assistants and other MCP clients to access Macroforge
+ * documentation, validate code with @derive decorators, and expand macros.
+ *
+ * The server communicates over stdio transport and exposes the following tools:
+ * - `list-sections` - List available documentation sections
+ * - `get-documentation` - Retrieve documentation content
+ * - `macroforge-autofixer` - Validate TypeScript code with @derive decorators
+ * - `expand-code` - Expand Macroforge macros and show generated code
+ * - `get-macro-info` - Get documentation for macros and decorators
+ *
+ * @example
+ * ```bash
+ * # Run the server directly
+ * npx @macroforge/mcp-server
+ *
+ * # Or configure in your MCP client settings
+ * {
+ *   "mcpServers": {
+ *     "macroforge": {
+ *       "command": "npx",
+ *       "args": ["@macroforge/mcp-server"]
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG"}

package/dist/index.js

@@ -1,4 +1,36 @@
 #!/usr/bin/env node
+/**
+ * @module @macroforge/mcp-server
+ *
+ * Macroforge MCP (Model Context Protocol) Server
+ *
+ * This module provides the main entry point for the Macroforge MCP server,
+ * which enables AI assistants and other MCP clients to access Macroforge
+ * documentation, validate code with @derive decorators, and expand macros.
+ *
+ * The server communicates over stdio transport and exposes the following tools:
+ * - `list-sections` - List available documentation sections
+ * - `get-documentation` - Retrieve documentation content
+ * - `macroforge-autofixer` - Validate TypeScript code with @derive decorators
+ * - `expand-code` - Expand Macroforge macros and show generated code
+ * - `get-macro-info` - Get documentation for macros and decorators
+ *
+ * @example
+ * ```bash
+ * # Run the server directly
+ * npx @macroforge/mcp-server
+ *
+ * # Or configure in your MCP client settings
+ * {
+ *   "mcpServers": {
+ *     "macroforge": {
+ *       "command": "npx",
+ *       "args": ["@macroforge/mcp-server"]
+ *     }
+ *   }
+ * }
+ * ```
+ */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { readFileSync } from 'node:fs';
@@ -11,7 +43,20 @@ const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 const { name, version } = pkg;
 /**
- * Main function to start the MCP server
+ * Initializes and starts the Macroforge MCP server.
+ *
+ * This function performs the following setup:
+ * 1. Creates an MCP Server instance with name and version from package.json
+ * 2. Registers all Macroforge tools (documentation, validation, expansion)
+ * 3. Sets up error handling for server errors
+ * 4. Configures graceful shutdown on SIGINT (Ctrl+C)
+ * 5. Connects to stdio transport for client communication
+ *
+ * The server runs until terminated and logs status to stderr
+ * (stdout is reserved for MCP protocol communication).
+ *
+ * @returns A promise that resolves when the server is connected
+ * @throws Will exit the process with code 1 if server initialization fails
  */
 async function main() {
     // Create server instance with metadata

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,uCAAuC;AACvC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AACtC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AACpF,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;AAE9B;;GAEG;AACH,KAAK,UAAU,IAAI;IACjB,uCAAuC;IACvC,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;QACE,IAAI;QACJ,OAAO;KACR,EACD;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;SACV;KACF,CACF,CAAC;IAEF,qBAAqB;IACrB,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtB,wBAAwB;IACxB,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,EAAE,EAAE;QACzB,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC;IAEF,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,uBAAuB;IACvB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;AAC1D,CAAC;AAED,iBAAiB;AACjB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,uCAAuC;AACvC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AACtC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AACpF,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;AAE9B;;;;;;;;;;;;;;;GAeG;AACH,KAAK,UAAU,IAAI;IACjB,uCAAuC;IACvC,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;QACE,IAAI;QACJ,OAAO;KACR,EACD;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;SACV;KACF,CACF,CAAC;IAEF,qBAAqB;IACrB,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtB,wBAAwB;IACxB,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,EAAE,EAAE;QACzB,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC;IAEF,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,uBAAuB;IACvB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;AAC1D,CAAC;AAED,iBAAiB;AACjB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/docs-loader.d.ts

@@ -1,3 +1,45 @@
+/**
+ * @module docs-loader
+ *
+ * Documentation Loading and Search Utilities
+ *
+ * This module provides functionality for loading, searching, and retrieving
+ * Macroforge documentation sections. Documentation is stored as markdown files
+ * with metadata in `docs/sections.json`.
+ *
+ * Key features:
+ * - Loads documentation sections from disk with lazy content loading
+ * - Supports multiple search strategies (exact, partial, fuzzy, category)
+ * - Handles chunked documentation for large sections
+ * - Provides type-safe interfaces for documentation structure
+ *
+ * @example
+ * ```typescript
+ * import { loadSections, getSection, searchSections } from './docs-loader.js';
+ *
+ * const sections = loadSections();
+ * const debug = getSection(sections, 'debug');
+ * const matches = searchSections(sections, 'serialization');
+ * ```
+ */
+/**
+ * Represents a documentation section with metadata and optional content.
+ *
+ * Sections can be standalone or part of a chunked hierarchy for large documents.
+ * Chunked sections have a parent entry with `is_chunked: true` and child entries
+ * with `parent_id` pointing to the parent.
+ *
+ * @property id - Unique identifier for the section (e.g., "debug", "serde-validators")
+ * @property title - Human-readable title displayed to users
+ * @property category - Category slug for grouping (e.g., "macros", "guides")
+ * @property category_title - Human-readable category name
+ * @property path - Relative path to the markdown content file from docs directory
+ * @property use_cases - Comma-separated keywords describing when this doc is useful
+ * @property content - The actual markdown content (loaded lazily, undefined for chunked parents)
+ * @property is_chunked - True if this section is split into multiple sub-chunks
+ * @property parent_id - For sub-chunks, the ID of the parent section
+ * @property chunk_ids - For chunked parents, ordered list of child chunk IDs
+ */
 export interface Section {
     id: string;
     title: string;
@@ -11,23 +53,109 @@ export interface Section {
     chunk_ids?: string[];
 }
 /**
- * Load all documentation sections from the docs directory
+ * Loads all documentation sections from the docs directory.
+ *
+ * This function reads `docs/sections.json` for metadata and loads the markdown
+ * content for each section from disk. Chunked parent sections do not have their
+ * content loaded directly - their content is accessed through child chunks.
+ *
+ * @returns Array of Section objects with content loaded. Returns empty array if
+ *          sections.json is not found (with a warning logged to stderr).
+ *
+ * @example
+ * ```typescript
+ * const sections = loadSections();
+ * console.log(`Loaded ${sections.length} sections`);
+ * ```
  */
 export declare function loadSections(): Section[];
 /**
- * Get a section by ID or title (case-insensitive)
+ * Finds a section by ID or title using progressive matching strategies.
+ *
+ * The function attempts to match in the following order (stopping at first match):
+ * 1. Exact ID match (case-insensitive)
+ * 2. Exact title match (case-insensitive)
+ * 3. Partial ID match (query is substring of ID)
+ * 4. Partial title match (query is substring of title)
+ *
+ * @param sections - Array of sections to search through
+ * @param query - Search query (ID or title to find)
+ * @returns The first matching Section, or undefined if no match found
+ *
+ * @example
+ * ```typescript
+ * const debug = getSection(sections, 'debug');        // Exact ID match
+ * const serde = getSection(sections, 'Serialize');    // Exact title match
+ * const partial = getSection(sections, 'valid');      // Partial match on "validators"
+ * ```
  */
 export declare function getSection(sections: Section[], query: string): Section | undefined;
 /**
- * Get multiple sections by IDs or titles
+ * Retrieves multiple sections by their IDs or titles.
+ *
+ * Uses {@link getSection} for each query, deduplicating results if the same
+ * section matches multiple queries.
+ *
+ * @param sections - Array of sections to search through
+ * @param queries - Array of search queries (IDs or titles)
+ * @returns Array of unique matching Sections in the order they were found
+ *
+ * @example
+ * ```typescript
+ * const docs = getSections(sections, ['debug', 'serialize', 'clone']);
+ * // Returns all three sections if found
+ * ```
  */
 export declare function getSections(sections: Section[], queries: string[]): Section[];
 /**
- * Search sections by use_cases or content
+ * Performs a fuzzy search across sections using a weighted scoring algorithm.
+ *
+ * The search splits the query into keywords and scores each section based on
+ * where matches are found. Results are sorted by relevance score (highest first).
+ *
+ * ## Scoring Algorithm
+ *
+ * Each section is scored based on matches in different fields:
+ * - **ID match** (+10): Full query found in section ID
+ * - **Title match** (+10): Full query found in section title
+ * - **Use cases match** (+5 per keyword): Each query keyword found in use_cases
+ * - **Content match** (+1 per keyword): Each query keyword found in content
+ *
+ * The higher weights for ID/title ensure exact matches rank above content matches.
+ * Use cases are weighted moderately as they indicate intended use.
+ *
+ * @param sections - Array of sections to search through
+ * @param query - Search query (can contain multiple space-separated keywords)
+ * @returns Array of matching Sections sorted by relevance score (highest first)
+ *
+ * @example
+ * ```typescript
+ * // Single keyword search
+ * const results = searchSections(sections, 'validation');
+ *
+ * // Multi-keyword search (scores sections matching more keywords higher)
+ * const results = searchSections(sections, 'email url length');
+ * ```
  */
 export declare function searchSections(sections: Section[], query: string): Section[];
 /**
- * Get all sections in a category
+ * Filters sections by category slug or category title.
+ *
+ * Matches against both `category` (slug) and `category_title` (display name)
+ * to support flexible lookups.
+ *
+ * @param sections - Array of sections to filter
+ * @param category - Category slug or title to filter by (case-insensitive)
+ * @returns Array of Sections belonging to the specified category
+ *
+ * @example
+ * ```typescript
+ * // Filter by category slug
+ * const macros = getSectionsByCategory(sections, 'macros');
+ *
+ * // Filter by category title
+ * const guides = getSectionsByCategory(sections, 'Getting Started');
+ * ```
  */
 export declare function getSectionsByCategory(sections: Section[], category: string): Section[];
 //# sourceMappingURL=docs-loader.d.ts.map

package/dist/tools/docs-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-loader.d.ts","sourceRoot":"","sources":["../../src/tools/docs-loader.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,EAAE,CA0BxC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAoBlF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAW7E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CA0C5E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CAOtF"}
+{"version":3,"file":"docs-loader.d.ts","sourceRoot":"","sources":["../../src/tools/docs-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAeH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,IAAI,OAAO,EAAE,CA0BxC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAoBlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAY7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CA4C5E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CAOtF"}

package/dist/tools/docs-loader.js

@@ -1,11 +1,51 @@
+/**
+ * @module docs-loader
+ *
+ * Documentation Loading and Search Utilities
+ *
+ * This module provides functionality for loading, searching, and retrieving
+ * Macroforge documentation sections. Documentation is stored as markdown files
+ * with metadata in `docs/sections.json`.
+ *
+ * Key features:
+ * - Loads documentation sections from disk with lazy content loading
+ * - Supports multiple search strategies (exact, partial, fuzzy, category)
+ * - Handles chunked documentation for large sections
+ * - Provides type-safe interfaces for documentation structure
+ *
+ * @example
+ * ```typescript
+ * import { loadSections, getSection, searchSections } from './docs-loader.js';
+ *
+ * const sections = loadSections();
+ * const debug = getSection(sections, 'debug');
+ * const matches = searchSections(sections, 'serialization');
+ * ```
+ */
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+/** Current file path for ESM module resolution */
 const __filename = fileURLToPath(import.meta.url);
+/** Current directory path for ESM module resolution */
 const __dirname = dirname(__filename);
+/** Path to the docs directory containing sections.json and markdown files */
 const docsDir = join(__dirname, '..', '..', 'docs');
 /**
- * Load all documentation sections from the docs directory
+ * Loads all documentation sections from the docs directory.
+ *
+ * This function reads `docs/sections.json` for metadata and loads the markdown
+ * content for each section from disk. Chunked parent sections do not have their
+ * content loaded directly - their content is accessed through child chunks.
+ *
+ * @returns Array of Section objects with content loaded. Returns empty array if
+ *          sections.json is not found (with a warning logged to stderr).
+ *
+ * @example
+ * ```typescript
+ * const sections = loadSections();
+ * console.log(`Loaded ${sections.length} sections`);
+ * ```
  */
 export function loadSections() {
     const sectionsPath = join(docsDir, 'sections.json');
@@ -14,9 +54,9 @@ export function loadSections() {
         return [];
     }
     const sectionsData = JSON.parse(readFileSync(sectionsPath, 'utf-8'));
-    // Load content for each section
+    // Load content for each non-chunked section from its markdown file
     for (const section of sectionsData) {
-        // For chunked parent sections, we don't load content - it will be handled specially
+        // Chunked parent sections don't have direct content - content is in child chunks
         if (section.is_chunked) {
             continue;
         }
@@ -31,35 +71,66 @@ export function loadSections() {
     return sectionsData;
 }
 /**
- * Get a section by ID or title (case-insensitive)
+ * Finds a section by ID or title using progressive matching strategies.
+ *
+ * The function attempts to match in the following order (stopping at first match):
+ * 1. Exact ID match (case-insensitive)
+ * 2. Exact title match (case-insensitive)
+ * 3. Partial ID match (query is substring of ID)
+ * 4. Partial title match (query is substring of title)
+ *
+ * @param sections - Array of sections to search through
+ * @param query - Search query (ID or title to find)
+ * @returns The first matching Section, or undefined if no match found
+ *
+ * @example
+ * ```typescript
+ * const debug = getSection(sections, 'debug');        // Exact ID match
+ * const serde = getSection(sections, 'Serialize');    // Exact title match
+ * const partial = getSection(sections, 'valid');      // Partial match on "validators"
+ * ```
  */
 export function getSection(sections, query) {
     const normalizedQuery = query.toLowerCase().trim();
-    // Try exact ID match first
+    // Priority 1: Exact ID match (most specific)
     let match = sections.find((s) => s.id.toLowerCase() === normalizedQuery);
     if (match)
         return match;
-    // Try exact title match
+    // Priority 2: Exact title match
     match = sections.find((s) => s.title.toLowerCase() === normalizedQuery);
     if (match)
         return match;
-    // Try partial ID match
+    // Priority 3: Partial ID match (query is substring of ID)
     match = sections.find((s) => s.id.toLowerCase().includes(normalizedQuery));
     if (match)
         return match;
-    // Try partial title match
+    // Priority 4: Partial title match (query is substring of title)
     match = sections.find((s) => s.title.toLowerCase().includes(normalizedQuery));
     if (match)
         return match;
     return undefined;
 }
 /**
- * Get multiple sections by IDs or titles
+ * Retrieves multiple sections by their IDs or titles.
+ *
+ * Uses {@link getSection} for each query, deduplicating results if the same
+ * section matches multiple queries.
+ *
+ * @param sections - Array of sections to search through
+ * @param queries - Array of search queries (IDs or titles)
+ * @returns Array of unique matching Sections in the order they were found
+ *
+ * @example
+ * ```typescript
+ * const docs = getSections(sections, ['debug', 'serialize', 'clone']);
+ * // Returns all three sections if found
+ * ```
  */
 export function getSections(sections, queries) {
     const results = [];
     for (const query of queries) {
         const section = getSection(sections, query);
+        // Deduplicate: only add if not already in results
         if (section && !results.includes(section)) {
             results.push(section);
         }
@@ -67,29 +138,57 @@ export function getSections(sections, queries) {
     return results;
 }
 /**
- * Search sections by use_cases or content
+ * Performs a fuzzy search across sections using a weighted scoring algorithm.
+ *
+ * The search splits the query into keywords and scores each section based on
+ * where matches are found. Results are sorted by relevance score (highest first).
+ *
+ * ## Scoring Algorithm
+ *
+ * Each section is scored based on matches in different fields:
+ * - **ID match** (+10): Full query found in section ID
+ * - **Title match** (+10): Full query found in section title
+ * - **Use cases match** (+5 per keyword): Each query keyword found in use_cases
+ * - **Content match** (+1 per keyword): Each query keyword found in content
+ *
+ * The higher weights for ID/title ensure exact matches rank above content matches.
+ * Use cases are weighted moderately as they indicate intended use.
+ *
+ * @param sections - Array of sections to search through
+ * @param query - Search query (can contain multiple space-separated keywords)
+ * @returns Array of matching Sections sorted by relevance score (highest first)
+ *
+ * @example
+ * ```typescript
+ * // Single keyword search
+ * const results = searchSections(sections, 'validation');
+ *
+ * // Multi-keyword search (scores sections matching more keywords higher)
+ * const results = searchSections(sections, 'email url length');
+ * ```
  */
 export function searchSections(sections, query) {
     const normalizedQuery = query.toLowerCase().trim();
     const keywords = normalizedQuery.split(/\s+/);
+    // Score each section based on where query/keywords match
     const scored = sections.map((section) => {
         let score = 0;
-        // Check ID
+        // High priority: ID contains full query (+10)
         if (section.id.toLowerCase().includes(normalizedQuery)) {
             score += 10;
         }
-        // Check title
+        // High priority: Title contains full query (+10)
         if (section.title.toLowerCase().includes(normalizedQuery)) {
             score += 10;
         }
-        // Check use_cases
+        // Medium priority: Each keyword in use_cases (+5 each)
         const useCases = section.use_cases.toLowerCase();
         for (const keyword of keywords) {
             if (useCases.includes(keyword)) {
                 score += 5;
             }
         }
-        // Check content (lower weight)
+        // Low priority: Each keyword in content (+1 each)
         if (section.content) {
             const content = section.content.toLowerCase();
             for (const keyword of keywords) {
@@ -100,13 +199,30 @@ export function searchSections(sections, query) {
         }
         return { section, score };
     });
+    // Return matching sections sorted by score (highest first)
     return scored
         .filter((s) => s.score > 0)
         .sort((a, b) => b.score - a.score)
         .map((s) => s.section);
 }
 /**
- * Get all sections in a category
+ * Filters sections by category slug or category title.
+ *
+ * Matches against both `category` (slug) and `category_title` (display name)
+ * to support flexible lookups.
+ *
+ * @param sections - Array of sections to filter
+ * @param category - Category slug or title to filter by (case-insensitive)
+ * @returns Array of Sections belonging to the specified category
+ *
+ * @example
+ * ```typescript
+ * // Filter by category slug
+ * const macros = getSectionsByCategory(sections, 'macros');
+ *
+ * // Filter by category title
+ * const guides = getSectionsByCategory(sections, 'Getting Started');
+ * ```
  */
 export function getSectionsByCategory(sections, category) {
     const normalizedCategory = category.toLowerCase().trim();

package/dist/tools/docs-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs-loader.js","sourceRoot":"","sources":["../../src/tools/docs-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"docs-loader.js","sourceRoot":"","sources":["../../src/tools/docs-loader.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -1,6 +1,53 @@
+/**
+ * @module tools
+ *
+ * MCP Tool Registry and Request Handlers
+ *
+ * This module registers and implements all MCP tools exposed by the Macroforge server.
+ * It serves as the main business logic layer, handling tool requests from MCP clients.
+ *
+ * ## Registered Tools
+ *
+ * | Tool | Purpose |
+ * |------|---------|
+ * | `list-sections` | List all documentation sections with metadata |
+ * | `get-documentation` | Retrieve full content for specific sections |
+ * | `macroforge-autofixer` | Validate TypeScript code with @derive decorators |
+ * | `expand-code` | Expand macros and show generated code |
+ * | `get-macro-info` | Get documentation for macros and decorators |
+ *
+ * ## Architecture
+ *
+ * The module uses:
+ * - `docs-loader.js` for documentation loading and search
+ * - `@macroforge/core` (optional) for native code validation and expansion
+ *
+ * Native bindings are loaded dynamically and gracefully degrade if unavailable.
+ *
+ * @see {@link registerTools} for the main entry point
+ */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 /**
- * Register all Macroforge MCP tools with the server
+ * Registers all Macroforge MCP tools with the server instance.
+ *
+ * This function:
+ * 1. Loads documentation sections from disk
+ * 2. Registers a `tools/list` handler returning all available tools
+ * 3. Registers a `tools/call` handler routing requests to appropriate handlers
+ *
+ * The tools registered provide documentation access and code analysis capabilities
+ * for AI assistants working with Macroforge.
+ *
+ * @param server - The MCP Server instance to register tools with
+ *
+ * @example
+ * ```typescript
+ * import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+ * import { registerTools } from './tools/index.js';
+ *
+ * const server = new Server({ name: 'macroforge', version: '1.0.0' }, { capabilities: { tools: {} } });
+ * registerTools(server);
+ * ```
  */
 export declare function registerTools(server: Server): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAWnE;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAwKlD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAYnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAwKlD"}