@equinor/fusion-framework-cli-plugin-ai-mcp 1.0.5 → 2.0.0

package/dist/types/index.d.ts

@@ -1,7 +1,17 @@
 import type { Command } from 'commander';
 /**
- * Registers the AI MCP server plugin command with the CLI program
- * @param program - The Commander program instance to register commands with
+ * Registers the AI MCP server plugin with the Fusion Framework CLI.
+ *
+ * Adds the `ai mcp` subcommand to the given Commander program so that
+ * running `ffc ai mcp` starts a Model Context Protocol server.
+ *
+ * @param program - Root Commander {@link Command} instance provided by the CLI bootstrap
+ *
+ * @example
+ * ```ts
+ * import { registerAiPlugin } from '@equinor/fusion-framework-cli-plugin-ai-mcp';
+ * registerAiPlugin(program);
+ * ```
  */
 export declare function registerAiPlugin(program: Command): void;
 export default registerAiPlugin;

package/dist/types/mcp.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Fully-configured Commander {@link Command} for `ai mcp`.
+ *
+ * Includes all Azure OpenAI embedding and Azure Search options required by
+ * the search tools. Chat options are excluded because the MCP server does
+ * not perform chat completions.
+ */
 export declare const command: import("commander").Command;
 export default command;

package/dist/types/tools/fusion-search-api.d.ts

