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

package/dist/esm/tools/fusion-search.tool.js

@@ -0,0 +1,152 @@
+import { z } from 'zod';
+export const inputSchema = z.object({
+    query: z
+        .string()
+        .describe('Ask anything about Fusion Framework in plain English — the more specific, the better the results.'),
+    limit: z
+        .number()
+        .optional()
+        .default(5)
+        .describe('Maximum number of results to return. Recommended range: 3–8 (default: 5). Lower values help prevent context window overflow.'),
+    category: z
+        // .enum(['api', 'cookbook', 'markdown', 'eds', 'all'])
+        .enum(['all'])
+        .optional()
+        .default('all'),
+    // .describe(
+    //   [
+    //     'Optional filter to narrow search scope:',
+    //     '• api      → TypeScript API reference (classes, methods, interfaces)',
+    //     '• cookbook → Code examples, tutorials, and practical recipes',
+    //     '• markdown → Guides, architecture docs, migration guides',
+    //     '• eds      → EDS components (Storybook stories, props, tokens, accessibility)',
+    //     '• all      → Search all sources (default)',
+    //   ].join('\n'),
+    // ),
+});
+/**
+ * Tool configuration for McpServer.registerTool().
+ */
+export const toolConfig = {
+    description: [
+        'THE BEST AND FASTEST WAY to get accurate answers about Fusion Framework, modules, configurators, EDS components, and best practices.',
+        'Understands natural questions and returns the exact code examples, API docs, cookbooks, or EDS stories you need — always with direct GitHub links.',
+        'Covers everything: TypeScript APIs, practical cookbooks, architecture guides, and full EDS component documentation.',
+    ].join('\n'),
+    inputSchema,
+};
+/**
+ * Azure Cognitive Search OData filter expressions per category
+ */
+const FILTER_EXPRESSIONS = {
+    api: "metadata/attributes/any(x: x/key eq 'type' and x/value eq 'tsdoc')",
+    cookbook: "metadata/attributes/any(x: x/key eq 'type' and x/value eq 'cookbook')",
+    markdown: "metadata/attributes/any(x: x/key eq 'type' and x/value eq 'markdown')",
+    eds: "metadata/attributes/any(x: x/key eq 'type' and x/value eq 'storybook')",
+    all: undefined,
+};
+/**
+ * Performs a semantic search with Maximal Marginal Relevance (MMR) in a specific category.
+ *
+ * MMR balances relevance and diversity — perfect for avoiding near-duplicate results
+ * when multiple docs describe the same concept.
+ *
+ * @param category - Documentation category to search within
+ * @param query - Natural language search query
+ * @param limit - Maximum number of results (final count after MMR)
+ * @param framework - Fusion Framework instance with AI module loaded
+ * @param options - AI plugin options (must include Azure Search index name)
+ * @returns Array of relevant documents with metadata
+ */
+async function searchWithMMR(category, query, limit, framework, options) {
+    const filterExpression = FILTER_EXPRESSIONS[category];
+    if (!framework.ai || !options.azureSearchIndexName) {
+        throw new Error('Fusion AI module or Azure Search index not configured. ' +
+            'Ensure `@equinor/fusion-framework-cli-plugin-ai` is installed and configured.');
+    }
+    const vectorStoreService = framework.ai.getService('search', options.azureSearchIndexName);
+    const retriever = vectorStoreService.asRetriever({
+        k: limit,
+        searchType: 'mmr',
+        searchKwargs: {
+            fetchK: Math.max(60, limit * 6), // Fetch more candidates for better diversity
+            lambda: 0.5, // Balance between relevance (1.0) and diversity (0.0)
+        },
+        filter: filterExpression ? { filterExpression } : undefined,
+    });
+    const docs = await retriever.invoke(query);
+    return Array.isArray(docs) ? docs : [];
+}
+/**
+ * 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 function handleTool(framework, options) {
+    return async (args) => {
+        // ── Preconditions ─────────────────────────────────────────────────────
+        if (!framework.ai || !options.azureSearchIndexName) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: 'Fusion AI module or Azure Search index not configured',
+                            message: 'Ensure `@equinor/fusion-framework-cli-plugin-ai` is installed and configured with Azure Search credentials.',
+                            required: {
+                                azureSearchIndexName: 'Azure Search index name',
+                                azureSearchEndpoint: 'Azure Search endpoint URL',
+                                azureSearchApiKey: 'Azure Search API key',
+                                openaiEmbeddingDeployment: 'Azure OpenAI embedding deployment name',
+                            },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const query = args.query.trim();
+        const limit = args.limit && args.limit > 0 ? Math.floor(args.limit) : 10;
+        const category = args.category && args.category in FILTER_EXPRESSIONS ? args.category : 'all';
+        if (!query || query === '') {
+            throw new Error('Parameter "query" is required and must be a non-empty string.');
+        }
+        // ── Verbose logging (useful when running in Cursor, VS Code, etc.) ───
+        if (options.verbose) {
+            console.error(`Fusion Search → "${query}" | Category: ${category} | Limit: ${limit}`);
+        }
+        // ── Execute search ───────────────────────────────────────────────────
+        try {
+            const results = await searchWithMMR(category, query, limit, framework, options);
+            return {
+                content: results.map((doc) => ({
+                    type: 'text',
+                    text: doc.pageContent,
+                    _meta: doc.metadata,
+                })),
+                isError: false,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                            results: [],
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=fusion-search.tool.js.map

package/dist/esm/tools/fusion-search.tool.js.map

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

package/dist/esm/version.js

@@ -0,0 +1,3 @@
+// Generated by genversion.
+export const version = '1.0.0';
+//# sourceMappingURL=version.js.map

package/dist/esm/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}