@equinor/fusion-framework-cli-plugin-ai-mcp 1.0.0

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

@@ -0,0 +1,37 @@
+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.
+ */
+export declare const toolDefinition: {
+    readonly name: "fusion_search_cookbook";
+    readonly description: "Search the Fusion Framework cookbooks using semantic search. Use this for finding example implementations, tutorials, guides, and how-to content.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "The search query to find relevant cookbook examples and tutorials";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of results to return (default: 5)";
+                readonly default: 5;
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+};
+/**
+ * Tool handler for fusion_search_cookbook
+ */
+export declare function handleTool(args: Record<string, unknown>, framework: FrameworkInstance, options: AiOptions & {
+    verbose?: boolean;
+}): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

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

@@ -0,0 +1,37 @@
+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.
+ */
+export declare const toolDefinition: {
+    readonly name: "fusion_search_eds";
+    readonly description: "Search EDS (Equinor Design System) components from Storybook using semantic search. Use this for finding component examples, props, usage patterns, and Storybook stories.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "The search query to find relevant EDS component examples and Storybook stories";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of results to return (default: 5)";
+                readonly default: 5;
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+};
+/**
+ * Tool handler for fusion_search_eds
+ */
+export declare function handleTool(args: Record<string, unknown>, framework: FrameworkInstance, options: AiOptions & {
+    verbose?: boolean;
+}): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

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

@@ -0,0 +1,37 @@
+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.
+ */
+export declare const toolDefinition: {
+    readonly name: "fusion_search_markdown";
+    readonly description: "Search the Fusion Framework markdown documentation using semantic search. Use this for finding documentation, guides, and explanatory content.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "The search query to find relevant markdown documentation";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of results to return (default: 5)";
+                readonly default: 5;
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+};
+/**
+ * Tool handler for fusion_search_markdown
+ */
+export declare function handleTool(args: Record<string, unknown>, framework: FrameworkInstance, options: AiOptions & {
+    verbose?: boolean;
+}): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

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

