fmea-api-mcp-server 1.0.6 → 1.1.0

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 (Summary > Description > Path).
-        - Supports filters: `query`, `method` (GET/POST), `version` (v1/v2).
-        - Results limited to top 10 by default to prevent context pollution.
-    - `get_api_details`: Get full details (schema, parameters) for a specific endpoint.
+        - **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.
+        - Includes **Deprecation Warnings** if a newer version of the API exists.

package/dist/index.js

@@ -114,6 +114,10 @@ class ApiDocsServer {
                                     type: "string",
                                     description: "Filter by API version (e.g. 'v1', 'v2'). Optional.",
                                 },
+                                page: {
+                                    type: "integer",
+                                    description: "Page number for pagination (default: 1).",
+                                },
                             },
                             required: ["query"],
                         },
@@ -144,7 +148,8 @@ class ApiDocsServer {
                 const 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 results = await this.searchInFiles(query, method, version);
+                const page = request.params.arguments?.page ? Number(request.params.arguments?.page) : 1;
+                const results = await this.searchInFiles(query, method, version, page);
                 return {
                     content: [
                         {
@@ -205,19 +210,21 @@ class ApiDocsServer {
         }
         return results;
     }
-    // Smart search helper with scoring, filtering, and limits
-    async searchInFiles(query, filterMethod, filterVersion) {
+    // Smart search helper with scoring, filtering, limits, and pagination
+    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);
         for (const filePath of files) {
             try {
                 const content = await fs.readFile(filePath, "utf-8");
                 const json = JSON.parse(content);
                 const fileName = path.relative(ENDPOINTS_DIR, filePath);
-                // Version Filtering (File level or content level check)
-                // Check if file path contains version (e.g. "v1/...") or json has version field
+                // Version Filtering
                 if (filterVersion) {
-                    const fileVersion = fileName.split(path.sep)[0]; // e.g. "v1" from "v1/projects/..."
+                    const fileVersion = fileName.split(path.sep)[0];
                     if (fileVersion !== filterVersion && json.version !== filterVersion) {
                         continue;
                     }
@@ -230,17 +237,36 @@ class ApiDocsServer {
                         }
                         // Scoring Logic
                         let score = 0;
-                        const summary = (endpoint.summary || "").toLowerCase();
-                        const description = (endpoint.description || "").toLowerCase();
-                        const apiPath = (endpoint.path || "").toLowerCase();
-                        const operationId = (endpoint.operationId || "").toLowerCase();
-                        // 1. 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 (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,
@@ -248,7 +274,8 @@ class ApiDocsServer {
                                 method: endpoint.method,
                                 path: endpoint.path,
                                 summary: endpoint.summary,
-                                description: endpoint.description
+                                description: endpoint.description,
+                                operationId: endpoint.operationId
                             });
                         }
                     }
@@ -258,19 +285,55 @@ class ApiDocsServer {
                 // Ignore parse errors
             }
         }
-        // Sort by score descending
-        allMatches.sort((a, b) => b.score - a.score);
-        // Limit results
-        const LIMIT = 10;
         const totalFound = allMatches.length;
-        const limitedResults = allMatches.slice(0, LIMIT).map(({ score, ...rest }) => rest); // Remove score from output
-        if (totalFound > LIMIT) {
+        if (totalFound === 0) {
             return {
-                results: limitedResults,
-                warning: `Found ${totalFound} results. Showing top ${LIMIT}. Please refine your search query or use filters.`
+                results: [],
+                message: `No results found for '${query}'. Try using '*' to list all endpoints, or check your version/method filters.`
             };
         }
-        return limitedResults;
+        // Sort by score descending (only meaningful if not wildcard)
+        if (!isWildcard) {
+            allMatches.sort((a, b) => b.score - a.score);
+        }
+        // Pagination
+        const LIMIT = 10;
+        const totalPages = Math.ceil(totalFound / 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
+        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;
+                }
+            }
+            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.`;
+            }
+        }
+        return {
+            results: finalResults,
+            meta: {
+                total: totalFound,
+                page: currentPage,
+                totalPages: totalPages
+            },
+            warning
+        };
     }
     // Helper to get full details of an API
     async getApiDetails(apiPath, method) {
@@ -285,10 +348,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;
                         }
                     }
                 }
@@ -299,6 +372,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/package.json

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