feat(backend): enhance MCP client types API with categorized response

Author: Lasim

.gitignore

@@ -12,7 +12,7 @@ desktop.ini
 *.sw?
 
 # AI
-CLAUDE.md
+/CLAUDE.md
 .claude/
 
 # Node.js dependencies

services/backend/api-spec.json

@@ -5345,7 +5345,7 @@
         "tags": [
           "User Satellite Configuration"
         ],
-        "description": "Returns a list of all supported MCP client types that can be configured with the DeployStack Satellite service. No Content-Type header required for this GET request.",
+        "description": "Returns a list of all supported MCP client types grouped by action category (connection, ai-instructions). Categories are dynamically extracted from client configurations.",
         "security": [
           {
             "cookieAuth": []
@@ -5356,13 +5356,13 @@
         ],
         "responses": {
           "200": {
-            "description": "List of supported MCP client types",
+            "description": "List of supported MCP client types grouped by category",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "clients": {
+                    "categories": {
                       "type": "array",
                       "items": {
                         "type": "object",
@@ -5373,25 +5373,52 @@
                           "name": {
                             "type": "string"
                           },
-                          "iconPath": {
+                          "description": {
                             "type": "string"
+                          },
+                          "clients": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "properties": {
+                                "id": {
+                                  "type": "string"
+                                },
+                                "name": {
+                                  "type": "string"
+                                },
+                                "iconPath": {
+                                  "type": "string"
+                                },
+                                "description": {
+                                  "type": "string"
+                                }
+                              },
+                              "required": [
+                                "id",
+                                "name",
+                                "iconPath"
+                              ],
+                              "additionalProperties": false
+                            }
                           }
                         },
                         "required": [
                           "id",
                           "name",
-                          "iconPath"
+                          "description",
+                          "clients"
                         ],
                         "additionalProperties": false
                       },
-                      "description": "List of supported MCP client types with metadata"
+                      "description": "Categorized list of supported MCP client types"
                     }
                   },
                   "required": [
-                    "clients"
+                    "categories"
                   ],
                   "additionalProperties": false,
-                  "description": "List of supported MCP client types"
+                  "description": "List of supported MCP client types grouped by category"
                 }
               }
             }

services/backend/api-spec.yaml

@@ -3676,21 +3676,21 @@ paths:
       summary: List supported MCP client types
       tags:
         - User Satellite Configuration
-      description: Returns a list of all supported MCP client types that can be
-        configured with the DeployStack Satellite service. No Content-Type
-        header required for this GET request.
+      description: Returns a list of all supported MCP client types grouped by action
+        category (connection, ai-instructions). Categories are dynamically
+        extracted from client configurations.
       security:
         - cookieAuth: []
         - bearerAuth: []
       responses:
         "200":
-          description: List of supported MCP client types
+          description: List of supported MCP client types grouped by category
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  clients:
+                  categories:
                     type: array
                     items:
                       type: object
@@ -3699,18 +3699,37 @@ paths:
                           type: string
                         name:
                           type: string
-                        iconPath:
+                        description:
                           type: string
+                        clients:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              id:
+                                type: string
+                              name:
+                                type: string
+                              iconPath:
+                                type: string
+                              description:
+                                type: string
+                            required:
+                              - id
+                              - name
+                              - iconPath
+                            additionalProperties: false
                       required:
                         - id
                         - name
-                        - iconPath
+                        - description
+                        - clients
                       additionalProperties: false
-                    description: List of supported MCP client types with metadata
+                    description: Categorized list of supported MCP client types
                 required:
-                  - clients
+                  - categories
                 additionalProperties: false
-                description: List of supported MCP client types
+                description: List of supported MCP client types grouped by category
         "401":
           description: Unauthorized - Authentication required
           content:

services/backend/src/routes/users/satellite/ai-instructions/CLAUDE.md

@@ -0,0 +1,100 @@
+# DeployStack MCP Integration
+
+## Overview
+You have access to MCP (Model Context Protocol) tools through DeployStack's hierarchical router. Before attempting tasks manually, always check if a relevant MCP tool is available.
+
+## Available Meta-Tools
+
+DeployStack exposes **2 meta-tools** that provide access to all installed MCP servers:
+
+### 1. discover_mcp_tools
+**Purpose:** Search for available MCP tools using short keywords
+
+**Usage:**
+- Use 1-3 keywords only (e.g., "github", "markdown", "database postgres")
+- Avoid full sentences or long descriptions
+- Returns tool paths in format `serverName:toolName`
+
+**Examples:**
+- Search for GitHub tools: `query: "github"`
+- Search for file operations: `query: "filesystem"`
+- Search for database tools: `query: "postgres query"`
+
+### 2. execute_mcp_tool
+**Purpose:** Execute a discovered tool by its path
+
+**Usage:**
+- Use `tool_path` from discovery results (format: `serverName:toolName`)
+- Pass tool-specific arguments as `arguments` object
+- Check tool description from discovery for argument schema
+
+## Workflow
+
+**Before starting any task, follow this pattern:**
+
+1. **Discover Available Tools**
+   ```
+   Use discover_mcp_tools with relevant keywords
+   Example: query="github" to find GitHub-related tools
+   ```
+
+2. **Review Results**
+   ```
+   Check returned tool paths and descriptions
+   Verify a tool matches your task
+   ```
+
+3. **Execute Tool**
+   ```
+   Use execute_mcp_tool with:
+   - tool_path from discovery (e.g., "github:create_issue")
+   - arguments specific to that tool
+   ```
+
+4. **Fallback to Manual**
+   ```
+   If no suitable tool found, proceed with manual implementation
+   ```
+
+## Search Best Practices
+
+**Good Queries (1-3 keywords):**
+- "github"
+- "markdown convert"
+- "database postgres"
+- "slack send"
+- "figma design"
+
+**Bad Queries (too verbose):**
+- ❌ "I need to create an issue in GitHub repository"
+- ❌ "How do I read files from the filesystem?"
+- ❌ "Can you help me query the database?"
+
+**Use the tool name or main function as keywords.**
+
+## When to Check for MCP Tools
+
+**Always check before:**
+- External API integrations (GitHub, Slack, Figma, etc.)
+- Database operations (PostgreSQL, MySQL, MongoDB, etc.)
+- File system operations
+- Content conversion (Markdown, PDF, etc.)
+- Cloud service operations (AWS, GCP, Azure, etc.)
+
+**Skip for:**
+- Pure code generation tasks
+- Architecture discussions
+- Explaining concepts
+- Refactoring existing code
+
+## Important Notes
+
+1. **Keyword-Based Search:** Use short, specific keywords - not full sentences
+2. **Tool Path Format:** Always use `serverName:toolName` (e.g., `github:create_issue`)
+3. **Check First:** Before manual implementation, always discover available tools
+4. **Tool-Specific Args:** Check tool description from discovery for argument schema
+5. **Fallback Strategy:** If no tool found or tool fails, proceed with manual approach
+
+---
+
+**Remember:** DeployStack's hierarchical router means you only see 2 meta-tools, but they provide access to 100+ actual MCP tools. Always discover before implementing manually.