@@ -0,0 +1,52 @@
+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 */
+export type FusionSearchCategory = 'api' | 'cookbook' | 'markdown' | 'eds' | 'all';
+export declare const inputSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    category: z.ZodDefault<z.ZodOptional<z.ZodEnum<["all"]>>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    limit: number;
+    category: "all";
+}, {
+    query: string;
+    limit?: number | undefined;
+    category?: "all" | undefined;
+}>;
+/**
+ * Tool configuration for McpServer.registerTool().
+ */
+export declare const toolConfig: {
+    readonly description: string;
+    readonly inputSchema: z.ZodObject<{
+        query: z.ZodString;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        category: z.ZodDefault<z.ZodOptional<z.ZodEnum<["all"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        query: string;
+        limit: number;
+        category: "all";
+    }, {
+        query: string;
+        limit?: number | undefined;
+        category?: "all" | undefined;
+    }>;
+};
+/**
+ * Main handler for the `fusion_search` tool.
+ *
+ * Returns a curried function that takes tool input arguments and returns search results.
+ *
+ * @param framework - Active Fusion Framework instance
+ * @param options - AI plugin options, optionally with `{ verbose: true }`
+ * @returns A function that takes validated tool arguments and returns search results
+ *
+ * @throws {Error} If AI module or Azure Search index is not configured
+ */
+export declare function handleTool(framework: FrameworkInstance, options: AiOptions & {
+    verbose?: boolean;
+}): ToolCallback<typeof inputSchema>;

package/dist/types/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "1.0.0";

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@equinor/fusion-framework-cli-plugin-ai-mcp",
+  "version": "1.0.0",
+  "description": "MCP server plugin for Fusion Framework CLI providing Model Context Protocol server capabilities",
+  "main": "dist/esm/index.js",
+  "type": "module",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "dist/types/index.d.ts"
+      ]
+    }
+  },
+  "keywords": [
+    "fusion-framework",
+    "cli",
+    "plugin",
+    "llm",
+    "ai",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/equinor/fusion-framework.git",
+    "directory": "packages/cli-plugins/ai-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "commander": "^14.0.1",
+    "zod": "^3.23.8",
+    "@equinor/fusion-framework-cli-plugin-ai-base": "1.0.0",
+    "@equinor/fusion-framework-module": "5.0.5",
+    "@equinor/fusion-framework-module-ai": "2.0.0"
+  },
+  "peerDependencies": {
+    "@equinor/fusion-framework-cli": "13.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "build:types": "tsc -b",
+    "watch": "tsc -b --watch",
+    "test": "vitest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+import type { Command } from 'commander';
+import { registerAiPlugin as registerAiPluginBase } from '@equinor/fusion-framework-cli-plugin-ai-base';
+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
+ */
+export function registerAiPlugin(program: Command): void {
+  registerAiPluginBase(program, mcpCommand);
+}
+
+export default registerAiPlugin;

package/src/mcp.ts

@@ -0,0 +1,130 @@
+import { createCommand, createOption } from 'commander';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { setupFramework } from '@equinor/fusion-framework-cli-plugin-ai-base';
+import {
+  type AiOptions,
+  withOptions as withAiOptions,
+} from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
+import {
+  handleTool as handleSearchTool,
+  toolConfig as searchToolConfig,
+} from './tools/fusion-search.tool.js';
+
+/**
+ * CLI command: `ai mcp`
+ *
+ * Starts a Model Context Protocol (MCP) server that provides tools and resources
+ * for AI assistants to interact with the Fusion Framework.
+ *
+ * The MCP server exposes:
+ * - Tools for querying and searching the Fusion Framework codebase:
+ *   - fusion_search: Unified search across all documentation types (API, cookbooks, markdown, EDS)
+ * - Resources for accessing framework documentation and context
+ * - Capabilities for AI assistants to understand and work with Fusion Framework
+ *
+ * Usage:
+ *   $ ffc ai mcp [options]
+ *
+ * Options:
+ *   --openai-api-key <key>              API key for Azure OpenAI
+ *   --openai-api-version <version>       API version (default: 2024-02-15-preview)
+ *   --openai-instance <name>             Azure OpenAI instance name
+ *   --openai-chat-deployment <name>      Azure OpenAI chat deployment name
+ *   --openai-embedding-deployment <name> Azure OpenAI embedding deployment name
+ *   --azure-search-endpoint <url>        Azure Search endpoint URL
+ *   --azure-search-api-key <key>        Azure Search API key
+ *   --azure-search-index-name <name>     Azure Search index name
+ *   --verbose                            Enable verbose output
+ *
+ * Environment Variables:
+ *   AZURE_OPENAI_API_KEY                    API key for Azure OpenAI
+ *   AZURE_OPENAI_API_VERSION                API version
+ *   AZURE_OPENAI_INSTANCE_NAME              Instance name
+ *   AZURE_OPENAI_CHAT_DEPLOYMENT_NAME        Chat deployment name
+ *   AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME   Embedding deployment name
+ *   AZURE_SEARCH_ENDPOINT                    Azure Search endpoint
+ *   AZURE_SEARCH_API_KEY                     Azure Search API key
+ *   AZURE_SEARCH_INDEX_NAME                  Azure Search index name
+ *
+ * Examples:
+ *   $ ffc ai mcp
+ *   $ ffc ai mcp --verbose
+ *   $ ffc ai mcp --azure-search-endpoint https://my-search.search.windows.net
+ */
+type CommandOptions = AiOptions & {
+  /** Enable verbose output for debugging */
+  verbose?: boolean;
+};
+
+const _command = createCommand('mcp')
+  .description('Start a Model Context Protocol (MCP) server for Fusion Framework')
+  .addOption(createOption('--verbose', 'Enable verbose output').default(false))
+  .action(async (options: CommandOptions) => {
+    if (options.verbose) {
+      console.error('🚀 Starting MCP server for Fusion Framework...');
+    }
+
+    // Initialize the framework
+    const framework = await setupFramework(options);
+
+    if (options.verbose) {
+      console.error('✅ Framework initialized successfully');
+    }
+
+    // Create MCP server instance
+    const server = new McpServer({
+      name: 'fusion-framework-mcp',
+      version: '1.0.0',
+      title: 'Fusion Framework MCP Server',
+    });
+
+    // Register search tool (will return error if not configured)
+    server.registerTool('fusion_search', searchToolConfig, handleSearchTool(framework, options));
+
+    if (options.verbose) {
+      if (options.azureSearchIndexName && framework.ai) {
+        console.error('✅ Registered tool: fusion_search');
+      } else {
+        console.error(
+          '⚠️  Registered tool: fusion_search (configuration missing - will return error when called)',
+        );
+      }
+    }
+
+    // Start the server using stdio transport (standard for MCP)
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    if (options.verbose) {
+      console.error('✅ MCP server started and ready');
+      console.error('📡 Listening on stdio for MCP protocol messages');
+    }
+
+    // Keep the process alive
+    process.on('SIGINT', async () => {
+      if (options.verbose) {
+        console.error('\n🛑 Shutting down MCP server...');
+      }
+      await server.close();
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', async () => {
+      if (options.verbose) {
+        console.error('\n🛑 Shutting down MCP server...');
+      }
+      await server.close();
+      process.exit(0);
+    });
+  });
+
+// Export the command with AI options
+// Note: Search tools require embedding deployment, so we include it
+export const command = withAiOptions(_command, {
+  includeChat: false,
+  includeEmbedding: true,
+  includeSearch: true,
+});
+
+export default command;

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

@@ -0,0 +1,90 @@
+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.
+ */
+export const toolDefinition = {
+  name: 'fusion_search_api',
+  description:
+    'Search the Fusion Framework API reference using semantic search. Use this for finding TypeScript/TSDoc code documentation, function signatures, class definitions, and API details.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'The search query to find relevant API reference documentation',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of results to return (default: 5)',
+        default: 5,
+      },
+    },
+    required: ['query'],
+  },
+} as const;
+
+/**
+ * Tool handler for fusion_search_api
+ */
+export async function handleTool(
+  args: Record<string, unknown>,
+  framework: FrameworkInstance,
+  options: AiOptions & { verbose?: boolean },
+): Promise<{
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+}> {
+  if (!options.azureSearchIndexName || !framework.ai) {
+    throw new Error(
+      'Vector store is not configured. Azure Search is required for search functionality.',
+    );
+  }
+
+  const query = args?.query as string;
+  const limit = (args?.limit as number) || 5;
+
+  if (!query || typeof query !== 'string') {
+    throw new Error('Query parameter is required and must be a string');
+  }
+
+  if (options.verbose) {
+    console.error(`🔍 Searching API reference for: ${query}`);
+  }
+
+  const vectorStoreService = framework.ai.getService('search', options.azureSearchIndexName);
+  const retriever = vectorStoreService.asRetriever({
+    k: limit,
+    searchType: 'similarity',
+    filter: {
+      filterExpression: "metadata/attributes/any(x: x/key eq 'type' and x/value eq 'tsdoc')",
+    },
+  });
+
+  const docs = await retriever.invoke(query);
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(
+          {
+            query,
+            type: 'api',
+            results: docs.map(
+              (doc: { pageContent: string; metadata: Record<string, unknown> }) => ({
+                content: doc.pageContent,
+                metadata: doc.metadata,
+              }),
+            ),
+            count: docs.length,
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,90 @@
+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.
+ */
+export const toolDefinition = {
+  name: 'fusion_search_cookbook',
+  description:
+    'Search the Fusion Framework cookbooks using semantic search. Use this for finding example implementations, tutorials, guides, and how-to content.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'The search query to find relevant cookbook examples and tutorials',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of results to return (default: 5)',
+        default: 5,
+      },
+    },
+    required: ['query'],
+  },
+} as const;
+
+/**
+ * Tool handler for fusion_search_cookbook
+ */
+export async function handleTool(
+  args: Record<string, unknown>,
+  framework: FrameworkInstance,
+  options: AiOptions & { verbose?: boolean },
+): Promise<{
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+}> {
+  if (!options.azureSearchIndexName || !framework.ai) {
+    throw new Error(
+      'Vector store is not configured. Azure Search is required for search functionality.',
+    );
+  }
+
+  const query = args?.query as string;
+  const limit = (args?.limit as number) || 5;
+
+  if (!query || typeof query !== 'string') {
+    throw new Error('Query parameter is required and must be a string');
+  }
+
+  if (options.verbose) {
+    console.error(`🔍 Searching cookbooks for: ${query}`);
+  }
+
+  const vectorStoreService = framework.ai.getService('search', options.azureSearchIndexName);
+  const retriever = vectorStoreService.asRetriever({
+    k: limit,
+    searchType: 'similarity',
+    filter: {
+      filterExpression: "metadata/attributes/any(x: x/key eq 'type' and x/value eq 'cookbook')",
+    },
+  });
+
+  const docs = await retriever.invoke(query);
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(
+          {
+            query,
+            type: 'cookbook',
+            results: docs.map(
+              (doc: { pageContent: string; metadata: Record<string, unknown> }) => ({
+                content: doc.pageContent,
+                metadata: doc.metadata,
+              }),
+            ),
+            count: docs.length,
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,91 @@
+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.
+ */
+export const toolDefinition = {
+  name: 'fusion_search_eds',
+  description:
+    'Search EDS (Equinor Design System) components from Storybook using semantic search. Use this for finding component examples, props, usage patterns, and Storybook stories.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description:
+          'The search query to find relevant EDS component examples and Storybook stories',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of results to return (default: 5)',
+        default: 5,
+      },
+    },
+    required: ['query'],
+  },
+} as const;
+
+/**
+ * Tool handler for fusion_search_eds
+ */
+export async function handleTool(
+  args: Record<string, unknown>,
+  framework: FrameworkInstance,
+  options: AiOptions & { verbose?: boolean },
+): Promise<{
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+}> {
+  if (!options.azureSearchIndexName || !framework.ai) {
+    throw new Error(
+      'Vector store is not configured. Azure Search is required for search functionality.',
+    );
+  }
+
+  const query = args?.query as string;
+  const limit = (args?.limit as number) || 5;
+
+  if (!query || typeof query !== 'string') {
+    throw new Error('Query parameter is required and must be a string');
+  }
+
+  if (options.verbose) {
+    console.error(`🔍 Searching EDS components/Storybook for: ${query}`);
+  }
+
+  const vectorStoreService = framework.ai.getService('search', options.azureSearchIndexName);
+  const retriever = vectorStoreService.asRetriever({
+    k: limit,
+    searchType: 'similarity',
+    filter: {
+      filterExpression: "metadata/attributes/any(x: x/key eq 'type' and x/value eq 'storybook')",
+    },
+  });
+
+  const docs = await retriever.invoke(query);
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(
+          {
+            query,
+            type: 'eds-component',
+            results: docs.map(
+              (doc: { pageContent: string; metadata: Record<string, unknown> }) => ({
+                content: doc.pageContent,
+                metadata: doc.metadata,
+              }),
+            ),
+            count: docs.length,
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}