fmea-api-mcp-server 1.1.1 → 1.1.3

package/dist/index.js

@@ -9,6 +9,54 @@ 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
@@ -120,7 +168,7 @@ class ApiDocsServer {
                                     description: "Page number for pagination (default: 1).",
                                 },
                             },
-                            required: ["query"],
+                            required: [],
                         },
                     },
                     {
@@ -146,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: [
@@ -211,6 +270,38 @@ class ApiDocsServer {
         }
         return results;
     }
+    // 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);
@@ -243,11 +334,13 @@ class ApiDocsServer {
                             (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, // For BM25 calculation
-                            docLength: tokens.length
+                            tokens: expandedTokens, // Expanded tokens for BM25 calculation
+                            docLength: expandedTokens.length
                         });
                     }
                 }
@@ -279,12 +372,15 @@ class ApiDocsServer {
                 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
+        // 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);
-                return synonyms.some((syn) => doc.tokens.includes(syn));
+                // Expand with plural/singular variants
+                const expandedQuery = Array.from(expandTokenVariants(synonyms));
+                return expandedQuery.some((variant) => doc.tokens.includes(variant));
             });
         });
         if (filteredDocs.length === 0) {
@@ -299,13 +395,18 @@ class ApiDocsServer {
         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)
+        // 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 => getSynonyms(t).forEach((s) => allQueryTerms.add(s)));
+        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;
@@ -319,13 +420,12 @@ class ApiDocsServer {
         let scoredDocs = filteredDocs.map(doc => {
             let score = 0;
             for (const qToken of rawQueryTokens) {
-                // Find which synonyms of qToken are present in this doc
+                // Find which synonyms + plural variants 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 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));
@@ -344,17 +444,17 @@ class ApiDocsServer {
         const start = (currentPage - 1) * LIMIT;
         // Slice
         const slice = scoredDocs.slice(start, start + LIMIT);
-        // Post-processing: Add warnings for V1 endpoints
+        // Post-processing: Add warnings for V1 endpoints AND strip heavy fields
         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;
-                }
+            // 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) {
@@ -384,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;
                         }
@@ -429,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

@@ -1,9 +1,11 @@
 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"],
+    "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"],

package/endpoints/README.md

@@ -18,6 +18,16 @@ endpoints/
           └── ...
 ```
 
+### Classification Rules
+
+To prevent ambiguity, follow these classification principles:
+
+- **Domain Specific**: If an endpoint operates *within the context* of a specific resource (e.g., "Export THIS resource's sub-data"), place it under that resource's directory.
+    - Example: `/api/v2/main-resources/{id}/sub-feature` -> `endpoints/v2/main-resources/sub-feature.json`
+
+- **Global / Utility**: If an endpoint is a generic utility or operates independently of other resources (e.g., "Process ANY file"), create a dedicated top-level resource directory.
+    - Example: `/api/v2/standalone-feature` -> `endpoints/v2/standalone-feature/core.json`
+
 ### Rules
 
 1.  **Directory Required**: Every resource (e.g., `projects`, `users`) MUST be a directory, even if it only contains one file.
@@ -27,7 +37,15 @@ endpoints/
     - `category`: String (Resource category name)
     - `version`: String ("v1" or "v2")
     - `description`: String (Resource description)
-    - `endpoints`: Array of endpoint objects.
+    - `endpoints`: Array of endpoint objects. Each object MUST contain:
+        - `path`: String (URI path)
+        - `method`: String (HTTP method)
+        - `summary`: String (Short summary)
+        - `description`: String (Detailed description)
+        - `tags`: Array of Strings
+        - `operationId`: String (Unique identifier)
+        - `parameters`: Array (Optional parameters)
+        - `responses`: Object (Response definitions)
 
 ### Example
 

package/package.json

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