services/backend/src/routes/users/satellite/clients.ts

@@ -1,13 +1,18 @@
 import { type FastifyInstance } from 'fastify';
 import { requireAuthenticationAny, requireOAuthScope } from '../../../middleware/oauthMiddleware';
-import { 
-  CLIENT_TYPES, 
-  CLIENTS_LIST_RESPONSE_SCHEMA, 
+import {
+  CLIENT_TYPES,
+  CLIENTS_LIST_RESPONSE_SCHEMA,
   ERROR_RESPONSE_SCHEMA,
   type ClientsListResponse,
-  type ErrorResponse
+  type ErrorResponse,
+  type ClientCategory,
+  type ClientInfo
 } from './schemas';
 
+// Import the config generator to extract categories dynamically
+import { generateClientConfig } from './config';
+
 export default async function listClients(server: FastifyInstance) {
   server.get('/me/satellite/clients', {
     preValidation: [
@@ -17,15 +22,15 @@ export default async function listClients(server: FastifyInstance) {
     schema: {
       tags: ['User Satellite Configuration'],
       summary: 'List supported MCP client types',
-      description: 'Returns a list of all supported MCP client types that can be configured with the DeployStack Satellite service. No Content-Type header required for this GET request.',
+      description: 'Returns a list of all supported MCP client types grouped by action category (connection, ai-instructions). Categories are dynamically extracted from client configurations.',
       security: [
         { cookieAuth: [] },
         { bearerAuth: [] }
       ],
       response: {
         200: {
           ...CLIENTS_LIST_RESPONSE_SCHEMA,
-          description: 'List of supported MCP client types'
+          description: 'List of supported MCP client types grouped by category'
         },
         401: {
           ...ERROR_RESPONSE_SCHEMA,
@@ -43,10 +48,66 @@ export default async function listClients(server: FastifyInstance) {
     }
   }, async (request, reply) => {
     try {
+      // Build category map: category -> clients that support it
+      const categoryMap = new Map<string, Set<ClientInfo>>();
+
+      // Loop through all client types and extract their categories
+      for (const client of CLIENT_TYPES) {
+        try {
+          const actions = generateClientConfig(client.id);
+          server.log.debug({ clientId: client.id, actionsCount: actions.length }, 'Generated client config');
+
+          // Extract unique categories from this client's actions
+          for (const action of actions) {
+            if (action.category) {
+              if (!categoryMap.has(action.category)) {
+                categoryMap.set(action.category, new Set());
+              }
+              categoryMap.get(action.category)!.add(client);
+              server.log.debug({ category: action.category, clientId: client.id }, 'Added client to category');
+            }
+          }
+        } catch (err) {
+          // Log error for debugging
+          server.log.error({ clientId: client.id, error: err }, 'Failed to generate config for client');
+          continue;
+        }
+      }
+
+      server.log.debug({ categoriesCount: categoryMap.size }, 'Total categories extracted');
+
+      // Convert map to array of categories
+      const categories: ClientCategory[] = Array.from(categoryMap.entries()).map(([categoryId, clients]) => {
+        // Determine category name and description based on ID
+        let name = categoryId;
+        let description = '';
+
+        switch (categoryId) {
+          case 'connection':
+            name = 'Connection Setup';
+            description = 'Configure your AI client to connect to DeployStack satellite';
+            break;
+          case 'ai-instructions':
+            name = 'AI Instructions';
+            description = 'Project-specific instruction files for AI coding assistants';
+            break;
+          default:
+            name = categoryId.charAt(0).toUpperCase() + categoryId.slice(1);
+            description = `${name} configuration`;
+        }
+
+        return {
+          id: categoryId,
+          name,
+          description,
+          clients: Array.from(clients)
+        };
+      });
+
       const response: ClientsListResponse = {
-        clients: CLIENT_TYPES
+        categories
       };
-      
+
       const jsonString = JSON.stringify(response);
       return reply.status(200).type('application/json').send(jsonString);
     } catch (error) {

services/backend/src/routes/users/satellite/config.ts

@@ -22,7 +22,7 @@ function createBase64Config(config: object): string {
 }
 
 // Client configuration generator - now returns array of actions
-function generateClientConfig(clientType: string): ClientConfigResponse {
+export function generateClientConfig(clientType: string): ClientConfigResponse {
   const satelliteUrl = 'https://satellite.deploystack.io';
   const actions: ClientConfigResponse = [];