fmea-api-mcp-server 1.0.7 → 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 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

@@ -214,7 +214,9 @@ class ApiDocsServer {
     async searchInFiles(query, filterMethod, filterVersion, page = 1) {
         const files = await this.getAllFiles(ENDPOINTS_DIR);
         let allMatches = [];
-        const isWildcard = query === "*" || query === "";
+        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");
@@ -236,20 +238,34 @@ class ApiDocsServer {
                         // Scoring Logic
                         let score = 0;
                         if (isWildcard) {
-                            score = 1; // All match in wildcard mode
+                            score = 1;
                         }
                         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;
+                            // 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({
@@ -258,7 +274,8 @@ class ApiDocsServer {
                                 method: endpoint.method,
                                 path: endpoint.path,
                                 summary: endpoint.summary,
-                                description: endpoint.description
+                                description: endpoint.description,
+                                operationId: endpoint.operationId
                             });
                         }
                     }
@@ -282,10 +299,25 @@ class ApiDocsServer {
         // Pagination
         const LIMIT = 10;
         const totalPages = Math.ceil(totalFound / LIMIT);
-        const currentPage = Math.max(1, page); // Ensure page is at least 1
+        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);
+        // 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}.`;
@@ -294,7 +326,7 @@ class ApiDocsServer {
             }
         }
         return {
-            results: slicedResults,
+            results: finalResults,
             meta: {
                 total: totalFound,
                 page: currentPage,
@@ -316,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;
                         }
                     }
                 }
@@ -330,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.7",
+  "version": "1.1.0",
   "description": "MCP server for serving API documentation from endpoints directory",
   "type": "module",
   "main": "dist/index.js",