@ubuligan/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jsznpm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ListToolsResult, CallToolResult, ListResourcesResult, ReadResourceResult, ListPromptsResult, GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+import { TransportConfig, AuthConfig, RetryOptions, Logger, LogLevel } from '@ubuligan/shared';
+export { AuthConfig, HttpTransportConfig, LogLevel, Logger, RetryOptions, StdioTransportConfig, TransportConfig } from '@ubuligan/shared';
+
+interface MCPClientOptions {
+    /** How to reach the server (stdio or Streamable HTTP). */
+    transport: TransportConfig;
+    /** Optional auth applied to HTTP transports. */
+    auth?: AuthConfig;
+    /** Retry policy applied to every request. Set `retries: 1` to disable. */
+    retry?: RetryOptions;
+    /** Provide a custom logger, or a level for the built-in console logger. */
+    logger?: Logger | LogLevel;
+    /** Client identity advertised to the server. */
+    name?: string;
+    version?: string;
+}
+/**
+ * A thin, ergonomic wrapper over the MCP SDK `Client`. Every request is wrapped
+ * with retry + logging; transport and auth are config-driven. The underlying
+ * SDK client is exposed as `.raw` for advanced use.
+ */
+declare class MCPClient {
+    readonly raw: Client;
+    private connected;
+    private readonly opts;
+    private readonly logger;
+    constructor(opts: MCPClientOptions);
+    connect(): Promise<this>;
+    close(): Promise<void>;
+    private run;
+    listTools(): Promise<ListToolsResult>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult>;
+    listResources(): Promise<ListResourcesResult>;
+    readResource(uri: string): Promise<ReadResourceResult>;
+    listPrompts(): Promise<ListPromptsResult>;
+    getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult>;
+}
+/** Create and connect an {@link MCPClient} in one call. */
+declare function createMCPClient(opts: MCPClientOptions): Promise<MCPClient>;
+
+export { MCPClient, type MCPClientOptions, createMCPClient, MCPClient as default };

package/dist/index.js

