fmea-api-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,87 @@
+# API Docs MCP Server
+
+This project is a Model Context Protocol (MCP) server that provides API specifications from the `endpoints` directory to AI assistants (Claude, Zed, etc.).
+
+## Installation & Execution (NPM)
+
+This project runs in a Node.js environment.
+
+1.  **Install Dependencies**
+    ```bash
+    cd mcp-server
+    npm install
+    ```
+
+2.  **Build**
+    ```bash
+    npm run build
+    ```
+
+3.  **Run**
+    ```bash
+    npm start
+    ```
+
+## Publishing
+
+To publish the package to NPM, use the following command:
+
+```bash
+cd mcp-server
+npm publish --access public
+```
+
+After publishing, you can run it from anywhere using `npx`:
+
+```bash
+npx -y fmea-api-mcp-server
+```
+
+## Client Configuration (Load Configuration)
+
+To use this server with clients like Claude Desktop or Zed, add the following to your configuration file.
+
+### Local Execution (Source-based)
+
+```json
+{
+  "mcpServers": {
+    "api-docs": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/fmea-api-mcp/mcp-server/dist/index.js"
+      ],
+      "env": {
+        "ENDPOINTS_DIR": "/absolute/path/to/fmea-api-mcp/endpoints"
+      }
+    }
+  }
+}
+```
+
+### NPX Execution (Published Package-based)
+
+When the package is published to NPM:
+
+```json
+{
+  "mcpServers": {
+    "api-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "fmea-api-mcp-server"
+      ],
+      "env": {
+        "ENDPOINTS_DIR": "/absolute/path/to/fmea-api-mcp/endpoints"
+      }
+    }
+  }
+}
+```
+
+- `ENDPOINTS_DIR`: The absolute path to the directory containing API specification files. The default is `../endpoints` (relative path from mcp-server), but it's recommended to set this explicitly when using npx.
+
+## Features
+- **Resources**: Can read JSON files in the `endpoints` folder.
+- **Tools**: Use the `search_apis` tool to search APIs by keyword.

package/dist/index.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import * as fs from "fs/promises";
+import * as fsSync from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Directory where endpoint definitions are stored.
+// Priority:
+// 1. Environment variable ENDPOINTS_DIR
+// 2. Packaged: dist/../endpoints (relative to bundled index.js)
+// 3. Local Dev: dist/../../endpoints (relative to mcp-server/src)
+const PACKAGED_ENDPOINTS_DIR = path.resolve(__dirname, "../endpoints");
+const LOCAL_ENDPOINTS_DIR = path.resolve(__dirname, "../../endpoints");
+const ENDPOINTS_DIR = process.env.ENDPOINTS_DIR ||
+    (fsSync.existsSync(PACKAGED_ENDPOINTS_DIR) ? PACKAGED_ENDPOINTS_DIR : LOCAL_ENDPOINTS_DIR);
+class ApiDocsServer {
+    server;
+    constructor() {
+        this.server = new Server({
+            name: "api-docs-mcp",
+            version: "1.0.0",
+        }, {
+            capabilities: {
+                resources: {},
+                tools: {},
+            },
+        });
+        this.setupResourceHandlers();
+        this.setupToolHandlers();
+        // Error handling
+        this.server.onerror = (error) => console.error("[MCP Error]", error);
+        process.on("SIGINT", async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    async setupResourceHandlers() {
+        // List available resources (files in endpoints directory)
+        this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+            try {
+                const files = await this.getAllFiles(ENDPOINTS_DIR);
+                const resources = files.map((filePath) => {
+                    const relativePath = path.relative(ENDPOINTS_DIR, filePath);
+                    // URI scheme: endpoints://v1/system.json
+                    const uri = `endpoints://${relativePath}`;
+                    return {
+                        uri,
+                        name: relativePath,
+                        mimeType: "application/json",
+                        description: `API Documentation for ${relativePath}`
+                    };
+                });
+                return {
+                    resources,
+                };
+            }
+            catch (error) {
+                console.error("Error listing resources:", error);
+                return { resources: [] };
+            }
+        });
+        // Read specific resource
+        this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            const uri = request.params.uri;
+            if (!uri.startsWith("endpoints://")) {
+                throw new McpError(ErrorCode.InvalidRequest, "Unknown URI scheme");
+            }
+            const relativePath = uri.replace("endpoints://", "");
+            const finalPath = path.join(ENDPOINTS_DIR, relativePath);
+            // Security check: prevent directory traversal
+            if (!finalPath.startsWith(ENDPOINTS_DIR)) {
+                throw new McpError(ErrorCode.InvalidRequest, "Access denied");
+            }
+            try {
+                const content = await fs.readFile(finalPath, "utf-8");
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: "application/json",
+                            text: content,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                throw new McpError(ErrorCode.InvalidRequest, `File not found: ${relativePath}`);
+            }
+        });
+    }
+    async setupToolHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: [
+                    {
+                        name: "search_apis",
+                        description: "Search for API endpoints by keyword across all documentation files",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                query: {
+                                    type: "string",
+                                    description: "Search query (e.g. 'user login', 'POST /api/v1')",
+                                },
+                            },
+                            required: ["query"],
+                        },
+                    },
+                ],
+            };
+        });
+        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);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(results, null, 2),
+                        },
+                    ],
+                };
+            }
+            throw new McpError(ErrorCode.MethodNotFound, "Tool not found");
+        });
+    }
+    // Recursive file listing helper
+    async getAllFiles(dir) {
+        let results = [];
+        try {
+            const list = await fs.readdir(dir);
+            for (const file of list) {
+                const filePath = path.join(dir, file);
+                const stat = await fs.stat(filePath);
+                if (stat && stat.isDirectory()) {
+                    results = results.concat(await this.getAllFiles(filePath));
+                }
+                else {
+                    if (file.endsWith(".json")) {
+                        results.push(filePath);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            // Directory might not exist or be empty
+            console.error(`Warning: Could not read directory ${dir}`);
+        }
+        return results;
+    }
+    // Simple search helper
+    async searchInFiles(query) {
+        const files = await this.getAllFiles(ENDPOINTS_DIR);
+        const matches = [];
+        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
+                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
+                            });
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                // Ignore parse errors
+            }
+        }
+        return matches;
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("MCP Server running on stdio");
+    }
+}
+const server = new ApiDocsServer();
+server.run().catch(console.error);

