fmea-api-mcp-server 1.0.7 → 1.1.1

package/README.md

@@ -98,10 +98,12 @@ When the package is published to NPM:
 
 ## Features
 - **Resources**: Can read JSON files in the `endpoints` folder.
-- **Tools**:
 - **Tools**:
     - `search_apis`: 
-        - Smart search with relevance scoring and pagination.
+        - **Smart Search**: Supports multi-keyword matching (e.g., "project search"). Results are ranked by relevance (Summary > OperationID > Description > Path).
+        - **Deprecation Warnings**: Automatically detects if a V1 endpoint has a V2 equivalent and includes a warning in the results.
         - Supports filters: `query` (use `*` for all), `method`, `version`, `page` (default 1).
         - Results limited to 10 per page. Returns meta info (total, totalPages) and guidance.
-    - `get_api_details`: Get full details (schema, parameters) for a specific endpoint.
+    - `get_api_details`: 
+        - Get full details (schema, parameters) for a specific endpoint.
+        - Includes **Deprecation Warnings** if a newer version of the API exists.

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,11 +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 === "*" || query === "";
+        let documents = [];
+        // 1. Prepare Documents (Corpus)
         for (const filePath of files) {
             try {
                 const content = await fs.readFile(filePath, "utf-8");
@@ -233,34 +234,21 @@ class ApiDocsServer {
                         if (filterMethod && endpoint.method.toUpperCase() !== filterMethod) {
                             continue;
                         }
-                        // Scoring Logic
-                        let score = 0;
-                        if (isWildcard) {
-                            score = 1; // All match in wildcard mode
-                        }
-                        else {
-                            const summary = (endpoint.summary || "").toLowerCase();
-                            const description = (endpoint.description || "").toLowerCase();
-                            const apiPath = (endpoint.path || "").toLowerCase();
-                            const operationId = (endpoint.operationId || "").toLowerCase();
-                            // Exact/High relevance matches
-                            if (summary.includes(query) || operationId.includes(query))
-                                score += 10;
-                            if (description.includes(query))
-                                score += 5;
-                            if (apiPath.includes(query))
-                                score += 3;
-                        }
-                        if (score > 0) {
-                            allMatches.push({
-                                score,
-                                file: fileName,
-                                method: endpoint.method,
-                                path: endpoint.path,
-                                summary: endpoint.summary,
-                                description: endpoint.description
-                            });
-                        }
+                        // 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
+                        });
                     }
                 }
             }
@@ -268,35 +256,114 @@ 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}'.`
+            };
+        }
+        // 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.`
             };
         }
-        // Sort by score descending (only meaningful if not wildcard)
-        if (!isWildcard) {
-            allMatches.sort((a, b) => b.score - a.score);
+        // 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 currentPage = Math.max(1, page); // Ensure page is at least 1
+        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;
-        const slicedResults = allMatches.slice(start, end).map(({ score, ...rest }) => rest);
+        // Slice
+        const slice = scoredDocs.slice(start, start + LIMIT);
+        // Post-processing: Add warnings for V1 endpoints
+        const finalResults = await Promise.all(slice.map(async (item) => {
+            const { score, tokens, docLength, ...rest } = item; // Remove internal props
+            if (rest.path && rest.path.includes("/v1/")) {
+                const v2Path = rest.path.replace("/v1/", "/v2/");
+                const v2Exists = await this.findEndpointInFiles(files, v2Path, rest.method);
+                if (v2Exists) {
+                    rest.warning = "DEPRECATED: Version v1 is deprecated. Please use v2 endpoint: " + v2Path;
+                }
+            }
+            return rest;
+        }));
         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: slicedResults,
+            results: finalResults,
             meta: {
-                total: totalFound,
+                total: totalHits,
                 page: currentPage,
                 totalPages: totalPages
             },
@@ -316,10 +383,20 @@ class ApiDocsServer {
                             if (method && endpoint.method.toUpperCase() !== method) {
                                 continue;
                             }
-                            return {
+                            const result = {
                                 sourceFile: path.relative(ENDPOINTS_DIR, filePath),
                                 ...endpoint
                             };
+                            // Check for V1 Deprecation
+                            if (apiPath.includes("/v1/")) {
+                                const v2Path = apiPath.replace("/v1/", "/v2/");
+                                const v2Exists = await this.findEndpointInFiles(files, v2Path, method);
+                                if (v2Exists) {
+                                    // Inject a top-level deprecation warning in the details
+                                    result.deprecation_warning = `NOTICE: This v1 endpoint is deprecated. A newer version (v2) exists at ${v2Path}`;
+                                }
+                            }
+                            return result;
                         }
                     }
                 }
@@ -330,6 +407,28 @@ class ApiDocsServer {
         }
         return null;
     }
+    // Efficiently check if an endpoint exists without reading files if content is not needed
+    // Note: Since we don't cache file contents in memory for this simple server,
+    // we re-read files. For a production server with many files, we would cache the map.
+    async findEndpointInFiles(files, apiPath, method) {
+        for (const filePath of files) {
+            try {
+                const content = await fs.readFile(filePath, "utf-8");
+                const json = JSON.parse(content);
+                if (json.endpoints && Array.isArray(json.endpoints)) {
+                    for (const ep of json.endpoints) {
+                        if (ep.path === apiPath) {
+                            if (method && ep.method.toUpperCase() !== method)
+                                continue;
+                            return true;
+                        }
+                    }
+                }
+            }
+            catch (e) { }
+        }
+        return false;
+    }
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);

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.0.7",
+  "version": "1.1.1",
   "description": "MCP server for serving API documentation from endpoints directory",
   "type": "module",
   "main": "dist/index.js",