@@ -0,0 +1,103 @@
+// src/index.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  createConsoleLogger,
+  noopLogger,
+  withRetry
+} from "@ubuligan/shared";
+
+// src/transport.ts
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { resolveAuthHeaders } from "@ubuligan/shared";
+async function buildTransport(config, auth) {
+  if (config.type === "stdio") {
+    return new StdioClientTransport({
+      command: config.command,
+      args: config.args,
+      cwd: config.cwd,
+      env: { ...process.env, ...config.env ?? {} }
+    });
+  }
+  const headers = { ...await resolveAuthHeaders(auth), ...config.headers ?? {} };
+  return new StreamableHTTPClientTransport(new URL(config.url), {
+    requestInit: { headers }
+  });
+}
+
+// src/index.ts
+function resolveLogger(logger) {
+  if (!logger) return noopLogger;
+  if (typeof logger === "string") return createConsoleLogger(logger);
+  return logger;
+}
+var MCPClient = class {
+  raw;
+  connected = false;
+  opts;
+  logger;
+  constructor(opts) {
+    this.opts = opts;
+    this.logger = resolveLogger(opts.logger);
+    this.raw = new Client({
+      name: opts.name ?? "mcp-toolkit-client",
+      version: opts.version ?? "0.1.0"
+    });
+  }
+  async connect() {
+    if (this.connected) return this;
+    const transport = await buildTransport(this.opts.transport, this.opts.auth);
+    this.logger.info("connecting", { transport: this.opts.transport.type });
+    await this.raw.connect(transport);
+    this.connected = true;
+    this.logger.info("connected");
+    return this;
+  }
+  async close() {
+    if (!this.connected) return;
+    await this.raw.close();
+    this.connected = false;
+    this.logger.info("closed");
+  }
+  run(label, fn) {
+    if (!this.connected) {
+      throw new Error("MCPClient is not connected \xE2\u20AC\u201D call connect() first");
+    }
+    return withRetry(fn, this.opts.retry, this.logger, label);
+  }
+  listTools() {
+    return this.run("listTools", () => this.raw.listTools());
+  }
+  callTool(name, args) {
+    return this.run(
+      `callTool:${name}`,
+      () => this.raw.callTool({ name, arguments: args ?? {} })
+    );
+  }
+  listResources() {
+    return this.run("listResources", () => this.raw.listResources());
+  }
+  readResource(uri) {
+    return this.run(`readResource:${uri}`, () => this.raw.readResource({ uri }));
+  }
+  listPrompts() {
+    return this.run("listPrompts", () => this.raw.listPrompts());
+  }
+  getPrompt(name, args) {
+    return this.run(
+      `getPrompt:${name}`,
+      () => this.raw.getPrompt({ name, arguments: args ?? {} })
+    );
+  }
+};
+async function createMCPClient(opts) {
+  const client = new MCPClient(opts);
+  await client.connect();
+  return client;
+}
+export {
+  MCPClient,
+  createMCPClient,
+  MCPClient as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/transport.ts"],"sourcesContent":["import { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\r\nimport type {\r\n  CallToolResult,\r\n  GetPromptResult,\r\n  ListPromptsResult,\r\n  ListResourcesResult,\r\n  ListToolsResult,\r\n  ReadResourceResult,\r\n} from \"@modelcontextprotocol/sdk/types.js\";\r\nimport {\r\n  createConsoleLogger,\r\n  noopLogger,\r\n  withRetry,\r\n  type AuthConfig,\r\n  type Logger,\r\n  type LogLevel,\r\n  type RetryOptions,\r\n  type TransportConfig,\r\n} from \"@ubuligan/shared\";\r\nimport { buildTransport } from \"./transport.js\";\r\n\r\nexport type {\r\n  AuthConfig,\r\n  HttpTransportConfig,\r\n  Logger,\r\n  LogLevel,\r\n  RetryOptions,\r\n  StdioTransportConfig,\r\n  TransportConfig,\r\n} from \"@ubuligan/shared\";\r\n\r\nexport interface MCPClientOptions {\r\n  /** How to reach the server (stdio or Streamable HTTP). */\r\n  transport: TransportConfig;\r\n  /** Optional auth applied to HTTP transports. */\r\n  auth?: AuthConfig;\r\n  /** Retry policy applied to every request. Set `retries: 1` to disable. */\r\n  retry?: RetryOptions;\r\n  /** Provide a custom logger, or a level for the built-in console logger. */\r\n  logger?: Logger | LogLevel;\r\n  /** Client identity advertised to the server. */\r\n  name?: string;\r\n  version?: string;\r\n}\r\n\r\nfunction resolveLogger(logger: MCPClientOptions[\"logger\"]): Logger {\r\n  if (!logger) return noopLogger;\r\n  if (typeof logger === \"string\") return createConsoleLogger(logger);\r\n  return logger;\r\n}\r\n\r\n/**\r\n * A thin, ergonomic wrapper over the MCP SDK `Client`. Every request is wrapped\r\n * with retry + logging; transport and auth are config-driven. The underlying\r\n * SDK client is exposed as `.raw` for advanced use.\r\n */\r\nexport class MCPClient {\r\n  readonly raw: Client;\r\n  private connected = false;\r\n  private readonly opts: MCPClientOptions;\r\n  private readonly logger: Logger;\r\n\r\n  constructor(opts: MCPClientOptions) {\r\n    this.opts = opts;\r\n    this.logger = resolveLogger(opts.logger);\r\n    this.raw = new Client({\r\n      name: opts.name ?? \"mcp-toolkit-client\",\r\n      version: opts.version ?? \"0.1.0\",\r\n    });\r\n  }\r\n\r\n  async connect(): Promise<this> {\r\n    if (this.connected) return this;\r\n    const transport = await buildTransport(this.opts.transport, this.opts.auth);\r\n    this.logger.info(\"connecting\", { transport: this.opts.transport.type });\r\n    await this.raw.connect(transport);\r\n    this.connected = true;\r\n    this.logger.info(\"connected\");\r\n    return this;\r\n  }\r\n\r\n  async close(): Promise<void> {\r\n    if (!this.connected) return;\r\n    await this.raw.close();\r\n    this.connected = false;\r\n    this.logger.info(\"closed\");\r\n  }\r\n\r\n  private run<T>(label: string, fn: () => Promise<T>): Promise<T> {\r\n    if (!this.connected) {\r\n      throw new Error(\"MCPClient is not connected — call connect() first\");\r\n    }\r\n    return withRetry(fn, this.opts.retry, this.logger, label);\r\n  }\r\n\r\n  listTools(): Promise<ListToolsResult> {\r\n    return this.run(\"listTools\", () => this.raw.listTools());\r\n  }\r\n\r\n  callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult> {\r\n    return this.run(`callTool:${name}`, () =>\r\n      this.raw.callTool({ name, arguments: args ?? {} }),\r\n    ) as Promise<CallToolResult>;\r\n  }\r\n\r\n  listResources(): Promise<ListResourcesResult> {\r\n    return this.run(\"listResources\", () => this.raw.listResources());\r\n  }\r\n\r\n  readResource(uri: string): Promise<ReadResourceResult> {\r\n    return this.run(`readResource:${uri}`, () => this.raw.readResource({ uri }));\r\n  }\r\n\r\n  listPrompts(): Promise<ListPromptsResult> {\r\n    return this.run(\"listPrompts\", () => this.raw.listPrompts());\r\n  }\r\n\r\n  getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult> {\r\n    return this.run(`getPrompt:${name}`, () =>\r\n      this.raw.getPrompt({ name, arguments: args ?? {} }),\r\n    );\r\n  }\r\n}\r\n\r\n/** Create and connect an {@link MCPClient} in one call. */\r\nexport async function createMCPClient(opts: MCPClientOptions): Promise<MCPClient> {\r\n  const client = new MCPClient(opts);\r\n  await client.connect();\r\n  return client;\r\n}\r\n\r\nexport { MCPClient as default };\r\n","import { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\r\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\r\nimport type { Transport } from \"@modelcontextprotocol/sdk/shared/transport.js\";\r\nimport { resolveAuthHeaders, type AuthConfig, type TransportConfig } from \"@ubuligan/shared\";\r\n\r\n/**\r\n * Build an MCP SDK transport from a plain config object. stdio is for local\r\n * servers; http uses Streamable HTTP (the production transport — SSE is\r\n * deprecated upstream).\r\n */\r\nexport async function buildTransport(config: TransportConfig, auth?: AuthConfig): Promise<Transport> {\r\n  if (config.type === \"stdio\") {\r\n    return new StdioClientTransport({\r\n      command: config.command,\r\n      args: config.args,\r\n      cwd: config.cwd,\r\n      env: { ...(process.env as Record<string, string>), ...(config.env ?? {}) },\r\n    });\r\n  }\r\n\r\n  const headers = { ...(await resolveAuthHeaders(auth)), ...(config.headers ?? {}) };\r\n  return new StreamableHTTPClientTransport(new URL(config.url), {\r\n    requestInit: { headers },\r\n  });\r\n}\r\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ubuligan/client",
+  "version": "0.1.0",
+  "description": "Thin DX layer over the MCP SDK Client: transport helpers, auth, retry and logging",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@ubuligan/shared": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "tsup": "^8.3.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "jsznpm",
+  "homepage": "https://github.com/jsznpm/create-mcp-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/jsznpm/create-mcp-toolkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsznpm/create-mcp-toolkit.git",
+    "directory": "packages/client"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "llm",
+    "client",
+    "sdk"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}