@smithery/api 0.24.0 → 0.25.0

package/src/lib/mcp-transport.ts

@@ -1,5 +1,5 @@
 /**
- * SmitheryConnectTransport - An MCP Transport that routes JSON-RPC messages through Smithery Connect.
+ * SmitheryTransport - An MCP Transport that routes JSON-RPC messages through Smithery Connect.
  *
  * This allows you to use the official MCP SDK's Client class with Smithery Connect as the transport layer.
  *
@@ -11,18 +11,17 @@
  * ```typescript
  * import { Client } from '@modelcontextprotocol/sdk/client/index.js';
  * import Smithery from '@smithery/api';
- * import { SmitheryConnectTransport } from '@smithery/api/mcp';
+ * import { SmitheryTransport } from '@smithery/api/mcp';
  *
  * const smithery = new Smithery({ apiKey: process.env.SMITHERY_API_KEY });
- * // Option 1: Let Smithery generate a connection ID
- * const transport = new SmitheryConnectTransport({
+ * // Option 1: Let Smithery generate a connection ID and use default namespace
+ * const transport = new SmitheryTransport({
  *   client: smithery,
- *   namespace: 'my-namespace',
  *   mcpUrl: 'https://mcp.example.com/sse',
  * });
  *
- * // Option 2: Use a specific connection ID (retrieves existing or creates new)
- * const transport2 = new SmitheryConnectTransport({
+ * // Option 2: Use a specific namespace and connection ID
+ * const transport2 = new SmitheryTransport({
  *   client: smithery,
  *   namespace: 'my-namespace',
  *   connectionId: 'my-connection',
@@ -43,7 +42,7 @@ import type { JSONRPCMessage, JSONRPCResponse, ServerCapabilities } from '@model
 import type { Smithery } from '../client';
 import type { Connection } from '../resources/beta/connect/connections';
 
-export interface SmitheryConnectTransportOptions {
+export interface SmitheryTransportOptions {
   /**
    * The Smithery client instance to use for making RPC calls.
    */
