fmea-api-mcp-server 1.1.0 → 1.1.2

package/dist/index.js

@@ -6,8 +6,57 @@ 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);
+/**
+ * Normalize token to singular form for better matching.
+ * Handles common English plural patterns.
+ */
+function normalizeToken(token) {
+    const normalized = [token];
+    // Simple pluralization rules (token -> singular or singular -> plural)
+    const rules = [
+        // Remove 's' for common plurals
+        [/([a-z]+)s$/, '$1'],
+        // Remove 'es' for words ending with s, x, z, ch, sh
+        [/([a-z]+)es$/, '$1'],
+        // Remove 'ies' and replace with 'y'
+        [/([a-z]+)ies$/, '$1y'],
+        // Remove 'ves' and replace with 'f' (leaf -> leaves)
+        [/([a-z]+)ves$/, '$1f'],
+        // Remove 'men' and replace with 'man' (woman -> women)
+        [/([a-z]+)men$/, '$1man'],
+    ];
+    // Generate singular variants
+    for (const [pattern, replacement] of rules) {
+        if (pattern.test(token)) {
+            const singular = token.replace(pattern, replacement);
+            if (singular !== token && singular.length > 2) {
+                normalized.push(singular);
+            }
+            break;
+        }
+    }
+    // Add plural variant (append 's' if not ending with 's')
+    if (!token.endsWith('s') && token.length > 2) {
+        normalized.push(token + 's');
+    }
+    return normalized;
+}
+/**
+ * Expand tokens to include singular/plural variants
+ */
+function expandTokenVariants(tokens) {
+    const variants = new Set(tokens);
+    for (const token of tokens) {
+        const normalized = normalizeToken(token);
+        for (const variant of normalized) {
+            variants.add(variant);
+        }
+    }
+    return variants;
+}
 // Directory where endpoint definitions are stored.
 // Priority:
 // 1. Environment variable ENDPOINTS_DIR
@@ -119,7 +168,7 @@ class ApiDocsServer {
                                     description: "Page number for pagination (default: 1).",
                                 },
                             },
