fmea-api-mcp-server 1.0.4 → 1.0.6

package/README.md

@@ -98,4 +98,10 @@ When the package is published to NPM:
 
 ## Features
 - **Resources**: Can read JSON files in the `endpoints` folder.
-- **Tools**: Use the `search_apis` tool to search APIs by keyword.
+- **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.

package/dist/index.js

@@ -98,25 +98,53 @@ class ApiDocsServer {
                 tools: [
                     {
                         name: "search_apis",
-                        description: "Search for API endpoints by keyword across all documentation files",
+                        description: "Search for API endpoints by keyword across all documentation files. Returns summarized results.",
                         inputSchema: {
                             type: "object",
                             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.",
                                 },
                             },
                             required: ["query"],
                         },
                     },
+                    {
+                        name: "get_api_details",
+                        description: "Get full details including schema and parameters for a specific API endpoint.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                path: {
+                                    type: "string",
+                                    description: "API Path (e.g. '/api/v1/projects')",
+                                },
+                                method: {
+                                    type: "string",
+                                    description: "HTTP Method (e.g. 'POST', 'GET')",
+                                },
+                            },
+                            required: ["path"],
+                        },
+                    },
                 ],
             };
         });
         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 results = await this.searchInFiles(query, method, version);
                 return {
                     content: [
                         {
@@ -126,6 +154,30 @@ class ApiDocsServer {
                     ],
                 };
             }
+            if (request.params.name === "get_api_details") {
+                const apiPath = String(request.params.arguments?.path);
+                const method = request.params.arguments?.method ? String(request.params.arguments?.method).toUpperCase() : undefined;
+                const result = await this.getApiDetails(apiPath, method);
+                if (!result) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: "text",
+                                text: `API endpoint not found: ${method ? method + " " : ""}${apiPath}`,
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
             throw new McpError(ErrorCode.MethodNotFound, "Tool not found");
         });
     }
@@ -153,23 +205,50 @@ class ApiDocsServer {
         }
         return results;
     }
