Skip to content

Commit 21e4833

Browse files
author
Lasim
committed
feat(backend): enhance MCP client types API with categorized response
1 parent a214653 commit 21e4833

File tree

7 files changed

+290
-40
lines changed

7 files changed

+290
-40
lines changed

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ desktop.ini
1212
*.sw?
1313

1414
# AI
15-
CLAUDE.md
15+
/CLAUDE.md
1616
.claude/
1717

1818
# Node.js dependencies

‎services/backend/api-spec.json‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5345,7 +5345,7 @@
53455345
"tags": [
53465346
"User Satellite Configuration"
53475347
],
5348-
"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.",
5348+
"description": "Returns a list of all supported MCP client types grouped by action category (connection, ai-instructions). Categories are dynamically extracted from client configurations.",
53495349
"security": [
53505350
{
53515351
"cookieAuth": []
@@ -5356,13 +5356,13 @@
53565356
],
53575357
"responses": {
53585358
"200": {
5359-
"description": "List of supported MCP client types",
5359+
"description": "List of supported MCP client types grouped by category",
53605360
"content": {
53615361
"application/json": {
53625362
"schema": {
53635363
"type": "object",
53645364
"properties": {
5365-
"clients": {
5365+
"categories": {
53665366
"type": "array",
53675367
"items": {
53685368
"type": "object",
@@ -5373,25 +5373,52 @@
53735373
"name": {
53745374
"type": "string"
53755375
},
5376-
"iconPath": {
5376+
"description": {
53775377
"type": "string"
5378+
},
5379+
"clients": {
5380+
"type": "array",
5381+
"items": {
5382+
"type": "object",
5383+
"properties": {
5384+
"id": {
5385+
"type": "string"
5386+
},
5387+
"name": {
5388+
"type": "string"
5389+
},
5390+
"iconPath": {
5391+
"type": "string"
5392+
},
5393+
"description": {
5394+
"type": "string"
5395+
}
5396+
},
5397+
"required": [
5398+
"id",
5399+
"name",
5400+
"iconPath"
5401+
],
5402+
"additionalProperties": false
5403+
}
53785404
}
53795405
},
53805406
"required": [
53815407
"id",
53825408
"name",
5383-
"iconPath"
5409+
"description",
5410+
"clients"
53845411
],
53855412
"additionalProperties": false
53865413
},
5387-
"description": "List of supported MCP client types with metadata"
5414+
"description": "Categorized list of supported MCP client types"
53885415
}
53895416
},
53905417
"required": [
5391-
"clients"
5418+
"categories"
53925419
],
53935420
"additionalProperties": false,
5394-
"description": "List of supported MCP client types"
5421+
"description": "List of supported MCP client types grouped by category"
53955422
}
53965423
}
53975424
}

‎services/backend/api-spec.yaml‎

Lines changed: 29 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3676,21 +3676,21 @@ paths:
36763676
summary: List supported MCP client types
36773677
tags:
36783678
- User Satellite Configuration
3679-
description: Returns a list of all supported MCP client types that can be
3680-
configured with the DeployStack Satellite service. No Content-Type
3681-
header required for this GET request.
3679+
description: Returns a list of all supported MCP client types grouped by action
3680+
category (connection, ai-instructions). Categories are dynamically
3681+
extracted from client configurations.
36823682
security:
36833683
- cookieAuth: []
36843684
- bearerAuth: []
36853685
responses:
36863686
"200":
3687-
description: List of supported MCP client types
3687+
description: List of supported MCP client types grouped by category
36883688
content:
36893689
application/json:
36903690
schema:
36913691
type: object
36923692
properties:
3693-
clients:
3693+
categories:
36943694
type: array
36953695
items:
36963696
type: object
@@ -3699,18 +3699,37 @@ paths:
36993699
type: string
37003700
name:
37013701
type: string
3702-
iconPath:
3702+
description:
37033703
type: string
3704+
clients:
3705+
type: array
3706+
items:
3707+
type: object
3708+
properties:
3709+
id:
3710+
type: string
3711+
name:
3712+
type: string
3713+
iconPath:
3714+
type: string
3715+
description:
3716+
type: string
3717+
required:
3718+
- id
3719+
- name
3720+
- iconPath
3721+
additionalProperties: false
37043722
required:
37053723
- id
37063724
- name
3707-
- iconPath
3725+
- description
3726+
- clients
37083727
additionalProperties: false
3709-
description: List of supported MCP client types with metadata
3728+
description: Categorized list of supported MCP client types
37103729
required:
3711-
- clients
3730+
- categories
37123731
additionalProperties: false
3713-
description: List of supported MCP client types
3732+
description: List of supported MCP client types grouped by category
37143733
"401":
37153734
description: Unauthorized - Authentication required
37163735
content:

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# DeployStack MCP Integration
2+
3+
## Overview
4+
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.
5+
6+
## Available Meta-Tools
7+
8+
DeployStack exposes **2 meta-tools** that provide access to all installed MCP servers:
9+
10+
### 1. discover_mcp_tools
11+
**Purpose:** Search for available MCP tools using short keywords
12+
13+
**Usage:**
14+
- Use 1-3 keywords only (e.g., "github", "markdown", "database postgres")
15+
- Avoid full sentences or long descriptions
16+
- Returns tool paths in format `serverName:toolName`
17+
18+
**Examples:**
19+
- Search for GitHub tools: `query: "github"`
20+
- Search for file operations: `query: "filesystem"`
21+
- Search for database tools: `query: "postgres query"`
22+
23+
### 2. execute_mcp_tool
24+
**Purpose:** Execute a discovered tool by its path
25+
26+
**Usage:**
27+
- Use `tool_path` from discovery results (format: `serverName:toolName`)
28+
- Pass tool-specific arguments as `arguments` object
29+
- Check tool description from discovery for argument schema
30+
31+
## Workflow
32+
33+
**Before starting any task, follow this pattern:**
34+
35+
1. **Discover Available Tools**
36+
```
37+
Use discover_mcp_tools with relevant keywords
38+
Example: query="github" to find GitHub-related tools
39+
```
40+
41+
2. **Review Results**
42+
```
43+
Check returned tool paths and descriptions
44+
Verify a tool matches your task
45+
```
46+
47+
3. **Execute Tool**
48+
```
49+
Use execute_mcp_tool with:
50+
- tool_path from discovery (e.g., "github:create_issue")
51+
- arguments specific to that tool
52+
```
53+
54+
4. **Fallback to Manual**
55+
```
56+
If no suitable tool found, proceed with manual implementation
57+
```
58+
59+
## Search Best Practices
60+
61+
**Good Queries (1-3 keywords):**
62+
- "github"
63+
- "markdown convert"
64+
- "database postgres"
65+
- "slack send"
66+
- "figma design"
67+
68+
**Bad Queries (too verbose):**
69+
- ❌ "I need to create an issue in GitHub repository"
70+
- ❌ "How do I read files from the filesystem?"
71+
- ❌ "Can you help me query the database?"
72+
73+
**Use the tool name or main function as keywords.**
74+
75+
## When to Check for MCP Tools
76+
77+
**Always check before:**
78+
- External API integrations (GitHub, Slack, Figma, etc.)
79+
- Database operations (PostgreSQL, MySQL, MongoDB, etc.)
80+
- File system operations
81+
- Content conversion (Markdown, PDF, etc.)
82+
- Cloud service operations (AWS, GCP, Azure, etc.)
83+
84+
**Skip for:**
85+
- Pure code generation tasks
86+
- Architecture discussions
87+
- Explaining concepts
88+
- Refactoring existing code
89+
90+
## Important Notes
91+
92+
1. **Keyword-Based Search:** Use short, specific keywords - not full sentences
93+
2. **Tool Path Format:** Always use `serverName:toolName` (e.g., `github:create_issue`)
94+
3. **Check First:** Before manual implementation, always discover available tools
95+
4. **Tool-Specific Args:** Check tool description from discovery for argument schema
96+
5. **Fallback Strategy:** If no tool found or tool fails, proceed with manual approach
97+
98+
---
99+
100+
**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‎

Lines changed: 69 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
11
import { type FastifyInstance } from 'fastify';
22
import { requireAuthenticationAny, requireOAuthScope } from '../../../middleware/oauthMiddleware';
3-
import {
4-
CLIENT_TYPES,
5-
CLIENTS_LIST_RESPONSE_SCHEMA,
3+
import {
4+
CLIENT_TYPES,
5+
CLIENTS_LIST_RESPONSE_SCHEMA,
66
ERROR_RESPONSE_SCHEMA,
77
type ClientsListResponse,
8-
type ErrorResponse
8+
type ErrorResponse,
9+
type ClientCategory,
10+
type ClientInfo
911
} from './schemas';
1012

13+
// Import the config generator to extract categories dynamically
14+
import { generateClientConfig } from './config';
15+
1116
export default async function listClients(server: FastifyInstance) {
1217
server.get('/me/satellite/clients', {
1318
preValidation: [
@@ -17,15 +22,15 @@ export default async function listClients(server: FastifyInstance) {
1722
schema: {
1823
tags: ['User Satellite Configuration'],
1924
summary: 'List supported MCP client types',
20-
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.',
25+
description: 'Returns a list of all supported MCP client types grouped by action category (connection, ai-instructions). Categories are dynamically extracted from client configurations.',
2126
security: [
2227
{ cookieAuth: [] },
2328
{ bearerAuth: [] }
2429
],
2530
response: {
2631
200: {
2732
...CLIENTS_LIST_RESPONSE_SCHEMA,
28-
description: 'List of supported MCP client types'
33+
description: 'List of supported MCP client types grouped by category'
2934
},
3035
401: {
3136
...ERROR_RESPONSE_SCHEMA,
@@ -43,10 +48,66 @@ export default async function listClients(server: FastifyInstance) {
4348
}
4449
}, async (request, reply) => {
4550
try {
51+
// Build category map: category -> clients that support it
52+
const categoryMap = new Map<string, Set<ClientInfo>>();
53+
54+
// Loop through all client types and extract their categories
55+
for (const client of CLIENT_TYPES) {
56+
try {
57+
const actions = generateClientConfig(client.id);
58+
server.log.debug({ clientId: client.id, actionsCount: actions.length }, 'Generated client config');
59+
60+
// Extract unique categories from this client's actions
61+
for (const action of actions) {
62+
if (action.category) {
63+
if (!categoryMap.has(action.category)) {
64+
categoryMap.set(action.category, new Set());
65+
}
66+
categoryMap.get(action.category)!.add(client);
67+
server.log.debug({ category: action.category, clientId: client.id }, 'Added client to category');
68+
}
69+
}
70+
} catch (err) {
71+
// Log error for debugging
72+
server.log.error({ clientId: client.id, error: err }, 'Failed to generate config for client');
73+
continue;
74+
}
75+
}
76+
77+
server.log.debug({ categoriesCount: categoryMap.size }, 'Total categories extracted');
78+
79+
// Convert map to array of categories
80+
const categories: ClientCategory[] = Array.from(categoryMap.entries()).map(([categoryId, clients]) => {
81+
// Determine category name and description based on ID
82+
let name = categoryId;
83+
let description = '';
84+
85+
switch (categoryId) {
86+
case 'connection':
87+
name = 'Connection Setup';
88+
description = 'Configure your AI client to connect to DeployStack satellite';
89+
break;
90+
case 'ai-instructions':
91+
name = 'AI Instructions';
92+
description = 'Project-specific instruction files for AI coding assistants';
93+
break;
94+
default:
95+
name = categoryId.charAt(0).toUpperCase() + categoryId.slice(1);
96+
description = `${name} configuration`;
97+
}
98+
99+
return {
100+
id: categoryId,
101+
name,
102+
description,
103+
clients: Array.from(clients)
104+
};
105+
});
106+
46107
const response: ClientsListResponse = {
47-
clients: CLIENT_TYPES
108+
categories
48109
};
49-
110+
50111
const jsonString = JSON.stringify(response);
51112
return reply.status(200).type('application/json').send(jsonString);
52113
} catch (error) {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ function createBase64Config(config: object): string {
2222
}
2323

2424
// Client configuration generator - now returns array of actions
25-
function generateClientConfig(clientType: string): ClientConfigResponse {
25+
export function generateClientConfig(clientType: string): ClientConfigResponse {
2626
const satelliteUrl = 'https://satellite.deploystack.io';
2727
const actions: ClientConfigResponse = [];
2828

0 commit comments

Comments
 (0)