-                            required: ["query"],
+                            required: [],
                         },
                     },
                     {
@@ -145,10 +194,21 @@ class ApiDocsServer {
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (request.params.name === "search_apis") {
-                const query = String(request.params.arguments?.query).toLowerCase();
+                const query = request.params.arguments?.query ? String(request.params.arguments?.query).toLowerCase() : "";
                 const method = request.params.arguments?.method ? String(request.params.arguments?.method).toUpperCase() : undefined;
                 const version = request.params.arguments?.version ? String(request.params.arguments?.version).toLowerCase() : undefined;
                 const page = request.params.arguments?.page ? Number(request.params.arguments?.page) : 1;
+                if (!query) {
+                    const categories = await this.listApiCategories();
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(categories, null, 2),
+                            },
+                        ],
+                    };
+                }
                 const results = await this.searchInFiles(query, method, version, page);
                 return {
                     content: [
@@ -210,13 +270,43 @@ class ApiDocsServer {
         }
         return results;
     }
-    // Smart search helper with scoring, filtering, limits, and pagination
+    // Helper to list API categories (directories) for exploration
+    async listApiCategories() {
+        const categories = [];
+        try {
+            const topLevel = await fs.readdir(ENDPOINTS_DIR);
+            for (const versionDir of topLevel) {
+                const versionPath = path.join(ENDPOINTS_DIR, versionDir);
+                const stat = await fs.stat(versionPath);
+                if (stat.isDirectory() && !versionDir.startsWith('.')) {
+                    // Look one level deeper for domains (e.g. v1/projects)
+                    const domains = await fs.readdir(versionPath);
+                    for (const domain of domains) {
+                        const domainPath = path.join(versionPath, domain);
+                        const domainStat = await fs.stat(domainPath);
+                        if (domainStat.isDirectory()) {
+                            categories.push({
+                                category: `${versionDir}/${domain}`,
+                                description: `API endpoints for ${domain} (${versionDir})`
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        catch (e) {
+            console.error("Error listing categories:", e);
+        }
+        return {
+            categories: categories,
+            message: "Use 'search_apis' with a query to find specific endpoints, or 'get_api_details' to see full schemas."
+        };
+    }
+    // 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 +325,23 @@ 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);
+                        // Expand document tokens with singular/plural variants
+                        const expandedTokens = Array.from(expandTokenVariants(tokens));
+                        documents.push({
+                            file: fileName,
+                            ...endpoint,
+                            tokens: expandedTokens, // Expanded tokens for BM25 calculation
+                            docLength: expandedTokens.length
+                        });
                     }
                 }
             }
@@ -285,50 +349,121 @@ 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 + Plural/Singular Normalization
+        // Every query token (or one of its synonyms/plurals) MUST be present in the document
+        const filteredDocs = documents.filter(doc => {
+            return rawQueryTokens.every(qToken => {
+                // Get synonyms first
+                const synonyms = getSynonyms(qToken);
+                // Expand with plural/singular variants
+                const expandedQuery = Array.from(expandTokenVariants(synonyms));
+                return expandedQuery.some((variant) => doc.tokens.includes(variant));
+            });
+        });
+        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 (synonyms + plurals)
+        // We expand query terms with both synonyms and plural/singular variants
+        const allQueryTerms = new Set();
+        rawQueryTokens.forEach(t => {
+            const synonyms = getSynonyms(t);
+            synonyms.forEach((s) => {
+                allQueryTerms.add(s);
+                // Also add plural/singular variants
+                const variants = normalizeToken(s);
+                variants.forEach(v => allQueryTerms.add(v));
+            });
+        });
+        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 + plural variants of qToken are present in this doc
+                const synonyms = getSynonyms(qToken);
+                const expandedQuery = Array.from(expandTokenVariants(synonyms));
+                const presentTerms = expandedQuery.filter((term) => doc.tokens.includes(term));
+                // Sum up scores for all matching terms (synonyms + plurals)
+                for (const term of presentTerms) {
+                    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 AND strip heavy fields
         const finalResults = await Promise.all(slice.map(async (item) => {
-            // Remove score before returning to user
-            const { score, ...rest } = item;
-            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;
-                }
+            // Deconstruct to remove heavy fields (parameters, requestBody, responses, tags) and internal scoring props
+            const { score, tokens, docLength, parameters, requestBody, responses, tags, file, ...lightweightItem } = item;
+            if (lightweightItem.path && lightweightItem.path.includes("/v1/")) {
+                // Check for V1 Deprecation
+                // Always generate a warning for v1 endpoints using the 3-step logic
+                // We do this check after determining it is a v1 endpoint
+                lightweightItem.warning = await this.generateDeprecationWarning(lightweightItem.path, lightweightItem.method);
             }
-            return rest;
+            return lightweightItem;
         }));
         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
             },
@@ -349,17 +484,15 @@ class ApiDocsServer {
                                 continue;
                             }
                             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}`;
-                                }
+                                // Check for V1 Deprecation
+                                // Always generate a warning for v1 endpoints using the 3-step logic
+                                // We do this check regardless of whether a direct v2 exists or not, 
+                                // because generateDeprecationWarning handles all cases.
+                                result.warning = await this.generateDeprecationWarning(apiPath, method);
                             }
                             return result;
                         }
@@ -394,6 +527,43 @@ class ApiDocsServer {
         }
         return false;
     }
+    // 3-Step Intelligent Warning Logic
+    async generateDeprecationWarning(v1Path, method) {
+        const files = await this.getAllFiles(ENDPOINTS_DIR);
+        // Step 1: Direct Match (v1 -> v2)
+        const v2Path = v1Path.replace("/v1/", "/v2/");
+        const v2Exists = await this.findEndpointInFiles(files, v2Path, method);
+        if (v2Exists) {
+            return `DEPRECATED: Version v1 is deprecated. Please use v2 endpoint: ${v2Path}`;
+        }
+        // Step 2: Domain Hint (e.g. /api/v1/auth/login -> Check /api/v2/auth/)
+        // Extract domain: /api/v1/projects/... -> projects, /api/v1/auth/... -> auth
+        const match = v1Path.match(/\/api\/v1\/([^/]+)/);
+        if (match && match[1]) {
+            const domain = match[1];
+            const v2DomainPathStart = `/api/v2/${domain}`;
+            // Check if any v2 endpoint exists in this domain
+            let domainExists = false;
+            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)) {
+                        if (json.endpoints.some((ep) => ep.path && ep.path.startsWith(v2DomainPathStart))) {
+                            domainExists = true;
+                            break;
+                        }
+                    }
+                }
+                catch (e) { }
+            }
+            if (domainExists) {
+                return `LEGACY: Direct v2 replacement not found, but newer '${domain}' related features exist in v2. Please search for '${domain}' in v2.`;
+            }
+        }
+        // Step 3: General Legacy Warning
+        return "LEGACY: This v1 endpoint is deprecated and may be removed in the future.";
+    }
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);

package/dist/synonyms.js

@@ -0,0 +1,40 @@
+export const SYNONYM_GROUPS = {
+    // Read / Retrieve
+    "get": ["fetch", "retrieve", "read", "load", "find", "search", "query", "list", "show"],
+    "find": ["get", "search", "retrieve", "lookup", "show"],
+    "search": ["find", "get", "query", "lookup", "show"],
+    "show": ["get", "display", "view", "fetch", "find"],
+    "list": ["get", "all", "collection", "show", "summary"],
+    "summary": ["list", "all", "overview", "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.2",
   "description": "MCP server for serving API documentation from endpoints directory",
   "type": "module",
   "main": "dist/index.js",