fmea-api-mcp-server 1.1.0 → 1.1.1

package/dist/index.js

@@ -6,6 +6,7 @@ import * as fs from "fs/promises";
 import * as fsSync from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import { getSynonyms } from "./synonyms.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Directory where endpoint definitions are stored.
@@ -210,13 +211,11 @@ class ApiDocsServer {
         }
         return results;
     }
-    // Smart search helper with scoring, filtering, limits, and pagination
+    // Smart search helper with BM25 scoring, Synonyms, and AND logic
     async searchInFiles(query, filterMethod, filterVersion, page = 1) {
         const files = await this.getAllFiles(ENDPOINTS_DIR);
-        let allMatches = [];
-        const isWildcard = query.trim() === "*" || query.trim() === "";
-        // Tokenize query: split by space, filter empty
-        const tokens = query.toLowerCase().split(/\s+/).filter(t => t.length > 0);
+        let documents = [];
+        // 1. Prepare Documents (Corpus)
         for (const filePath of files) {
             try {
                 const content = await fs.readFile(filePath, "utf-8");
@@ -235,49 +234,21 @@ class ApiDocsServer {
                         if (filterMethod && endpoint.method.toUpperCase() !== filterMethod) {
                             continue;
                         }
-                        // Scoring Logic
-                        let score = 0;
-                        if (isWildcard) {
-                            score = 1;
-                        }
-                        else {
-                            const summary = (endpoint.summary || "").toLowerCase();
-                            const description = (endpoint.description || "").toLowerCase();
-                            const apiPath = (endpoint.path || "").toLowerCase();
-                            const operationId = (endpoint.operationId || "").toLowerCase();
-                            // Calculate score for each token
-                            for (const token of tokens) {
-                                let tokenScore = 0;
-                                // Summary: Highest weight (Exact > Partial)
-                                if (summary === token)
-                                    tokenScore += 20;
-                                else if (summary.includes(token))
-                                    tokenScore += 10;
-                                // OperationID: High weight
-                                if (operationId === token)
-                                    tokenScore += 15;
-                                else if (operationId.includes(token))
-                                    tokenScore += 8;
-                                // Description: Medium weight
-                                if (description.includes(token))
-                                    tokenScore += 5;
-                                // Path: Low weight
-                                if (apiPath.includes(token))
-                                    tokenScore += 3;
-                                score += tokenScore;
-                            }
-                        }
-                        if (score > 0) {
-                            allMatches.push({
-                                score,
-                                file: fileName,
-                                method: endpoint.method,
-                                path: endpoint.path,
-                                summary: endpoint.summary,
-                                description: endpoint.description,
-                                operationId: endpoint.operationId
-                            });
-                        }
+                        // Create searchable text blob
+                        // Weighting: Summary (3x), OperationID (2x), Description (1x), Path (1x)
+                        const searchableText = [
+                            (endpoint.summary || "").toLowerCase().repeat(3),
+                            (endpoint.operationId || "").toLowerCase().repeat(2),
+                            (endpoint.description || "").toLowerCase(),
+                            (endpoint.path || "").toLowerCase()
+                        ].join(" ");
+                        const tokens = searchableText.split(/\s+/).filter(t => t.length > 0);
+                        documents.push({
+                            file: fileName,
+                            ...endpoint,
+                            tokens, // For BM25 calculation
+                            docLength: tokens.length
+                        });
                     }
                 }
             }
@@ -285,32 +256,99 @@ class ApiDocsServer {
                 // Ignore parse errors
             }
         }
-        const totalFound = allMatches.length;
+        const totalFound = documents.length;
         if (totalFound === 0) {
             return {
                 results: [],
-                message: `No results found for '${query}'. Try using '*' to list all endpoints, or check your version/method filters.`
+                message: `No results found for '${query}'.`
             };
         }