package/endpoints/v1/authentication.json

@@ -0,0 +1,171 @@
+{
+  "category": "Authentication",
+  "version": "v1",
+  "description": "인증/인가 관련 API",
+  "endpoints": [
+    {
+      "path": "/api/v1/auth/login",
+      "method": "POST",
+      "operationId": "login",
+      "summary": "User login",
+      "description": "Authenticate user with credentials",
+      "tags": [],
+      "parameters": [],
+      "requestBody": {
+        "content": {
+          "*/*": {
+            "schema": {
+              "$ref": "#/components/schemas/CredentialsDTO"
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "*/*": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/auth/logout",
+      "method": "POST",
+      "operationId": "logout",
+      "summary": "User logout",
+      "description": "Logout user with refresh token",
+      "tags": [],
+      "parameters": [],
+      "requestBody": {
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/TokenDTO"
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "*/*": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/auth/refresh",
+      "method": "POST",
+      "operationId": "refresh",
+      "summary": "Refresh access token",
+      "description": "Refresh authentication token using refresh token",
+      "tags": [],
+      "parameters": [],
+      "requestBody": {
+        "content": {
+          "*/*": {
+            "schema": {
+              "$ref": "#/components/schemas/TokenDTO"
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "*/*": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/auth/change-password",
+      "method": "POST",
+      "operationId": "changePassword",
+      "summary": "Change password",
+      "description": "Change user password",
+      "tags": [],
+      "parameters": [],
+      "requestBody": {
+        "content": {
+          "*/*": {
+            "schema": {
+              "$ref": "#/components/schemas/PasswordChangeDTO"
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "*/*": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/auth/password-reset-request",
+      "method": "POST",
+      "operationId": "passwordResetRequest",
+      "summary": "Password reset request",
+      "description": "Request password reset",
+      "tags": [],
+      "parameters": [],
+      "requestBody": {
+        "content": {
+          "*/*": {
+            "schema": {
+              "$ref": "#/components/schemas/PasswordResetDTO"
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "*/*": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/oauth/callback/{service}",
+      "method": "GET",
+      "operationId": "callback",
+      "summary": "OAuth callback",
+      "description": "OAuth authentication callback endpoint",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "service",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "code",
+          "in": "query",
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "requestBody": null,
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "*/*": {}
+          }
+        }
+      }
+    }
+  ]
+}

package/endpoints/v1/block-diagrams.json

@@ -0,0 +1,214 @@
+{
+  "category": "Block Diagrams",
+  "version": "v1",
+  "description": "블록 다이어그램 관련 API",
+  "endpoints": [
+    {
+      "path": "/api/v1/projects/{projectId}/blockdiagrams",
+      "method": "GET",
+      "operationId": "list",
+      "summary": "List block diagrams",
+      "description": "Get all block diagrams for a project",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "projectId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "requestBody": null,
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{projectId}/blockdiagrams/search",
+      "method": "GET",
+      "operationId": "search",
+      "summary": "Search block diagrams",
+      "description": "Search block diagrams by model, item, division, or block title",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "projectId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "model",
+          "in": "query",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "item",
+          "in": "query",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "divisionId",
+          "in": "query",
+          "schema": {
+            "type": "integer",
+            "format": "int32"
+          }
+        },
+        {
+          "name": "blockTitle",
+          "in": "query",
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "requestBody": null,
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{projectId}/blockdiagrams/{blockId}/nodes",
+      "method": "GET",
+      "operationId": "findNodesByIds",
+      "summary": "Find nodes by IDs",
+      "description": "Get nodes for a specific block diagram",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "projectId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "blockId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "requestBody": null,
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{projectId}/blockdiagrams/{blockId}/nodes",
+      "method": "POST",
+      "operationId": "saveNodes",
+      "summary": "Save nodes",
+      "description": "Save nodes for a block diagram",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "projectId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "blockId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "requestBody": {
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/BlockNodeSaveDTO"
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    },
+    {
+      "path": "/api/v1/projects/{projectId}/blockdiagrams/{blockId}/nodes/batch",
+      "method": "POST",
+      "operationId": "batchNodes",
+      "summary": "Batch create nodes",
+      "description": "Create multiple nodes in a batch operation",
+      "tags": [],
+      "parameters": [
+        {
+          "name": "projectId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "blockId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "requestBody": {
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/BlockNodeBatchDTO"
+              }
+            }
+          }
+        }
+      },
+      "responses": {
+        "default": {
+          "description": "default response",
+          "content": {
+            "application/json": {}
+          }
+        }
+      }
+    }
+  ]
+}