@@ -1,8 +1,14 @@
 import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import type { AiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 /**
- * Tool definition for searching Fusion Framework API reference.
- * This tool enables semantic search across TypeScript/TSDoc code documentation, function signatures, and class definitions.
+ * MCP tool definition for `fusion_search_api`.
+ *
+ * Enables semantic search scoped to Fusion Framework TypeScript API
+ * reference — TSDoc blocks, function signatures, class definitions,
+ * and interface declarations indexed as `tsdoc` documents.
+ *
+ * Registered with the MCP server so that AI assistants can discover
+ * and invoke the tool by name.
  */
 export declare const toolDefinition: {
     readonly name: "fusion_search_api";
@@ -24,7 +30,16 @@ export declare const toolDefinition: {
     };
 };
 /**
- * Tool handler for fusion_search_api
+ * Handles invocations of the `fusion_search_api` MCP tool.
+ *
+ * Queries the Azure Cognitive Search vector store with a `tsdoc` category
+ * filter and returns matching documents as JSON text content.
+ *
+ * @param args - Raw tool arguments containing `query` (string) and optional `limit` (number)
+ * @param framework - Active {@link FrameworkInstance} with the AI module loaded
+ * @param options - AI plugin options including Azure Search index name and optional `verbose` flag
+ * @returns MCP-compliant content array with search results, or an error payload
+ * @throws {Error} If the vector store is not configured or `query` is missing
  */
 export declare function handleTool(args: Record<string, unknown>, framework: FrameworkInstance, options: AiOptions & {
     verbose?: boolean;

package/dist/types/tools/fusion-search-cookbook.d.ts

@@ -1,8 +1,11 @@
 import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import type { AiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 /**
- * Tool definition for searching Fusion Framework cookbooks.
- * This tool enables semantic search across example implementations, tutorials, and how-to guides.
+ * MCP tool definition for `fusion_search_cookbook`.
+ *
+ * Enables semantic search scoped to Fusion Framework cookbook content —
+ * example implementations, tutorials, how-to guides, and practical recipes
+ * indexed as `cookbook` documents.
  */
 export declare const toolDefinition: {
     readonly name: "fusion_search_cookbook";
@@ -24,7 +27,16 @@ export declare const toolDefinition: {
     };
 };
 /**
- * Tool handler for fusion_search_cookbook
+ * Handles invocations of the `fusion_search_cookbook` MCP tool.
+ *
+ * Queries the Azure Cognitive Search vector store with a `cookbook` category
+ * filter and returns matching tutorial / recipe documents as JSON text content.
+ *
+ * @param args - Raw tool arguments containing `query` (string) and optional `limit` (number)
+ * @param framework - Active {@link FrameworkInstance} with the AI module loaded
+ * @param options - AI plugin options including Azure Search index name and optional `verbose` flag
+ * @returns MCP-compliant content array with search results, or an error payload
+ * @throws {Error} If the vector store is not configured or `query` is missing
  */
 export declare function handleTool(args: Record<string, unknown>, framework: FrameworkInstance, options: AiOptions & {
     verbose?: boolean;

package/dist/types/tools/fusion-search-eds.d.ts

@@ -1,8 +1,11 @@
 import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import type { AiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 /**
- * Tool definition for searching EDS (Equinor Design System) components from Storybook.
- * This tool enables semantic search across component examples, props, usage patterns, and Storybook stories.
+ * MCP tool definition for `fusion_search_eds`.
+ *
+ * Enables semantic search scoped to EDS (Equinor Design System) Storybook
+ * content — component examples, prop tables, usage patterns, accessibility
+ * notes, and design-token references indexed as `storybook` documents.
  */
 export declare const toolDefinition: {
     readonly name: "fusion_search_eds";
@@ -24,7 +27,16 @@ export declare const toolDefinition: {
     };
 };
 /**
- * Tool handler for fusion_search_eds
+ * Handles invocations of the `fusion_search_eds` MCP tool.
+ *
+ * Queries the Azure Cognitive Search vector store with a `storybook` category
+ * filter and returns matching EDS component documents as JSON text content.
+ *
+ * @param args - Raw tool arguments containing `query` (string) and optional `limit` (number)
+ * @param framework - Active {@link FrameworkInstance} with the AI module loaded
+ * @param options - AI plugin options including Azure Search index name and optional `verbose` flag
+ * @returns MCP-compliant content array with search results, or an error payload
+ * @throws {Error} If the vector store is not configured or `query` is missing
  */
 export declare function handleTool(args: Record<string, unknown>, framework: FrameworkInstance, options: AiOptions & {
     verbose?: boolean;

package/dist/types/tools/fusion-search-markdown.d.ts

@@ -1,8 +1,11 @@
 import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import type { AiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 /**
- * Tool definition for searching Fusion Framework markdown documentation.
- * This tool enables semantic search across markdown files, guides, and documentation.
+ * MCP tool definition for `fusion_search_markdown`.
+ *
+ * Enables semantic search scoped to Fusion Framework markdown
+ * documentation — architecture guides, migration notes, conceptual
+ * overviews, and README content indexed as `markdown` documents.
  */
 export declare const toolDefinition: {
     readonly name: "fusion_search_markdown";
@@ -24,7 +27,16 @@ export declare const toolDefinition: {
     };
 };
 /**
- * Tool handler for fusion_search_markdown
+ * Handles invocations of the `fusion_search_markdown` MCP tool.
+ *
+ * Queries the Azure Cognitive Search vector store with a `markdown` category
+ * filter and returns matching documentation pages as JSON text content.
+ *
+ * @param args - Raw tool arguments containing `query` (string) and optional `limit` (number)
+ * @param framework - Active {@link FrameworkInstance} with the AI module loaded
+ * @param options - AI plugin options including Azure Search index name and optional `verbose` flag
+ * @returns MCP-compliant content array with search results, or an error payload
+ * @throws {Error} If the vector store is not configured or `query` is missing
  */
 export declare function handleTool(args: Record<string, unknown>, framework: FrameworkInstance, options: AiOptions & {
     verbose?: boolean;

package/dist/types/tools/fusion-search.tool.d.ts

@@ -2,8 +2,24 @@ import { z } from 'zod';
 import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import type { AiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 import type { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
-/** Valid documentation categories that can be searched */
+/**
+ * Valid documentation categories that can be used to scope a search.
+ *
+ * - `api` — TypeScript API reference (TSDoc, function signatures, interfaces)
+ * - `cookbook` — Practical code examples, tutorials, and recipes
+ * - `markdown` — Architecture guides, migration docs, and READMEs
+ * - `eds` — EDS Storybook stories, component props, and design tokens
+ * - `all` — Search across every category without filtering
+ */
 export type FusionSearchCategory = 'api' | 'cookbook' | 'markdown' | 'eds' | 'all';
+/**
+ * Zod input schema for the `fusion_search` MCP tool.
+ *
+ * Validates and documents the parameters that AI assistants supply when
+ * invoking the tool: a required `query` string, an optional `limit`
+ * (default 5), and an optional `category` filter (currently locked
+ * to `'all'`).
+ */
 export declare const inputSchema: z.ZodObject<{
     query: z.ZodString;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
@@ -12,7 +28,11 @@ export declare const inputSchema: z.ZodObject<{
     }>>>;
 }, z.core.$strip>;
 /**
- * Tool configuration for McpServer.registerTool().
+ * Configuration object passed to `McpServer.registerTool()` for the
+ * `fusion_search` tool.
+ *
+ * Contains the human-readable description shown to AI assistants and the
+ * Zod {@link inputSchema} used for argument validation.
  */
 export declare const toolConfig: {
     readonly description: string;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "1.0.5";
+export declare const version = "2.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-cli-plugin-ai-mcp",
-  "version": "1.0.5",
+  "version": "2.0.0",
   "description": "MCP server plugin for Fusion Framework CLI providing Model Context Protocol server capabilities",
   "main": "dist/esm/index.js",
   "type": "module",
@@ -40,17 +40,19 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
     "commander": "^14.0.1",
-    "zod": "^4.3.5",
-    "@equinor/fusion-framework-module-ai": "2.0.2",
-    "@equinor/fusion-framework-cli-plugin-ai-base": "1.0.5",
-    "@equinor/fusion-framework-module": "5.0.6"
+    "hono": "^4.12.8",
+    "zod": "^4.3.6",
+    "@equinor/fusion-framework-cli-plugin-ai-base": "2.0.0",
+    "@equinor/fusion-framework-module": "6.0.0",
+    "@equinor/fusion-framework-module-ai": "3.0.0"
   },
   "peerDependencies": {
-    "@equinor/fusion-framework-cli": "^13.3.16"
+    "@equinor/fusion-framework-cli": "^14.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@equinor/fusion-framework-cli": "^14.0.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/index.ts

@@ -3,8 +3,18 @@ import { registerAiPlugin as registerAiPluginBase } from '@equinor/fusion-framew
 import { command as mcpCommand } from './mcp.js';
 
 /**
- * Registers the AI MCP server plugin command with the CLI program
- * @param program - The Commander program instance to register commands with
+ * Registers the AI MCP server plugin with the Fusion Framework CLI.
+ *
+ * Adds the `ai mcp` subcommand to the given Commander program so that
+ * running `ffc ai mcp` starts a Model Context Protocol server.
+ *
+ * @param program - Root Commander {@link Command} instance provided by the CLI bootstrap
+ *
+ * @example
+ * ```ts
+ * import { registerAiPlugin } from '@equinor/fusion-framework-cli-plugin-ai-mcp';
+ * registerAiPlugin(program);
+ * ```
  */
 export function registerAiPlugin(program: Command): void {
   registerAiPluginBase(program, mcpCommand);

package/src/mcp.ts

@@ -52,8 +52,14 @@ import {
  *   $ ffc ai mcp --verbose
  *   $ ffc ai mcp --azure-search-endpoint https://my-search.search.windows.net
  */
+/**
+ * Combined option set for the `ai mcp` command.
+ *
+ * Merges the base AI options (Azure OpenAI + Azure Search credentials)
+ * with MCP-specific flags such as `verbose`.
+ */
 type CommandOptions = AiOptions & {
-  /** Enable verbose output for debugging */
+  /** When `true`, diagnostic messages are written to stderr during startup and shutdown. */
   verbose?: boolean;
 };
 
@@ -119,8 +125,13 @@ const _command = createCommand('mcp')
     });
   });
 
-// Export the command with AI options
-// Note: Search tools require embedding deployment, so we include it
+/**
+ * Fully-configured Commander {@link Command} for `ai mcp`.
+ *
+ * Includes all Azure OpenAI embedding and Azure Search options required by
+ * the search tools. Chat options are excluded because the MCP server does
+ * not perform chat completions.
+ */
 export const command = withAiOptions(_command, {
   includeChat: false,
   includeEmbedding: true,

package/src/tools/fusion-search-api.ts

@@ -2,8 +2,14 @@ import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-
 import type { AiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 
 /**
- * Tool definition for searching Fusion Framework API reference.
- * This tool enables semantic search across TypeScript/TSDoc code documentation, function signatures, and class definitions.
+ * MCP tool definition for `fusion_search_api`.
+ *
+ * Enables semantic search scoped to Fusion Framework TypeScript API
+ * reference — TSDoc blocks, function signatures, class definitions,
+ * and interface declarations indexed as `tsdoc` documents.
+ *
+ * Registered with the MCP server so that AI assistants can discover
+ * and invoke the tool by name.
  */
 export const toolDefinition = {
   name: 'fusion_search_api',
@@ -27,7 +33,16 @@ export const toolDefinition = {
 } as const;
 
 /**
- * Tool handler for fusion_search_api
+ * Handles invocations of the `fusion_search_api` MCP tool.
+ *
+ * Queries the Azure Cognitive Search vector store with a `tsdoc` category
+ * filter and returns matching documents as JSON text content.
+ *
+ * @param args - Raw tool arguments containing `query` (string) and optional `limit` (number)
+ * @param framework - Active {@link FrameworkInstance} with the AI module loaded
+ * @param options - AI plugin options including Azure Search index name and optional `verbose` flag
+ * @returns MCP-compliant content array with search results, or an error payload
+ * @throws {Error} If the vector store is not configured or `query` is missing
  */
 export async function handleTool(
   args: Record<string, unknown>,

package/src/tools/fusion-search-cookbook.ts

@@ -2,8 +2,11 @@ import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-
 import type { AiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 
 /**
- * Tool definition for searching Fusion Framework cookbooks.
- * This tool enables semantic search across example implementations, tutorials, and how-to guides.
+ * MCP tool definition for `fusion_search_cookbook`.
+ *
+ * Enables semantic search scoped to Fusion Framework cookbook content —
+ * example implementations, tutorials, how-to guides, and practical recipes
+ * indexed as `cookbook` documents.
  */
 export const toolDefinition = {
   name: 'fusion_search_cookbook',
@@ -27,7 +30,16 @@ export const toolDefinition = {
 } as const;
 
 /**
- * Tool handler for fusion_search_cookbook
+ * Handles invocations of the `fusion_search_cookbook` MCP tool.
+ *
+ * Queries the Azure Cognitive Search vector store with a `cookbook` category
+ * filter and returns matching tutorial / recipe documents as JSON text content.
+ *
+ * @param args - Raw tool arguments containing `query` (string) and optional `limit` (number)
+ * @param framework - Active {@link FrameworkInstance} with the AI module loaded
+ * @param options - AI plugin options including Azure Search index name and optional `verbose` flag
+ * @returns MCP-compliant content array with search results, or an error payload
+ * @throws {Error} If the vector store is not configured or `query` is missing
  */
 export async function handleTool(
   args: Record<string, unknown>,

package/src/tools/fusion-search-eds.ts

@@ -2,8 +2,11 @@ import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-
 import type { AiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 
 /**
- * Tool definition for searching EDS (Equinor Design System) components from Storybook.
- * This tool enables semantic search across component examples, props, usage patterns, and Storybook stories.
+ * MCP tool definition for `fusion_search_eds`.
+ *
+ * Enables semantic search scoped to EDS (Equinor Design System) Storybook
+ * content — component examples, prop tables, usage patterns, accessibility
+ * notes, and design-token references indexed as `storybook` documents.
  */
 export const toolDefinition = {
   name: 'fusion_search_eds',
@@ -28,7 +31,16 @@ export const toolDefinition = {
 } as const;
 
 /**
- * Tool handler for fusion_search_eds
+ * Handles invocations of the `fusion_search_eds` MCP tool.
+ *
+ * Queries the Azure Cognitive Search vector store with a `storybook` category
+ * filter and returns matching EDS component documents as JSON text content.
+ *
+ * @param args - Raw tool arguments containing `query` (string) and optional `limit` (number)
+ * @param framework - Active {@link FrameworkInstance} with the AI module loaded
+ * @param options - AI plugin options including Azure Search index name and optional `verbose` flag
+ * @returns MCP-compliant content array with search results, or an error payload
+ * @throws {Error} If the vector store is not configured or `query` is missing
  */
 export async function handleTool(
   args: Record<string, unknown>,

package/src/tools/fusion-search-markdown.ts

@@ -2,8 +2,11 @@ import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-
 import type { AiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 
 /**
- * Tool definition for searching Fusion Framework markdown documentation.
- * This tool enables semantic search across markdown files, guides, and documentation.
+ * MCP tool definition for `fusion_search_markdown`.
+ *
+ * Enables semantic search scoped to Fusion Framework markdown
+ * documentation — architecture guides, migration notes, conceptual
+ * overviews, and README content indexed as `markdown` documents.
  */
 export const toolDefinition = {
   name: 'fusion_search_markdown',
@@ -27,7 +30,16 @@ export const toolDefinition = {
 } as const;
 
 /**
- * Tool handler for fusion_search_markdown
+ * Handles invocations of the `fusion_search_markdown` MCP tool.
+ *
+ * Queries the Azure Cognitive Search vector store with a `markdown` category
+ * filter and returns matching documentation pages as JSON text content.
+ *
+ * @param args - Raw tool arguments containing `query` (string) and optional `limit` (number)
+ * @param framework - Active {@link FrameworkInstance} with the AI module loaded
+ * @param options - AI plugin options including Azure Search index name and optional `verbose` flag
+ * @returns MCP-compliant content array with search results, or an error payload
+ * @throws {Error} If the vector store is not configured or `query` is missing
  */
 export async function handleTool(
   args: Record<string, unknown>,

package/src/tools/fusion-search.tool.ts

@@ -5,9 +5,25 @@ import type { VectorStoreDocument } from '@equinor/fusion-framework-module-ai/li
 import type { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 
-/** Valid documentation categories that can be searched */
+/**
+ * Valid documentation categories that can be used to scope a search.
+ *
+ * - `api` — TypeScript API reference (TSDoc, function signatures, interfaces)
+ * - `cookbook` — Practical code examples, tutorials, and recipes
+ * - `markdown` — Architecture guides, migration docs, and READMEs
+ * - `eds` — EDS Storybook stories, component props, and design tokens
+ * - `all` — Search across every category without filtering
+ */
 export type FusionSearchCategory = 'api' | 'cookbook' | 'markdown' | 'eds' | 'all';
 
+/**
+ * Zod input schema for the `fusion_search` MCP tool.
+ *
+ * Validates and documents the parameters that AI assistants supply when
+ * invoking the tool: a required `query` string, an optional `limit`
+ * (default 5), and an optional `category` filter (currently locked
+ * to `'all'`).
+ */
 export const inputSchema = z.object({
   query: z
     .string()
@@ -39,7 +55,11 @@ export const inputSchema = z.object({
 });
 
 /**
- * Tool configuration for McpServer.registerTool().
+ * Configuration object passed to `McpServer.registerTool()` for the
+ * `fusion_search` tool.
+ *
+ * Contains the human-readable description shown to AI assistants and the
+ * Zod {@link inputSchema} used for argument validation.
  */
 export const toolConfig = {
   description: [
@@ -51,7 +71,12 @@ export const toolConfig = {
 } as const;
 
 /**
- * Azure Cognitive Search OData filter expressions per category
+ * Azure Cognitive Search OData filter expressions keyed by
+ * {@link FusionSearchCategory}.
+ *
+ * Each expression restricts the vector search to documents whose
+ * `metadata/attributes` collection contains a matching `type` value.
+ * The `all` category maps to `undefined` (no filter applied).
  */
 const FILTER_EXPRESSIONS: Readonly<Record<FusionSearchCategory, string | undefined>> = {
   api: "metadata/attributes/any(x: x/key eq 'type' and x/value eq 'tsdoc')",

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '1.0.5';
+export const version = '2.0.0';