-        // Sort by score descending (only meaningful if not wildcard)
-        if (!isWildcard) {
-            allMatches.sort((a, b) => b.score - a.score);
+        // 2. Query Processing (Synonyms + AND Logic)
+        const rawQueryTokens = query.toLowerCase().split(/\s+/).filter(t => t.length > 0);
+        // Check for Wildcard
+        if (rawQueryTokens.length === 0 || (rawQueryTokens.length === 1 && rawQueryTokens[0] === "*")) {
+            // Slice for pagination
+            const LIMIT = 10;
+            const totalPages = Math.ceil(totalFound / LIMIT);
+            const currentPage = Math.max(1, page);
+            const start = (currentPage - 1) * LIMIT;
+            const slice = documents.slice(start, start + LIMIT);
+            const finalResults = slice.map(({ tokens, docLength, ...rest }) => rest);
+            return {
+                results: finalResults,
+                meta: { total: totalFound, page: currentPage, totalPages: totalPages }
+            };
         }
+        // Filter Documents: AND Logic with Synonym Expansion
+        // Every query token (or one of its synonyms) MUST be present in the document
+        const filteredDocs = documents.filter(doc => {
+            return rawQueryTokens.every(qToken => {
+                const synonyms = getSynonyms(qToken);
+                return synonyms.some((syn) => doc.tokens.includes(syn));
+            });
+        });
+        if (filteredDocs.length === 0) {
+            return {
+                results: [],
+                message: `No results found for '${query}'. Try fewer keywords or check spelling.`
+            };
+        }
+        // 3. BM25 Calculation on Filtered Docs
+        // Context: We calculate stats based on the *filtered* corpus or *full* corpus?
+        // Standard BM25 usages often use full corpus stats for IDF. We will use full corpus stats.
+        const k1 = 1.2;
+        const b = 0.75;
+        const avgdl = documents.reduce((acc, doc) => acc + doc.docLength, 0) / totalFound;
+        // Calculate IDF (using full corpus) for *expanded* tokens? 
+        // Complexity: simple approach -> Calculate IDF for the specific matching token in the doc for scoring.
+        // If multiple synonyms match, take the max score or sum? Sum is risky (double count). 
+        // We will iterate query tokens, find the *best matching synonym* in the doc, and score that.
+        // Pre-calculate IDF for all potential terms in query (raw + synonyms)
+        const allQueryTerms = new Set();
+        rawQueryTokens.forEach(t => getSynonyms(t).forEach((s) => allQueryTerms.add(s)));
+        const idf = {};
+        for (const term of allQueryTerms) {
+            let n_q = 0;
+            for (const doc of documents) {
+                if (doc.tokens.includes(term))
+                    n_q++;
+            }
+            idf[term] = Math.log((totalFound - n_q + 0.5) / (n_q + 0.5) + 1);
+        }
+        // Score Filtered Documents
+        let scoredDocs = filteredDocs.map(doc => {
+            let score = 0;
+            for (const qToken of rawQueryTokens) {
+                // Find which synonyms of qToken are present in this doc
+                const synonyms = getSynonyms(qToken);
+                const presentSynonyms = synonyms.filter((syn) => doc.tokens.includes(syn));
+                // If multiple synonyms match (e.g. 'find' and 'get' both in doc), we should probably 
+                // just take the best one or sum them with saturation. 
+                // Simplified: Sum them up (assuming they add more relevance).
+                for (const term of presentSynonyms) {
+                    const f_q = doc.tokens.filter((t) => t === term).length;
+                    const numerator = idf[term] * f_q * (k1 + 1);
+                    const denominator = f_q + k1 * (1 - b + b * (doc.docLength / avgdl));
+                    score += numerator / denominator;
+                }
+            }
+            return { ...doc, score };
+        });
+        // Sort by score descending
+        scoredDocs.sort((a, b) => b.score - a.score);
         // Pagination
         const LIMIT = 10;
-        const totalPages = Math.ceil(totalFound / LIMIT);
+        const totalHits = scoredDocs.length;
+        const totalPages = Math.ceil(totalHits / LIMIT);
         const currentPage = Math.max(1, page);
         const start = (currentPage - 1) * LIMIT;
-        const end = start + LIMIT;
-        // Get the page slice
-        const slice = allMatches.slice(start, end);
-        // Post-processing: Add warnings for V1 endpoints if V2 exists
+        // Slice
+        const slice = scoredDocs.slice(start, start + LIMIT);
+        // Post-processing: Add warnings for V1 endpoints
         const finalResults = await Promise.all(slice.map(async (item) => {
-            // Remove score before returning to user
-            const { score, ...rest } = item;
+            const { score, tokens, docLength, ...rest } = item; // Remove internal props
             if (rest.path && rest.path.includes("/v1/")) {
                 const v2Path = rest.path.replace("/v1/", "/v2/");
-                // We check if this v2 path exists using our internal lookup logic
                 const v2Exists = await this.findEndpointInFiles(files, v2Path, rest.method);
                 if (v2Exists) {
                     rest.warning = "DEPRECATED: Version v1 is deprecated. Please use v2 endpoint: " + v2Path;
@@ -320,15 +358,12 @@ class ApiDocsServer {
         }));
         let warning = undefined;
         if (totalPages > 1) {
-            warning = `Found ${totalFound} results. Showing page ${currentPage} of ${totalPages}.`;
-            if (currentPage < totalPages) {
-                warning += ` Use 'page: ${currentPage + 1}' to see next results.`;
-            }
+            warning = `Found ${totalHits} results. Showing page ${currentPage} of ${totalPages}.`;
         }
         return {
             results: finalResults,
             meta: {
-                total: totalFound,
+                total: totalHits,
                 page: currentPage,
                 totalPages: totalPages
             },

package/dist/synonyms.js

@@ -0,0 +1,38 @@
+export const SYNONYM_GROUPS = {
+    // Read / Retrieve
+    "get": ["fetch", "retrieve", "read", "load", "find", "search", "query", "list"],
+    "find": ["get", "search", "retrieve", "lookup"],
+    "search": ["find", "get", "query", "lookup"],
+    "list": ["get", "all", "collection"],
+    // Create
+    "create": ["add", "insert", "make", "new", "post", "generate"],
+    "add": ["create", "insert", "append", "attach"],
+    "post": ["create", "add", "submit"],
+    // Update
+    "update": ["modify", "edit", "change", "save", "put", "patch", "set"],
+    "modify": ["update", "edit", "change", "adjust"],
+    "save": ["update", "store", "persist", "write"],
+    // Delete
+    "delete": ["remove", "destroy", "clear", "erase", "drop"],
+    "remove": ["delete", "detach", "discard"]
+};
+/**
+ * Expands a single token into a list of synonyms including itself.
+ */
+export function getSynonyms(token) {
+    const lowerToken = token.toLowerCase();
+    // Direct lookup
+    if (SYNONYM_GROUPS[lowerToken]) {
+        return [lowerToken, ...SYNONYM_GROUPS[lowerToken]];
+    }
+    // Reverse lookup (inefficient but thorough for a small map)
+    const synonyms = new Set();
+    synonyms.add(lowerToken);
+    for (const [key, details] of Object.entries(SYNONYM_GROUPS)) {
+        if (details.includes(lowerToken)) {
+            synonyms.add(key);
+            details.forEach(d => synonyms.add(d));
+        }
+    }
+    return Array.from(synonyms);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fmea-api-mcp-server",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "MCP server for serving API documentation from endpoints directory",
   "type": "module",
   "main": "dist/index.js",