@mhingston5/conduit 1.1.5 → 1.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhingston5/conduit",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "type": "module",
   "description": "A secure Code Mode execution substrate for MCP agents",
   "main": "index.js",

package/src/auth.cmd.ts

@@ -157,27 +157,39 @@ export async function handleAuth(options: AuthOptions) {
             }
 
             try {
-                const body = new URLSearchParams();
-                body.set('grant_type', 'authorization_code');
-                body.set('code', code);
-                body.set('redirect_uri', redirectUri);
-                body.set('client_id', options.clientId);
+                const payload: Record<string, string> = {
+                    grant_type: 'authorization_code',
+                    code,
+                    redirect_uri: redirectUri,
+                    client_id: options.clientId,
+                };
+
                 if (options.clientSecret) {
-                    body.set('client_secret', options.clientSecret);
+                    payload.client_secret = options.clientSecret;
                 }
                 if (codeVerifier) {
-                    body.set('code_verifier', codeVerifier);
+                    payload.code_verifier = codeVerifier;
                 }
                 if (resolvedResource) {
-                    body.set('resource', resolvedResource);
+                    payload.resource = resolvedResource;
                 }
 
-                const response = await axios.post(resolvedTokenUrl, body, {
-                    headers: {
-                        'Content-Type': 'application/x-www-form-urlencoded',
-                        'Accept': 'application/json',
-                    },
-                });
+                const tokenHostname = new URL(resolvedTokenUrl).hostname;
+                const useJson = tokenHostname === 'auth.atlassian.com';
+
+                const response = useJson
+                    ? await axios.post(resolvedTokenUrl, payload, {
+                        headers: {
+                            'Content-Type': 'application/json',
+                            'Accept': 'application/json',
+                        },
+                    })
+                    : await axios.post(resolvedTokenUrl, new URLSearchParams(payload), {
+                        headers: {
+                            'Content-Type': 'application/x-www-form-urlencoded',
+                            'Accept': 'application/json',
+                        },
+                    });
 
                 const { refresh_token, access_token } = response.data;
 

package/src/core/config.service.ts

@@ -29,6 +29,8 @@ export const UpstreamCredentialsSchema = z.object({
     tokenUrl: z.string().optional(),
     refreshToken: z.string().optional(),
     scopes: z.array(z.string()).optional(),
+    tokenRequestFormat: z.enum(['form', 'json']).optional(),
+    tokenParams: z.record(z.string(), z.string()).optional(),
     apiKey: z.string().optional(),
     bearerToken: z.string().optional(),
     headerName: z.string().optional(),
@@ -41,6 +43,20 @@ export const HttpUpstreamSchema = z.object({
     credentials: UpstreamCredentialsSchema.optional(),
 });
 
+export const StreamableHttpUpstreamSchema = z.object({
+    id: z.string(),
+    type: z.literal('streamableHttp'),
+    url: z.string(),
+    credentials: UpstreamCredentialsSchema.optional(),
+});
+
+export const SseUpstreamSchema = z.object({
+    id: z.string(),
+    type: z.literal('sse'),
+    url: z.string(),
+    credentials: UpstreamCredentialsSchema.optional(),
+});
+
 export const StdioUpstreamSchema = z.object({
     id: z.string(),
     type: z.literal('stdio'),
@@ -49,7 +65,12 @@ export const StdioUpstreamSchema = z.object({
     env: z.record(z.string(), z.string()).optional(),
 });
 
-export const UpstreamInfoSchema = z.union([HttpUpstreamSchema, StdioUpstreamSchema]);
+export const UpstreamInfoSchema = z.union([
+    HttpUpstreamSchema,
+    StreamableHttpUpstreamSchema,
+    SseUpstreamSchema,
+    StdioUpstreamSchema,
+]);
 
 export type ResourceLimits = z.infer<typeof ResourceLimitsSchema>;
 
@@ -134,10 +155,14 @@ export class ConfigService {
             (fs.existsSync(path.resolve(process.cwd(), 'conduit.yaml')) ? 'conduit.yaml' :
                 (fs.existsSync(path.resolve(process.cwd(), 'conduit.json')) ? 'conduit.json' : null));
 
-        if (!configPath) return {};
+        if (!configPath) {
+            console.warn(`[Conduit] No config file found in ${process.cwd()}. Running with default settings.`);
+            return {};
+        }
 
         try {
             const fullPath = path.resolve(process.cwd(), configPath);
+            console.error(`[Conduit] Loading config from ${fullPath}`);
             let fileContent = fs.readFileSync(fullPath, 'utf-8');
 
             // Env var substitution: ${VAR} or ${VAR:-default}

package/src/core/execution.service.ts

@@ -137,17 +137,22 @@ export class ExecutionService {
         const packages = await this.gatewayService.listToolPackages();
         const allBindings = [];
 
+        this.logger.debug({ packageCount: packages.length, packages: packages.map(p => p.id) }, 'Fetching tool bindings');
+
         for (const pkg of packages) {
             try {
                 // Determine if we need to fetch tools for this package
                 // Optimization: if allowedTools is strict, we could filter packages here
 
                 const stubs = await this.gatewayService.listToolStubs(pkg.id, context);
+                this.logger.debug({ packageId: pkg.id, stubCount: stubs.length }, 'Got stubs from package');
                 allBindings.push(...stubs.map(s => toToolBinding(s.id, undefined, s.description)));
             } catch (err: any) {
                 this.logger.warn({ packageId: pkg.id, err: err.message }, 'Failed to list stubs for package');
             }
         }
+
+        this.logger.info({ totalBindings: allBindings.length }, 'Tool bindings ready for SDK generation');
         return allBindings;
     }
 

package/src/core/policy.service.ts

@@ -66,6 +66,11 @@ export class PolicyService {
                 return true;
             }
 
+            // Improved matching: if pattern has only one part, match it against the tool's name part
+            if (patternParts.length === 1 && toolParts.length > 1) {
+                return patternParts[0] === toolParts[toolParts.length - 1];
+            }
+
             // Exact match: pattern parts must equal tool parts
             if (patternParts.length !== toolParts.length) return false;
             for (let i = 0; i < patternParts.length; i++) {

package/src/core/request.controller.ts

@@ -128,6 +128,8 @@ export class RequestController {
                 return this.handleInitialize(params, context, id);
             case 'notifications/initialized':
                 return null; // Notifications don't get responses per MCP spec
+            case 'mcp_register_upstream':
+                return this.handleRegisterUpstream(params, context, id);
             case 'ping':
                 return { jsonrpc: '2.0', id, result: {} };
             default:
@@ -138,6 +140,23 @@ export class RequestController {
         }
     }
 
+    private async handleRegisterUpstream(params: any, context: ExecutionContext, id: string | number): Promise<JSONRPCResponse> {
+        if (!params || !params.id || !params.type || (!params.url && !params.command)) {
+            return this.errorResponse(id, -32602, 'Missing registration parameters (id, type, url/command)');
+        }
+
+        try {
+            this.gatewayService.registerUpstream(params);
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: { success: true }
+            };
+        } catch (err: any) {
+            return this.errorResponse(id, -32001, err.message);
+        }
+    }
+
     private async handleDiscoverTools(params: any, context: ExecutionContext, id: string | number): Promise<JSONRPCResponse> {
         const tools = await this.gatewayService.discoverTools(context);
 
@@ -215,14 +234,20 @@ export class RequestController {
         if (!params) return this.errorResponse(id, -32602, 'Missing parameters');
         const { name, arguments: toolArgs } = params;
 
+        const toolId = this.gatewayService.policyService.parseToolName(name);
+        const baseName = toolId.name;
+        const isConduit = toolId.namespace === 'conduit' || toolId.namespace === '';
+
         // Route built-in tools to their specific handlers
-        switch (name) {
-            case 'mcp_execute_typescript':
-                return this.handleExecuteToolCall('typescript', toolArgs, context, id);
-            case 'mcp_execute_python':
-                return this.handleExecuteToolCall('python', toolArgs, context, id);
-            case 'mcp_execute_isolate':
-                return this.handleExecuteToolCall('isolate', toolArgs, context, id);
+        if (isConduit) {
+            switch (baseName) {
+                case 'mcp_execute_typescript':
+                    return this.handleExecuteToolCall('typescript', toolArgs, context, id);
+                case 'mcp_execute_python':
+                    return this.handleExecuteToolCall('python', toolArgs, context, id);
+                case 'mcp_execute_isolate':
+                    return this.handleExecuteToolCall('isolate', toolArgs, context, id);
+            }
         }
 
         const response = await this.gatewayService.callTool(name, toolArgs, context);

package/src/gateway/auth.service.ts

@@ -12,6 +12,8 @@ export interface UpstreamCredentials {
     tokenUrl?: string;
     refreshToken?: string;
     scopes?: string[];
+    tokenRequestFormat?: 'form' | 'json';
+    tokenParams?: Record<string, string>;
 }
 
 interface CachedToken {
@@ -23,6 +25,8 @@ export class AuthService {
     private logger: Logger;
     // Cache tokens separately from credentials to avoid mutation
     private tokenCache = new Map<string, CachedToken>();
+    // Keep the latest refresh token in-memory (rotating tokens)
+    private refreshTokenCache = new Map<string, string>();
     // Prevent concurrent refresh requests for the same client
     private refreshLocks = new Map<string, Promise<string>>();
 
@@ -81,23 +85,56 @@ export class AuthService {
         this.logger.info({ tokenUrl: creds.tokenUrl, clientId: creds.clientId }, 'Refreshing OAuth2 token');
 
         try {
-            const body = new URLSearchParams();
-            body.set('grant_type', 'refresh_token');
-            body.set('refresh_token', creds.refreshToken);
-            body.set('client_id', creds.clientId);
+            const tokenUrl = creds.tokenUrl;
+            const cachedRefreshToken = this.refreshTokenCache.get(cacheKey);
+            const refreshToken = cachedRefreshToken || creds.refreshToken;
+
+            if (!refreshToken) {
+                throw new Error('OAuth2 credentials missing required fields for refresh');
+            }
+
+            const payload: Record<string, string> = {
+                grant_type: 'refresh_token',
+                refresh_token: refreshToken,
+                client_id: creds.clientId,
+            };
+
             if (creds.clientSecret) {
-                body.set('client_secret', creds.clientSecret);
+                payload.client_secret = creds.clientSecret;
             }
 
-            const response = await axios.post(creds.tokenUrl, body, {
-                headers: {
-                    'Content-Type': 'application/x-www-form-urlencoded',
-                    'Accept': 'application/json',
-                },
-            });
+            if (creds.tokenParams) {
+                Object.assign(payload, creds.tokenParams);
+            }
 
-            const { access_token, expires_in } = response.data;
-            const expiresInSeconds = Number(expires_in) || 3600;
+            const requestFormat = (() => {
+                if (creds.tokenRequestFormat) return creds.tokenRequestFormat;
+                try {
+                    const hostname = new URL(tokenUrl).hostname;
+                    if (hostname === 'auth.atlassian.com') return 'json';
+                } catch {
+                    // ignore
+                }
+                return 'form';
+            })();
+
+            const response = requestFormat === 'json'
+                ? await axios.post(tokenUrl, payload, {
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Accept': 'application/json',
+                    },
+                })
+                : await axios.post(tokenUrl, new URLSearchParams(payload), {
+                    headers: {
+                        'Content-Type': 'application/x-www-form-urlencoded',
+                        'Accept': 'application/json',
+                    },
+                });
+
+            const { access_token, expires_in, refresh_token } = response.data;
+            const expiresInRaw = Number(expires_in);
+            const expiresInSeconds = Number.isFinite(expiresInRaw) ? expiresInRaw : 3600;
 
             // Cache the token (don't mutate the input credentials)
             this.tokenCache.set(cacheKey, {
@@ -105,6 +142,11 @@ export class AuthService {
                 expiresAt: Date.now() + (expiresInSeconds * 1000),
             });
 
+            // Some providers (e.g. Atlassian) rotate refresh tokens
+            if (typeof refresh_token === 'string' && refresh_token.length > 0) {
+                this.refreshTokenCache.set(cacheKey, refresh_token);
+            }
+
             return `Bearer ${access_token}`;
         } catch (err: any) {
             const errorMsg = err.response?.data?.error_description || err.response?.data?.error || err.message;

package/src/gateway/gateway.service.ts

@@ -1,4 +1,6 @@
 import { Logger } from 'pino';
+import { HostClient } from './host.client.js';
+import { StdioTransport } from '../transport/stdio.transport.js';
 import { UpstreamClient, UpstreamInfo } from './upstream.client.js';
 import { AuthService } from './auth.service.js';
 import { SchemaCache, ToolSchema } from './schema.cache.js';
@@ -72,41 +74,69 @@ const BUILT_IN_TOOLS: ToolSchema[] = [
 
 export class GatewayService {
     private logger: Logger;
-    private clients: Map<string, UpstreamClient> = new Map();
+    private clients: Map<string, any> = new Map();
     private authService: AuthService;
     private schemaCache: SchemaCache;
     private urlValidator: IUrlValidator;
-    private policyService: PolicyService;
+    public policyService: PolicyService;
     private ajv: Ajv;
     // Cache compiled validators to avoid recompilation on every call
     private validatorCache = new Map<string, any>();
 
     constructor(logger: Logger, urlValidator: IUrlValidator, policyService?: PolicyService) {
-        this.logger = logger;
+        this.logger = logger.child({ component: 'GatewayService' });
+        this.logger.debug('GatewayService instance created');
         this.urlValidator = urlValidator;
         this.authService = new AuthService(logger);
         this.schemaCache = new SchemaCache(logger);
         this.policyService = policyService ?? new PolicyService();
-        this.ajv = new Ajv({ strict: false }); // Strict mode off for now to be permissive with upstream schemas
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        this.ajv = new Ajv({ strict: false });
         (addFormats as any).default(this.ajv);
     }
 
     registerUpstream(info: UpstreamInfo) {
         const client = new UpstreamClient(this.logger, info, this.authService, this.urlValidator);
         this.clients.set(info.id, client);
-        this.logger.info({ upstreamId: info.id }, 'Registered upstream MCP');
+        this.logger.info({ upstreamId: info.id, totalRegistered: this.clients.size }, 'Registered upstream MCP');
+    }
+
+    registerHost(transport: StdioTransport) {
+        // NOTE: The host (VS Code) cannot receive tools/call requests - it's the CLIENT.
+        // We only register it for potential future use (e.g., sampling requests).
+        // DO NOT use the host as a tool provider fallback.
+        this.logger.debug('Host transport available but not registered as tool upstream (protocol limitation)');
     }
 
     async listToolPackages(): Promise<ToolPackage[]> {
-        return Array.from(this.clients.entries()).map(([id, client]) => ({
+        const upstreams = Array.from(this.clients.entries()).map(([id, client]) => ({
             id,
-            description: `Upstream ${id}`, // NOTE: Upstream description fetching deferred to V2
+            description: `Upstream ${id}`,
             version: '1.0.0'
         }));
+
+        return [
+            { id: 'conduit', description: 'Conduit built-in execution tools', version: '1.0.0' },
+            ...upstreams
+        ];
+    }
+
+    getBuiltInTools(): ToolSchema[] {
+        return BUILT_IN_TOOLS;
     }
 
     async listToolStubs(packageId: string, context: ExecutionContext): Promise<ToolStub[]> {
+        if (packageId === 'conduit') {
+            const stubs = BUILT_IN_TOOLS.map(t => ({
+                id: `conduit__${t.name}`,
+                name: t.name,
+                description: t.description
+            }));
+            if (context.allowedTools) {
+                return stubs.filter(t => this.policyService.isToolAllowed(t.id, context.allowedTools!));
+            }
+            return stubs;
+        }
+
         const client = this.clients.get(packageId);
         if (!client) {
             throw new Error(`Upstream package not found: ${packageId}`);
@@ -114,43 +144,51 @@ export class GatewayService {
 
         let tools = this.schemaCache.get(packageId);
 
-        // Try manifest first if tools not cached
+        // Discover tools if not cached
         if (!tools) {
-            try {
-                // Try to fetch manifest first
-                const manifest = await client.getManifest(context);
-                if (manifest) {
-                    const stubs: ToolStub[] = manifest.tools.map((t: any) => ({
-                        id: `${packageId}__${t.name}`,
-                        name: t.name,
-                        description: t.description
-                    }));
-
-                    if (context.allowedTools) {
-                        return stubs.filter(t => this.policyService.isToolAllowed(t.id, context.allowedTools!));
+            // 1) Try to get manifest (if supported)
+            if (typeof (client as any).getManifest === 'function') {
+                try {
+                    const manifest = await (client as any).getManifest(context);
+                    if (manifest && manifest.tools) {
+                        tools = manifest.tools as ToolSchema[];
                     }
-                    return stubs;
+                } catch (e: any) {
+                    this.logger.debug({ upstreamId: packageId, err: e.message }, 'Manifest fetch failed (will fallback)');
                 }
-            } catch (e) {
-                // Manifest fetch failed, fall back
-                this.logger.debug({ packageId, err: e }, 'Manifest fetch failed, falling back to RPC');
             }
 
-            const response = await client.call({
-                jsonrpc: '2.0',
-                id: 'discovery',
-                method: 'tools/list',
-            }, context);
+            // 2) Fall back to RPC discovery
+            if (!tools) {
+                try {
+                    if (typeof (client as any).listTools === 'function') {
+                        tools = await (client as any).listTools();
+                    } else {
+                        const response = await client.call({
+                            jsonrpc: '2.0',
+                            id: 'discovery',
+                            method: 'tools/list',
+                        }, context);
+
+                        if (response.result?.tools) {
+                            tools = response.result.tools as ToolSchema[];
+                        } else {
+                            this.logger.warn({ upstreamId: packageId, error: response.error }, 'Failed to discover tools via RPC');
+                        }
+                    }
+                } catch (e: any) {
+                    this.logger.error({ upstreamId: packageId, err: e.message }, 'Error during tool discovery');
+                }
+            }
 
-            if (response.result?.tools) {
-                tools = response.result.tools as ToolSchema[];
+            if (tools && tools.length > 0) {
                 this.schemaCache.set(packageId, tools);
-            } else {
-                this.logger.warn({ upstreamId: packageId, error: response.error }, 'Failed to discover tools from upstream');
-                tools = [];
+                this.logger.info({ upstreamId: packageId, toolCount: tools.length }, 'Discovered tools from upstream');
             }
         }
 
+        if (!tools) tools = [];
+
         const stubs: ToolStub[] = tools.map(t => ({
             id: `${packageId}__${t.name}`,
             name: t.name,
@@ -170,17 +208,29 @@ export class GatewayService {
         }
 
         const parsed = this.policyService.parseToolName(toolId);
-        const toolName = parsed.name; // Use a new variable for the un-namespaced name
-
-        // Check for built-in tools
-        const builtIn = BUILT_IN_TOOLS.find(t => t.name === toolId); // Compare with the full toolId
-        if (builtIn) return builtIn;
+        const namespace = parsed.namespace;
+        const toolName = parsed.name;
+
+        // Check for built-in tools (now namespaced as conduit__*)
+        if (namespace === 'conduit' || namespace === '') {
+            const builtIn = BUILT_IN_TOOLS.find(t => t.name === toolName);
+            if (builtIn) {
+                return { ...builtIn, name: `conduit__${builtIn.name}` };
+            }
+        }
 
-        const upstreamId = parsed.namespace;
+        const upstreamId = namespace;
+        if (!upstreamId) {
+            // Un-namespaced tool lookup: try all upstreams
+            for (const id of this.clients.keys()) {
+                const schema = await this.getToolSchema(`${id}__${toolName}`, context);
+                if (schema) return schema;
+            }
+            return null;
+        }
 
         // Ensure we have schemas for this upstream
         if (!this.schemaCache.get(upstreamId)) {
-            // Force refresh if missing
             await this.listToolStubs(upstreamId, context);
         }
 
@@ -189,7 +239,6 @@ export class GatewayService {
 
         if (!tool) return null;
 
-        // Return schema with namespaced name
         return {
             ...tool,
             name: toolId
@@ -197,41 +246,48 @@ export class GatewayService {
     }
 
     async discoverTools(context: ExecutionContext): Promise<ToolSchema[]> {
-        const allTools: ToolSchema[] = [...BUILT_IN_TOOLS];
+        const allTools: ToolSchema[] = BUILT_IN_TOOLS.map(t => ({
+            ...t,
+            name: `conduit__${t.name}`
+        }));
+
+        this.logger.debug({ clientCount: this.clients.size, clientIds: Array.from(this.clients.keys()) }, 'Starting tool discovery');
 
         for (const [id, client] of this.clients.entries()) {
-            let tools = this.schemaCache.get(id);
+            // Skip host - it's not a tool provider
+            if (id === 'host') {
+                continue;
+            }
 
-            if (!tools) {
-                const response = await client.call({
-                    jsonrpc: '2.0',
-                    id: 'discovery',
-                    method: 'tools/list', // Standard MCP method
-                }, context);
+            this.logger.debug({ upstreamId: id }, 'Discovering tools from upstream');
 
-                if (response.result?.tools) {
-                    tools = response.result.tools as ToolSchema[];
-                    this.schemaCache.set(id, tools);
-                } else {
-                    this.logger.warn({ upstreamId: id, error: response.error }, 'Failed to discover tools from upstream');
-                    tools = [];
-                }
+            // reuse unified discovery logic
+            try {
+                await this.listToolStubs(id, context);
+            } catch (e: any) {
+                this.logger.error({ upstreamId: id, err: e.message }, 'Failed to list tool stubs');
             }
+            const tools = this.schemaCache.get(id) || [];
 
-            const prefixedTools = tools.map(t => ({ ...t, name: `${id}__${t.name}` }));
+            this.logger.debug({ upstreamId: id, toolCount: tools.length }, 'Discovery result');
 
-            if (context.allowedTools) {
-                // Support wildcard patterns: "mock.*" matches "mock__hello"
-                allTools.push(...prefixedTools.filter(t => this.policyService.isToolAllowed(t.name, context.allowedTools!)));
-            } else {
-                allTools.push(...prefixedTools);
+            if (tools && tools.length > 0) {
+                const prefixedTools = tools.map(t => ({ ...t, name: `${id}__${t.name}` }));
+                if (context.allowedTools) {
+                    allTools.push(...prefixedTools.filter(t => this.policyService.isToolAllowed(t.name, context.allowedTools!)));
+                } else {
+                    allTools.push(...prefixedTools);
+                }
             }
         }
 
+        this.logger.info({ totalTools: allTools.length }, 'Tool discovery complete');
         return allTools;
     }
 
     async callTool(name: string, params: any, context: ExecutionContext): Promise<JSONRPCResponse> {
+        this.logger.debug({ name, upstreamCount: this.clients.size }, 'GatewayService.callTool called');
+
         if (context.allowedTools && !this.policyService.isToolAllowed(name, context.allowedTools)) {
             this.logger.warn({ name, allowedTools: context.allowedTools }, 'Tool call blocked by allowlist');
             return {
@@ -248,14 +304,43 @@ export class GatewayService {
         const upstreamId = toolId.namespace;
         const toolName = toolId.name;
 
+        this.logger.debug({ name, upstreamId, toolName }, 'Parsed tool name');
+
+        // Fallback for namespaceless calls: try to find the tool in any registered upstream
+        if (!upstreamId) {
+            this.logger.debug({ toolName }, 'Namespaceless call, attempting discovery across upstreams');
+            const allStubs = await this.discoverTools(context);
+            const found = allStubs.find(t => {
+                const parts = t.name.split('__');
+                return parts[parts.length - 1] === toolName;
+            });
+
+            if (found) {
+                this.logger.debug({ original: name, resolved: found.name }, 'Resolved namespaceless tool');
+                return this.callTool(found.name, params, context);
+            }
+
+            // No fallback to host - it doesn't support server-to-client tool calls
+            const upstreamList = Array.from(this.clients.keys()).filter(k => k !== 'host');
+            return {
+                jsonrpc: '2.0',
+                id: 0,
+                error: {
+                    code: -32601,
+                    message: `Tool '${toolName}' not found. Discovered ${allStubs.length} tools from upstreams: [${upstreamList.join(', ') || 'none'}]. Available tools: ${allStubs.map(t => t.name).slice(0, 10).join(', ')}${allStubs.length > 10 ? '...' : ''}`,
+                },
+            };
+        }
+
         const client = this.clients.get(upstreamId);
         if (!client) {
+            this.logger.error({ upstreamId, availableUpstreams: Array.from(this.clients.keys()) }, 'Upstream not found');
             return {
                 jsonrpc: '2.0',
                 id: 0,
                 error: {
                     code: -32003,
-                    message: `Upstream not found: ${upstreamId}`,
+                    message: `Upstream not found: '${upstreamId}'. Available: ${Array.from(this.clients.keys()).join(', ') || 'none'}`,
                 },
             };
         }