@@ -51,8 +50,9 @@ export interface SmitheryConnectTransportOptions {
 
   /**
    * The namespace for the Smithery Connect connection.
+   * If not provided, uses the first existing namespace or creates a new one.
    */
-  namespace: string;
+  namespace?: string;
 
   /**
    * The connection ID for the Smithery Connect connection.
@@ -77,9 +77,9 @@ export interface SmitheryConnectTransportOptions {
 // MCP protocol version
 const LATEST_PROTOCOL_VERSION = '2024-11-05';
 
-export class SmitheryConnectTransport implements Transport {
+export class SmitheryTransport implements Transport {
   private _client: Smithery;
-  private _namespace: string;
+  private _namespace: string | undefined;
   private _connectionId: string | undefined;
   private _mcpUrl: string | undefined;
   private _started = false;
@@ -101,7 +101,7 @@ export class SmitheryConnectTransport implements Transport {
     return this._connectionId;
   }
 
-  constructor(options: SmitheryConnectTransportOptions) {
+  constructor(options: SmitheryTransportOptions) {
     this._client = options.client;
     this._namespace = options.namespace;
     this._connectionId = options.connectionId;
@@ -124,7 +124,7 @@ export class SmitheryConnectTransport implements Transport {
   async start(): Promise<void> {
     if (this._started) {
       throw new Error(
-        'SmitheryConnectTransport already started! If using Client class, note that connect() calls start() automatically.',
+        'SmitheryTransport already started! If using Client class, note that connect() calls start() automatically.',
       );
     }
     if (this._closed) {
@@ -134,6 +134,26 @@ export class SmitheryConnectTransport implements Transport {
     this._started = true;
   }
 
+  /**
+   * Lazily ensures a namespace is available.
+   * If no namespace was provided, uses the first existing namespace or creates a new one.
+   */
+  private async _ensureNamespace(): Promise<string> {
+    if (this._namespace) {
+      return this._namespace;
+    }
+
+    const { namespaces } = await this._client.namespaces.list();
+    if (namespaces.length > 0) {
+      this._namespace = namespaces[0]!.name;
+    } else {
+      // Create a new namespace with server-generated name
+      const { name } = await this._client.namespaces.create();
+      this._namespace = name;
+    }
+    return this._namespace;
+  }
+
   /**
    * Lazily ensures the Smithery Connect connection exists.
    * Called on first message to defer network IO until actually needed.
@@ -143,17 +163,19 @@ export class SmitheryConnectTransport implements Transport {
       return;
     }
 
+    const namespace = await this._ensureNamespace();
+
     if (this._connectionId) {
-      // Connection ID provided: try to retrieve, or create if mcpUrl is provided
+      // Connection ID provided: try to get, or create if mcpUrl is provided
       try {
-        this._connection = await this._client.beta.connect.connections.retrieve(this._connectionId, {
-          namespace: this._namespace,
+        this._connection = await this._client.beta.connect.connections.get(this._connectionId, {
+          namespace,
         });
       } catch (error) {
         // If connection doesn't exist and we have mcpUrl, create it with the specified ID
         if (this._mcpUrl) {
           this._connection = await this._client.beta.connect.connections.set(this._connectionId, {
-            namespace: this._namespace,
+            namespace,
             mcpUrl: this._mcpUrl,
           });
         } else {
@@ -163,7 +185,7 @@ export class SmitheryConnectTransport implements Transport {
     } else {
       // No connection ID: create a new connection with auto-generated ID
       // mcpUrl is guaranteed to be present (validated in constructor)
-      this._connection = await this._client.beta.connect.connections.create(this._namespace, {
+      this._connection = await this._client.beta.connect.connections.create(namespace, {
         mcpUrl: this._mcpUrl!,
       });
       // Store the generated connection ID for subsequent RPC calls
@@ -221,8 +243,9 @@ export class SmitheryConnectTransport implements Transport {
 
     try {
       // Build the RPC call params, only including id if it's defined
+      // _namespace is guaranteed to be set after _ensureConnection
       const rpcParams: Parameters<typeof this._client.beta.connect.rpc.call>[1] = {
-        namespace: this._namespace,
+        namespace: this._namespace!,
         jsonrpc: '2.0',
         method: message.method,
       };

package/src/resources/beta/connect/connect.ts

@@ -7,7 +7,8 @@ import {
   ConnectionCreateParams,
   ConnectionDeleteParams,
   ConnectionDeleteResponse,
-  ConnectionRetrieveParams,
+  ConnectionGetParams,
+  ConnectionListParams,
   ConnectionSetParams,
   Connections,
   ConnectionsListResponse,
@@ -32,8 +33,9 @@ export declare namespace Connect {
     type CreateConnectionRequest as CreateConnectionRequest,
     type ConnectionDeleteResponse as ConnectionDeleteResponse,
     type ConnectionCreateParams as ConnectionCreateParams,
-    type ConnectionRetrieveParams as ConnectionRetrieveParams,
+    type ConnectionListParams as ConnectionListParams,
     type ConnectionDeleteParams as ConnectionDeleteParams,
+    type ConnectionGetParams as ConnectionGetParams,
     type ConnectionSetParams as ConnectionSetParams,
   };
 

package/src/resources/beta/connect/connections.ts

@@ -24,30 +24,8 @@ export class Connections extends APIResource {
   }
 
   /**
-   * Get details for a specific connection. Requires service token with
-   * connections:read scope.
-   *
-   * @example
-   * ```ts
-   * const connection =
-   *   await client.beta.connect.connections.retrieve(
-   *     'connectionId',
-   *     { namespace: 'namespace' },
-   *   );
-   * ```
-   */
-  retrieve(
-    connectionID: string,
-    params: ConnectionRetrieveParams,
-    options?: RequestOptions,
-  ): APIPromise<Connection> {
-    const { namespace } = params;
-    return this._client.get(path`/connect/${namespace}/${connectionID}`, options);
-  }
-
-  /**
-   * List all connections in a namespace. Requires service token with
-   * connections:read scope.
+   * List all connections in a namespace. Supports filtering by metadata using
+   * `metadata.{key}={value}` query params (e.g., `metadata.userId=alice`).
    *
    * @example
    * ```ts
@@ -55,8 +33,12 @@ export class Connections extends APIResource {
    *   await client.beta.connect.connections.list('namespace');
    * ```
    */
-  list(namespace: string, options?: RequestOptions): APIPromise<ConnectionsListResponse> {
-    return this._client.get(path`/connect/${namespace}`, options);
+  list(
+    namespace: string,
+    query: ConnectionListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ConnectionsListResponse> {
+    return this._client.get(path`/connect/${namespace}`, { query, ...options });
   }
 
   /**
@@ -81,6 +63,24 @@ export class Connections extends APIResource {
     return this._client.delete(path`/connect/${namespace}/${connectionID}`, options);
   }
 
+  /**
+   * Get details for a specific connection. Requires service token with
+   * connections:read scope.
+   *
+   * @example
+   * ```ts
+   * const connection =
+   *   await client.beta.connect.connections.get(
+   *     'connectionId',
+   *     { namespace: 'namespace' },
+   *   );
+   * ```
+   */
+  get(connectionID: string, params: ConnectionGetParams, options?: RequestOptions): APIPromise<Connection> {
+    const { namespace } = params;
+    return this._client.get(path`/connect/${namespace}/${connectionID}`, options);
+  }
+
   /**
    * Create a new MCP connection with the given ID. Returns 409 if connection already
    * exists - delete it first to recreate. Requires API key and namespace ownership.
@@ -137,9 +137,9 @@ export interface Connection {
    * Connection status after initialization (only returned on create)
    */
   status?:
-    | Connection.ConnectConnectionStatusConnected
-    | Connection.ConnectConnectionStatusAuthRequired
-    | Connection.ConnectConnectionStatusError;
+    | Connection.ConnectionStatusConnected
+    | Connection.ConnectionStatusAuthRequired
+    | Connection.ConnectionStatusError;
 }
 
 export namespace Connection {
@@ -172,11 +172,11 @@ export namespace Connection {
     }
   }
 
-  export interface ConnectConnectionStatusConnected {
+  export interface ConnectionStatusConnected {
     state: 'connected';
   }
 
-  export interface ConnectConnectionStatusAuthRequired {
+  export interface ConnectionStatusAuthRequired {
     state: 'auth_required';
 
     /**
@@ -185,7 +185,7 @@ export namespace Connection {
     authorizationUrl?: string;
   }
 
-  export interface ConnectConnectionStatusError {
+  export interface ConnectionStatusError {
     /**
      * Error message
      */
@@ -254,14 +254,31 @@ export interface ConnectionCreateParams {
   name?: string;
 }
 
-export interface ConnectionRetrieveParams {
-  namespace: string;
+export interface ConnectionListParams {
+  /**
+   * Pagination cursor from previous response's nextCursor
+   */
+  cursor?: string;
+
+  /**
+   * Maximum number of items to return (default 100, max 100)
+   */
+  limit?: number;
+
+  /**
+   * Filter by exact connection name
+   */
+  name?: string;
 }
 
 export interface ConnectionDeleteParams {
   namespace: string;
 }
 
+export interface ConnectionGetParams {
+  namespace: string;
+}
+
 export interface ConnectionSetParams {
   /**
    * Path param
@@ -297,8 +314,9 @@ export declare namespace Connections {
     type CreateConnectionRequest as CreateConnectionRequest,
     type ConnectionDeleteResponse as ConnectionDeleteResponse,
     type ConnectionCreateParams as ConnectionCreateParams,
-    type ConnectionRetrieveParams as ConnectionRetrieveParams,
+    type ConnectionListParams as ConnectionListParams,
     type ConnectionDeleteParams as ConnectionDeleteParams,
+    type ConnectionGetParams as ConnectionGetParams,
     type ConnectionSetParams as ConnectionSetParams,
   };
 }

package/src/resources/beta/connect/index.ts

@@ -8,8 +8,9 @@ export {
   type CreateConnectionRequest,
   type ConnectionDeleteResponse,
   type ConnectionCreateParams,
-  type ConnectionRetrieveParams,
+  type ConnectionListParams,
   type ConnectionDeleteParams,
+  type ConnectionGetParams,
   type ConnectionSetParams,
 } from './connections';
 export { Rpc, type JsonRpcRequest, type JsonRpcResponse, type RpcCallParams } from './rpc';

package/src/resources/index.ts

@@ -6,16 +6,16 @@ export {
   Namespaces,
   type NamespaceCreateResponse,
   type NamespaceListResponse,
-  type NamespaceCreateParams,
+  type NamespaceSetResponse,
 } from './namespaces';
 export {
   Servers,
   type BuildConfig,
   type DeploymentTarget,
   type ProjectConfig,
-  type ServerRetrieveResponse,
   type ServerListResponse,
   type ServerDeleteResponse,
+  type ServerGetResponse,
   type ServerListParams,
   type ServerListResponsesSmitheryPage,
 } from './servers/servers';
@@ -25,5 +25,15 @@ export {
   type SkillListParams,
   type SkillListResponsesSkillsPage,
 } from './skills';
-export { Tokens, type CreateTokenRequest, type CreateTokenResponse, type TokenCreateParams } from './tokens';
+export {
+  Tokens,
+  type Action,
+  type Allow,
+  type ConnectionScope,
+  type CreateTokenRequest,
+  type CreateTokenResponse,
+  type ResourceScope,
+  type RpcScope,
+  type TokenCreateParams,
+} from './tokens';
 export { Uplink, type UplinkCreateTokenResponse } from './uplink';

package/src/resources/namespaces.ts

@@ -3,33 +3,31 @@
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
 
 export class Namespaces extends APIResource {
   /**
-   * Create a new namespace owned by the authenticated user
-   *
-   * @example
-   * ```ts
-   * const namespace = await client.namespaces.create({
-   *   name: 'myorg',
-   * });
-   * ```
+   * Create a new namespace with a server-generated human-readable name, owned by the
+   * authenticated user
    */
-  create(body: NamespaceCreateParams, options?: RequestOptions): APIPromise<NamespaceCreateResponse> {
-    return this._client.put('/namespaces', { body, ...options });
+  create(options?: RequestOptions): APIPromise<NamespaceCreateResponse> {
+    return this._client.post('/namespaces', options);
   }
 
   /**
    * Get a list of all namespaces owned by the authenticated user
-   *
-   * @example
-   * ```ts
-   * const namespaces = await client.namespaces.list();
-   * ```
    */
   list(options?: RequestOptions): APIPromise<NamespaceListResponse> {
     return this._client.get('/namespaces', options);
   }
+
+  /**
+   * Create a new namespace with a user-specified name, owned by the authenticated
+   * user
+   */
+  set(name: string, options?: RequestOptions): APIPromise<NamespaceSetResponse> {
+    return this._client.put(path`/namespaces/${name}`, options);
+  }
 }
 
 export interface NamespaceCreateResponse {
@@ -50,7 +48,9 @@ export namespace NamespaceListResponse {
   }
 }
 
-export interface NamespaceCreateParams {
+export interface NamespaceSetResponse {
+  createdAt: string;
+
   name: string;
 }
 
@@ -58,6 +58,6 @@ export declare namespace Namespaces {
   export {
     type NamespaceCreateResponse as NamespaceCreateResponse,
     type NamespaceListResponse as NamespaceListResponse,
-    type NamespaceCreateParams as NamespaceCreateParams,
+    type NamespaceSetResponse as NamespaceSetResponse,
   };
 }

package/src/resources/servers/deployments.ts

@@ -8,18 +8,6 @@ import { multipartFormRequestOptions } from '../../internal/uploads';
 import { path } from '../../internal/utils/path';
 
 export class Deployments extends APIResource {
-  /**
-   * Get deployment status
-   */
-  retrieve(
-    id: string,
-    params: DeploymentRetrieveParams,
-    options?: RequestOptions,
-  ): APIPromise<DeploymentRetrieveResponse> {
-    const { qualifiedName } = params;
-    return this._client.get(path`/servers/${qualifiedName}/deployments/${id}`, options);
-  }
-
   /**
    * List deployments for a server
    */
@@ -41,6 +29,14 @@ export class Deployments extends APIResource {
     );
   }
 
+  /**
+   * Get deployment status
+   */
+  get(id: string, params: DeploymentGetParams, options?: RequestOptions): APIPromise<DeploymentGetResponse> {
+    const { qualifiedName } = params;
+    return this._client.get(path`/servers/${qualifiedName}/deployments/${id}`, options);
+  }
+
   /**
    * Use id='latest' to resume the most recent deployment
    */
@@ -72,6 +68,8 @@ export interface ExternalDeployPayload {
   upstreamUrl: string;
 
   configSchema?: { [key: string]: unknown };
+
+  scanCredentials?: { [key: string]: string };
 }
 
 export interface HostedDeployPayload {
@@ -302,7 +300,33 @@ export namespace StdioDeployPayload {
   }
 }
 
-export interface DeploymentRetrieveResponse {
+export type DeploymentListResponse = Array<DeploymentListResponse.DeploymentListResponseItem>;
+
+export namespace DeploymentListResponse {
+  export interface DeploymentListResponseItem {
+    id: string;
+
+    createdAt: string;
+
+    status: string;
+
+    updatedAt: string;
+
+    mcpUrl?: string;
+  }
+}
+
+export interface DeploymentDeployResponse {
+  deploymentId: string;
+
+  mcpUrl: string;
+
+  status: string;
+
+  warnings?: Array<string>;
+}
+
+export interface DeploymentGetResponse {
   id: string;
 
   createdAt: string;
@@ -311,12 +335,12 @@ export interface DeploymentRetrieveResponse {
 
   updatedAt: string;
 
-  logs?: Array<DeploymentRetrieveResponse.Log>;
+  logs?: Array<DeploymentGetResponse.Log>;
 
   mcpUrl?: string;
 }
 
-export namespace DeploymentRetrieveResponse {
+export namespace DeploymentGetResponse {
   export interface Log {
     level: string;
 
@@ -336,42 +360,12 @@ export namespace DeploymentRetrieveResponse {
   }
 }
 
-export type DeploymentListResponse = Array<DeploymentListResponse.DeploymentListResponseItem>;
-
-export namespace DeploymentListResponse {
-  export interface DeploymentListResponseItem {
-    id: string;
-
-    createdAt: string;
-
-    status: string;
-
-    updatedAt: string;
-
-    mcpUrl?: string;
-  }
-}
-
-export interface DeploymentDeployResponse {
-  deploymentId: string;
-
-  mcpUrl: string;
-
-  status: string;
-
-  warnings?: Array<string>;
-}
-
 export interface DeploymentResumeResponse {
   deploymentId: string;
 
   status: string;
 }
 
-export interface DeploymentRetrieveParams {
-  qualifiedName: string;
-}
-
 export interface DeploymentDeployParams {
   /**
    * JSON-encoded deployment payload. See DeployPayload schema for structure.
@@ -394,6 +388,10 @@ export interface DeploymentDeployParams {
   sourcemap?: Uploadable;
 }
 
+export interface DeploymentGetParams {
+  qualifiedName: string;
+}
+
 export interface DeploymentResumeParams {
   qualifiedName: string;
 }
@@ -405,12 +403,12 @@ export declare namespace Deployments {
     type HostedDeployPayload as HostedDeployPayload,
     type ServerCard as ServerCard,
     type StdioDeployPayload as StdioDeployPayload,
-    type DeploymentRetrieveResponse as DeploymentRetrieveResponse,
     type DeploymentListResponse as DeploymentListResponse,
     type DeploymentDeployResponse as DeploymentDeployResponse,
+    type DeploymentGetResponse as DeploymentGetResponse,
     type DeploymentResumeResponse as DeploymentResumeResponse,
-    type DeploymentRetrieveParams as DeploymentRetrieveParams,
     type DeploymentDeployParams as DeploymentDeployParams,
+    type DeploymentGetParams as DeploymentGetParams,
     type DeploymentResumeParams as DeploymentResumeParams,
   };
 }

package/src/resources/servers/index.ts

@@ -7,12 +7,12 @@ export {
   type HostedDeployPayload,
   type ServerCard,
   type StdioDeployPayload,
-  type DeploymentRetrieveResponse,
   type DeploymentListResponse,
   type DeploymentDeployResponse,
+  type DeploymentGetResponse,
   type DeploymentResumeResponse,
-  type DeploymentRetrieveParams,
   type DeploymentDeployParams,
+  type DeploymentGetParams,
   type DeploymentResumeParams,
 } from './deployments';
 export { Logs, type LogListResponse, type LogListParams } from './logs';
@@ -29,9 +29,9 @@ export {
   type BuildConfig,
   type DeploymentTarget,
   type ProjectConfig,
-  type ServerRetrieveResponse,
   type ServerListResponse,
   type ServerDeleteResponse,
+  type ServerGetResponse,
   type ServerListParams,
   type ServerListResponsesSmitheryPage,
 } from './servers';