Phase 5: Server-Side API Routes for MCP Management #127

New issue

Closed

opened 2025-11-22 22:55:23 +00:00 by rwachters · 0 comments

rwachters commented

2025-11-22 22:55:23 +00:00

(Migrated from github.com)

Phase 5: Server-Side API Routes for MCP Management

Epic: NF.EA1 - Local MCP Servers

Description

This issue covers the implementation of the necessary server-side RESTful API endpoints for managing local MCP servers and their associated tools. These routes will serve as the bridge between the client-side application and the backend services and database tables created in Phase 1.

The primary responsibilities of this API are to provide unique, persistent IDs for new server configurations and to handle the synchronization of tool definitions discovered by the client.

User Stories & Acceptance Criteria

✅ Task Checklist

US5.1: Implement Local MCP Server API Routes
- POST /api/v1/local-mcp-servers:
  - Create a new route to generate a unique, server-side ID for a new local MCP server configuration.
  - The endpoint should call LocalMCPServerService.generateServerId.
  - It should return the newly created serverId to the client, which will then store it in its local database.
  - The route must be authenticated and associate the new server ID with the current user.
- DELETE /api/v1/local-mcp-servers/{serverId}:
  - Create a route to delete a local MCP server record from the server.
  - This endpoint should call LocalMCPServerService.deleteServer.
  - The service logic must perform an ownership check to ensure the user is authorized to delete the server.
  - Cascading deletes in the database should handle the removal of associated tool links (LocalMCPToolDefinitionTable).
US5.2: Implement Local MCP Tool Management API Route
- POST /api/v1/local-mcp-servers/{serverId}/tools/sync:
  - Create the synchronization endpoint that the client calls after performing tool discovery.
  - The request body will contain a list of tool definitions (List<ToolDefinition>).
  - The endpoint must perform an ownership check on the {serverId}.
  - It should invoke a service method (e.g., ToolService.synchronizeMcpTools) that performs the create, update, and delete logic to align the server's database with the list of tools provided by the client.
  - The operation must be transactional.

Architectural Context

Stateless and Client-Driven: These API endpoints are designed to be stateless. The client is the source of truth for the full MCP server configuration and the list of available tools. The client uses these APIs to notify the server of changes and to obtain persistent identifiers.
ID Generation Workflow: The client will first create a full LocalMCPServer configuration in its local database with a temporary ID. It will then call POST /api/v1/local-mcp-servers to receive a permanent, server-generated ID, which it then updates in its local record. This decouples the client's local state from the server's persistence layer.
Security: All endpoints defined in this phase must be protected and require user authentication. Every operation must include an ownership check to ensure a user can only access or modify their own resources (LocalMCPServer records and their associated tools).
Synchronization Endpoint: The /sync endpoint is the cornerstone of tool management. By accepting a complete list of tools for a server, it simplifies the logic on both the client and server. The client doesn't need to track individual changes, and the server's logic is idempotent—it simply makes its state match the client's provided state.

# Phase 5: Server-Side API Routes for MCP Management **Epic**: `NF.EA1 - Local MCP Servers` ## Description This issue covers the implementation of the necessary server-side RESTful API endpoints for managing local MCP servers and their associated tools. These routes will serve as the bridge between the client-side application and the backend services and database tables created in Phase 1. The primary responsibilities of this API are to provide unique, persistent IDs for new server configurations and to handle the synchronization of tool definitions discovered by the client. --- ## User Stories & Acceptance Criteria ### ✅ Task Checklist - [ ] **US5.1: Implement Local MCP Server API Routes** - [ ] **`POST /api/v1/local-mcp-servers`**: - Create a new route to generate a unique, server-side ID for a new local MCP server configuration. - The endpoint should call `LocalMCPServerService.generateServerId`. - It should return the newly created `serverId` to the client, which will then store it in its local database. - The route must be authenticated and associate the new server ID with the current user. - [ ] **`DELETE /api/v1/local-mcp-servers/{serverId}`**: - Create a route to delete a local MCP server record from the server. - This endpoint should call `LocalMCPServerService.deleteServer`. - The service logic must perform an ownership check to ensure the user is authorized to delete the server. - Cascading deletes in the database should handle the removal of associated tool links (`LocalMCPToolDefinitionTable`). - [ ] **US5.2: Implement Local MCP Tool Management API Route** - [ ] **`POST /api/v1/local-mcp-servers/{serverId}/tools/sync`**: - Create the synchronization endpoint that the client calls after performing tool discovery. - The request body will contain a list of tool definitions (`List<ToolDefinition>`). - The endpoint must perform an ownership check on the `{serverId}`. - It should invoke a service method (e.g., `ToolService.synchronizeMcpTools`) that performs the create, update, and delete logic to align the server's database with the list of tools provided by the client. - The operation must be transactional. --- <details> <summary><h3>Architectural Context</h3></summary> - **Stateless and Client-Driven**: These API endpoints are designed to be stateless. The client is the source of truth for the full MCP server configuration and the list of available tools. The client uses these APIs to notify the server of changes and to obtain persistent identifiers. - **ID Generation Workflow**: The client will first create a full `LocalMCPServer` configuration in its local database with a temporary ID. It will then call `POST /api/v1/local-mcp-servers` to receive a permanent, server-generated ID, which it then updates in its local record. This decouples the client's local state from the server's persistence layer. - **Security**: All endpoints defined in this phase must be protected and require user authentication. Every operation must include an ownership check to ensure a user can only access or modify their own resources (`LocalMCPServer` records and their associated tools). - **Synchronization Endpoint**: The `/sync` endpoint is the cornerstone of tool management. By accepting a complete list of tools for a server, it simplifies the logic on both the client and server. The client doesn't need to track individual changes, and the server's logic is idempotent—it simply makes its state match the client's provided state. </details>