fmea-api-mcp-server 1.0.5 → 1.0.7

package/README.md

@@ -99,5 +99,9 @@ When the package is published to NPM:
 ## Features
 - **Resources**: Can read JSON files in the `endpoints` folder.
 - **Tools**:
-    - `search_apis`: Search APIs by keyword (returns summaries).
+- **Tools**:
+    - `search_apis`: 
+        - Smart search with relevance scoring and pagination.
+        - 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.

package/dist/index.js

@@ -104,7 +104,19 @@ class ApiDocsServer {
                             properties: {
                                 query: {
                                     type: "string",
-                                    description: "Search query (e.g. 'user login', 'POST /api/v1')",
+                                    description: "Search query (e.g. 'user login', 'create project').",
+                                },
+                                method: {
+                                    type: "string",
+                                    description: "Filter by HTTP method (e.g. 'GET', 'POST'). Optional.",
+                                },
+                                version: {
+                                    type: "string",
+                                    description: "Filter by API version (e.g. 'v1', 'v2'). Optional.",
+                                },
+                                page: {
+                                    type: "integer",
+                                    description: "Page number for pagination (default: 1).",
                                 },
                             },
                             required: ["query"],
@@ -134,7 +146,10 @@ class ApiDocsServer {
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (request.params.name === "search_apis") {
                 const query = String(request.params.arguments?.query).toLowerCase();
-                const results = await this.searchInFiles(query);
+                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;
+                const results = await this.searchInFiles(query, method, version, page);
                 return {
                     content: [
                         {
@@ -195,20 +210,50 @@ class ApiDocsServer {
         }
         return results;
     }
-    // Simple search helper - returns summaries
-    async searchInFiles(query) {
+    // Smart search helper with scoring, filtering, limits, and pagination
+    async searchInFiles(query, filterMethod, filterVersion, page = 1) {
         const files = await this.getAllFiles(ENDPOINTS_DIR);
-        const matches = [];
+        let allMatches = [];
+        const isWildcard = query === "*" || query === "";
         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
+                if (filterVersion) {
+                    const fileVersion = fileName.split(path.sep)[0];
+                    if (fileVersion !== filterVersion && json.version !== filterVersion) {
+                        continue;
+                    }
+                }
                 if (json.endpoints && Array.isArray(json.endpoints)) {
                     for (const endpoint of json.endpoints) {
-                        const str = JSON.stringify(endpoint).toLowerCase();
-                        if (str.includes(query)) {
-                            matches.push({
+                        // Method Filtering
+                        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,
@@ -223,7 +268,40 @@ class ApiDocsServer {
                 // Ignore parse errors
             }
         }
-        return matches;
+        const totalFound = allMatches.length;
+        if (totalFound === 0) {
+            return {
+                results: [],
+                message: `No results found for '${query}'. Try using '*' to list all endpoints, or check your version/method filters.`
+            };
+        }
+        // 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); // Ensure page is at least 1
+        const start = (currentPage - 1) * LIMIT;
+        const end = start + LIMIT;
+        const slicedResults = allMatches.slice(start, end).map(({ score, ...rest }) => 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: slicedResults,
+            meta: {
+                total: totalFound,
+                page: currentPage,
+                totalPages: totalPages
+            },
+            warning
+        };
     }
     // Helper to get full details of an API
     async getApiDetails(apiPath, method) {

package/package.json

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