-    // Simple search helper
-    async searchInFiles(query) {
+    // Smart search helper with scoring, filtering, and limits
+    async searchInFiles(query, filterMethod, filterVersion) {
         const files = await this.getAllFiles(ENDPOINTS_DIR);
-        const matches = [];
+        let allMatches = [];
         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);
-                // Assuming structure has "endpoints" array
+                // Version Filtering (File level or content level check)
+                // Check if file path contains version (e.g. "v1/...") or json has version field
+                if (filterVersion) {
+                    const fileVersion = fileName.split(path.sep)[0]; // e.g. "v1" from "v1/projects/..."
+                    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({
-                                source: fileName,
-                                ...endpoint
+                        // Method Filtering
+                        if (filterMethod && endpoint.method.toUpperCase() !== filterMethod) {
+                            continue;
+                        }
+                        // 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 (score > 0) {
+                            allMatches.push({
+                                score,
+                                file: fileName,
+                                method: endpoint.method,
+                                path: endpoint.path,
+                                summary: endpoint.summary,
+                                description: endpoint.description
                             });
                         }
                     }
@@ -179,7 +258,46 @@ class ApiDocsServer {
                 // Ignore parse errors
             }
         }
-        return matches;
+        // 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) {
+            return {
+                results: limitedResults,
+                warning: `Found ${totalFound} results. Showing top ${LIMIT}. Please refine your search query or use filters.`
+            };
+        }
+        return limitedResults;
+    }
+    // Helper to get full details of an API
+    async getApiDetails(apiPath, method) {
+        const files = await this.getAllFiles(ENDPOINTS_DIR);
+        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 endpoint of json.endpoints) {
+                        if (endpoint.path === apiPath) {
+                            if (method && endpoint.method.toUpperCase() !== method) {
+                                continue;
+                            }
+                            return {
+                                sourceFile: path.relative(ENDPOINTS_DIR, filePath),
+                                ...endpoint
+                            };
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                // Ignore parse errors
+            }
+        }
+        return null;
     }
     async run() {
         const transport = new StdioServerTransport();

package/endpoints/README.md

@@ -0,0 +1,40 @@
+# API Documentation Structure
+
+This directory contains the API definitions for the FMEA system, organized by version and resource.
+
+## Directory Pattern
+
+All endpoints MUST follow this strictly nested directory structure:
+
+```
+endpoints/
+  ├── v1/
+  │   └── {resource}/
+  │       ├── core.json       # Basic CRUD operations
+  │       ├── {feature}.json  # Feature-specific endpoints (e.g., export.json)
+  │       └── ...
+  └── v2/
+      └── {resource}/
+          └── ...
+```
+
+### Rules
+
+1.  **Directory Required**: Every resource (e.g., `projects`, `users`) MUST be a directory, even if it only contains one file.
+2.  **Core File**: The main file for a resource should be named `core.json`. This typically contains the basic CRUD operations.
+3.  **Feature Files**: Distinct sub-features should be separated into their own JSON files with descriptive names (e.g., `excel.json`, `lifecycle.json`).
+4.  **JSON Structure**: Each file must contain a valid JSON object with:
+    - `category`: String (Resource category name)
+    - `version`: String ("v1" or "v2")
+    - `description`: String (Resource description)
+    - `endpoints`: Array of endpoint objects.
+
+### Example
+
+```
+endpoints/v1/projects/
+  ├── core.json
+  ├── lifecycle.json
+  ├── data.json
+  └── recommendations.json
+```

package/endpoints/v1/projects/core.json

@@ -0,0 +1,156 @@
+{
+  "category": "Project Management",
+  "version": "v1",
+  "description": "Core Project Operations",
+  "endpoints": [
+    {
+      "path": "/api/v1/projects",
+      "method": "POST",
+      "operationId": "save_5",
+      "summary": "Create project",
+      "description": "Create a new project",
+      "tags": [],
+      "parameters": [],
+      "requestBody": {
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProjectCreationDTO"
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/my",
+      "method": "GET",
+      "operationId": "findAllByUserId",
+      "summary": "Get user projects",
+      "description": "Get all projects for the current user",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "size",
+          "in": "query",
+          "schema": {
+            "type": "integer",
+            "format": "int32",
+            "default": 20
+          }
+        },
+        {
+          "name": "page",
+          "in": "query",
+          "schema": {
+            "type": "integer",
+            "format": "int32",
+            "default": 1
+          }
+        }
+      ],
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{id}",
+      "method": "GET",
+      "operationId": "findById_4",
+      "summary": "Get project by ID",
+      "description": "Get a project by its ID",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{id}",
+      "method": "PUT",
+      "operationId": "update",
+      "summary": "Update project",
+      "description": "Update an existing project",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "requestBody": {
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProjectUpdateDTO"
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{id}",
+      "method": "DELETE",
+      "operationId": "delete",
+      "summary": "Delete project",
+      "description": "Delete a project by its ID",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    }
+  ]
+}

package/endpoints/v1/projects/data.json

@@ -0,0 +1,64 @@
+{
+  "category": "Project Management",
+  "version": "v1",
+  "description": "Project Data Operations",
+  "endpoints": [
+    {
+      "path": "/api/v1/projects/{id}/export",
+      "method": "GET",
+      "operationId": "exportData",
+      "summary": "Export project data",
+      "description": "Export project data",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/import",
+      "method": "POST",
+      "operationId": "importData",
+      "summary": "Import project data",
+      "description": "Import project data from a file",
+      "tags": [],
+      "parameters": [],
+      "requestBody": {
+        "content": {
+          "multipart/form-data": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "file": {
+                  "$ref": "#/components/schemas/FormDataContentDisposition"
+                }
+              }
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    }
+  ]
+}

package/endpoints/v1/projects/lifecycle.json

@@ -0,0 +1,85 @@
+{
+  "category": "Project Management",
+  "version": "v1",
+  "description": "Project Lifecycle Actions",
+  "endpoints": [
+    {
+      "path": "/api/v1/projects/{id}/activate",
+      "method": "PUT",
+      "operationId": "activateProject",
+      "summary": "Activate project",
+      "description": "Activate a project",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{id}/deactivate",
+      "method": "PUT",
+      "operationId": "deactivateProject",
+      "summary": "Deactivate project",
+      "description": "Deactivate a project",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{id}/copy",
+      "method": "POST",
+      "operationId": "copy",
+      "summary": "Copy project",
+      "description": "Copy a project",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    }
+  ]
+}

package/endpoints/v1/projects/recommendations.json

@@ -0,0 +1,58 @@
+{
+  "category": "Project Management",
+  "version": "v1",
+  "description": "Project Recommendations",
+  "endpoints": [
+    {
+      "path": "/api/v1/projects/recommendations",
+      "method": "GET",
+      "operationId": "getProjects",
+      "summary": "Get project recommendations",
+      "description": "Get recommended projects",
+      "tags": [],
+      "parameters": [],
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{id}/recommendations",
+      "method": "GET",
+      "operationId": "getRecommendationsByProjectId",
+      "summary": "Get project recommendations by ID",
+      "description": "Get recommendations for a specific project",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "status",
+          "in": "query",
+          "schema": {
+            "pattern": "NotCompleted|In-Progress|Delay|Completed|All",
+            "type": "string"
+          }
+        }
+      ],
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    }
+  ]
+}