feat(all): add satellite selection to MCP client configuration

- Add satellite selection dropdown to dashboard modal and client-configuration page
- Replace hardcoded satellite URL with dynamic database lookup
- Filter to show only active satellites (status='active')
- Auto-select first satellite when only one is available
- Implement 50/50 grid layout with client on left, satellite on right
- Add Alert component for no satellites available state
- Backend: Add getSatelliteUrl() helper with active satellite filtering
- Backend: Update generateClientConfig() to accept satelliteUrl parameter
- Backend: Add satelliteId query parameter support to config endpoints
- Frontend: Add loadAvailableSatellites() with TeamService integration
- Frontend: Add satellite selection watchers for dynamic config reload
- Fix parameter order in client-configuration loadConfiguration()

Close #548

Author: Lasim

services/backend/api-spec.json

@@ -5038,6 +5038,15 @@
         ],
         "description": "Returns configuration actions filtered by category (connection, ai-instructions) for the specified MCP client.",
         "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "satelliteId",
+            "required": false,
+            "description": "Satellite ID to generate configuration for (optional, defaults to first active satellite)"
+          },
           {
             "schema": {
               "type": "string"
@@ -5377,6 +5386,15 @@
         ],
         "description": "Returns all configuration actions for the specified MCP client. Consider using /config/:category/:client for filtered results.",
         "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "satelliteId",
+            "required": false,
+            "description": "Satellite ID to generate configuration for (optional, defaults to first active satellite)"
+          },
           {
             "schema": {
               "type": "string",

services/backend/api-spec.yaml

@@ -3480,6 +3480,13 @@ paths:
       description: Returns configuration actions filtered by category (connection,
         ai-instructions) for the specified MCP client.
       parameters:
+        - schema:
+            type: string
+          in: query
+          name: satelliteId
+          required: false
+          description: Satellite ID to generate configuration for (optional, defaults to
+            first active satellite)
         - schema:
             type: string
           in: path
@@ -3702,6 +3709,13 @@ paths:
       description: Returns all configuration actions for the specified MCP client.
         Consider using /config/:category/:client for filtered results.
       parameters:
+        - schema:
+            type: string
+          in: query
+          name: satelliteId
+          required: false
+          description: Satellite ID to generate configuration for (optional, defaults to
+            first active satellite)
         - schema:
             type: string
             enum:

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

@@ -54,7 +54,8 @@ export default async function listClients(server: FastifyInstance) {
       // Loop through all client types and extract their categories
       for (const client of CLIENT_TYPES) {
         try {
-          const actions = generateClientConfig(client.id);
+          // Use placeholder URL since we're only discovering categories, not generating actual configs
+          const actions = await generateClientConfig(client.id, 'https://placeholder.satellite.url');
           server.log.debug({ clientId: client.id, actionsCount: actions.length }, 'Generated client config');
 
           // Extract unique categories from this client's actions

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

@@ -1,14 +1,18 @@
 import { type FastifyInstance } from 'fastify';
 import { requireAuthenticationAny, requireOAuthScope } from '../../../middleware/oauthMiddleware';
+import { getDb, getSchema } from '../../../db';
+import { eq, and, or, isNull } from 'drizzle-orm';
 import fs from 'fs';
 import path from 'path';
 import {
   CLIENT_PARAM_SCHEMA,
   CLIENT_CATEGORY_PARAM_SCHEMA,
+  SATELLITE_ID_QUERY_SCHEMA,
   SUCCESS_RESPONSE_SCHEMA,
   ERROR_RESPONSE_SCHEMA,
   type ClientParams,
   type ClientCategoryParams,
+  type SatelliteIdQuery,
   type ErrorResponse,
   type JsonAction,
   type LinkAction,
@@ -23,9 +27,44 @@ function createBase64Config(config: object): string {
   return Buffer.from(JSON.stringify(config)).toString('base64');
 }
 
+// Helper function to get satellite URL from database
+async function getSatelliteUrl(
+  satelliteId: string | undefined,
+  teamId: string,
+  db: ReturnType<typeof getDb>,
+  satellites: ReturnType<typeof getSchema>['satellites']
+): Promise<string> {
+  // Build query condition - if satelliteId provided, use it; otherwise get first active satellite
+  const query = satelliteId
+    ? eq(satellites.id, satelliteId)
+    : or(
+        and(eq(satellites.satellite_type, 'global'), isNull(satellites.team_id)),
+        and(eq(satellites.satellite_type, 'team'), eq(satellites.team_id, teamId))
+      );
+
+  const satelliteRecords = await db
+    .select({ satellite_url: satellites.satellite_url })
+    .from(satellites)
+    .where(
+      and(
+        eq(satellites.status, 'active'),  // CRITICAL: Only active satellites
+        query
+      )
+    )
+    .limit(1);
+
+  if (satelliteRecords.length === 0) {
+    throw new Error('No active satellites available');
+  }
+
+  return satelliteRecords[0].satellite_url;
+}
+
 // Client configuration generator - now returns array of actions
-export function generateClientConfig(clientType: string): ClientConfigResponse {
-  const satelliteUrl = 'https://satellite.deploystack.io';
+export async function generateClientConfig(
+  clientType: string,
+  satelliteUrl: string
+): Promise<ClientConfigResponse> {
   const actions: ClientConfigResponse = [];
 
   // Read AI instruction files from local directory
@@ -239,7 +278,10 @@ export function generateClientConfig(clientType: string): ClientConfigResponse {
 
 export default async function getClientConfig(server: FastifyInstance) {
   // New route with category filtering
-  server.get('/me/satellite/config/:category/:client', {
+  server.get<{
+    Params: ClientCategoryParams;
+    Querystring: SatelliteIdQuery;
+  }>('/me/satellite/config/:category/:client', {
     preValidation: [
       requireAuthenticationAny(),
       requireOAuthScope('mcp:read')
@@ -253,6 +295,7 @@ export default async function getClientConfig(server: FastifyInstance) {
         { bearerAuth: [] }
       ],
       params: CLIENT_CATEGORY_PARAM_SCHEMA,
+      querystring: SATELLITE_ID_QUERY_SCHEMA,
       response: {
         200: {
           ...SUCCESS_RESPONSE_SCHEMA,
@@ -275,9 +318,35 @@ export default async function getClientConfig(server: FastifyInstance) {
   }, async (request, reply) => {
     try {
       const { category, client } = request.params as ClientCategoryParams;
+      const { satelliteId } = request.query as SatelliteIdQuery;
+      const userId = request.user!.id;
+
+      const db = getDb();
+      const { satellites, teams } = getSchema();
+
+      // Get user's default team
+      const defaultTeam = await db
+        .select({ id: teams.id })
+        .from(teams)
+        .where(
+          and(
+            eq(teams.owner_id, userId),
+            eq(teams.is_default, true)
+          )
+        )
+        .limit(1);
+
+      if (defaultTeam.length === 0) {
+        throw new Error('No default team found for user');
+      }
+
+      const teamId = defaultTeam[0].id;
+
+      // Get satellite URL from database
+      const satelliteUrl = await getSatelliteUrl(satelliteId, teamId, db, satellites);
 
-      // Generate all client-specific configuration actions
-      const allActions = generateClientConfig(client);
+      // Generate all client-specific configuration actions with dynamic URL
+      const allActions = await generateClientConfig(client, satelliteUrl);
 
       // Filter by category
       const filteredActions = allActions.filter(action => action.category === category);
@@ -295,7 +364,10 @@ export default async function getClientConfig(server: FastifyInstance) {
   });
 
   // Keep legacy route for backward compatibility (returns all actions)
-  server.get('/me/satellite/config/:client', {
+  server.get<{
+    Params: ClientParams;
+    Querystring: SatelliteIdQuery;
+  }>('/me/satellite/config/:client', {
     preValidation: [
       requireAuthenticationAny(),
       requireOAuthScope('mcp:read')
@@ -309,6 +381,7 @@ export default async function getClientConfig(server: FastifyInstance) {
         { bearerAuth: [] }
       ],
       params: CLIENT_PARAM_SCHEMA,
+      querystring: SATELLITE_ID_QUERY_SCHEMA,
       response: {
         200: {
           ...SUCCESS_RESPONSE_SCHEMA,
@@ -331,9 +404,35 @@ export default async function getClientConfig(server: FastifyInstance) {
   }, async (request, reply) => {
     try {
       const { client } = request.params as ClientParams;
+      const { satelliteId } = request.query as SatelliteIdQuery;
+      const userId = request.user!.id;
+
+      const db = getDb();
+      const { satellites, teams } = getSchema();
+
+      // Get user's default team
+      const defaultTeam = await db
+        .select({ id: teams.id })
+        .from(teams)
+        .where(
+          and(
+            eq(teams.owner_id, userId),
+            eq(teams.is_default, true)
+          )
+        )
+        .limit(1);
+
+      if (defaultTeam.length === 0) {
+        throw new Error('No default team found for user');
+      }
+
+      const teamId = defaultTeam[0].id;
+
+      // Get satellite URL from database
+      const satelliteUrl = await getSatelliteUrl(satelliteId, teamId, db, satellites);
 
-      // Generate client-specific configuration actions
-      const configActions = generateClientConfig(client);
+      // Generate client-specific configuration actions with dynamic URL
+      const configActions = await generateClientConfig(client, satelliteUrl);
 
       const jsonString = JSON.stringify(configActions);
       return reply.status(200).type('application/json').send(jsonString);

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

@@ -80,6 +80,17 @@ export const CLIENT_CATEGORY_PARAM_SCHEMA = {
   additionalProperties: false
 } as const;
 
+export const SATELLITE_ID_QUERY_SCHEMA = {
+  type: 'object',
+  properties: {
+    satelliteId: {
+      type: 'string',
+      description: 'Satellite ID to generate configuration for (optional, defaults to first active satellite)'
+    }
+  },
+  additionalProperties: false
+} as const;
+
 // New response schema for array-based configuration with actions
 export const SUCCESS_RESPONSE_SCHEMA = {
   type: 'array',
@@ -236,6 +247,10 @@ export interface ClientCategoryParams {
   client: ClientType;
 }
 
+export interface SatelliteIdQuery {
+  satelliteId?: string;
+}
+
 export interface ClientsListResponse {
   categories: readonly ClientCategory[];
 }