@wice24/tars-sdk 0.2.0 → 0.2.3

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, AgentVersion, ClientTool, CreateAgentInput, FileMeta, McpCredentialInput, McpCredentialStatus, ReasoningConfig, SessionEvent, ModelInfo, SessionInfo, SessionListItem, UpdateAgentInput, UploadFileInput, UsageSummary, SessionUsageRow, DailyUsageRow, McpServer, Skill, SkillVersion, ApiKeyInfo, ClientIdentity, ClientRole, PlatformStats, Tenant } from './types.js';
+import type { Agent, AgentVersion, ClientTool, CreateAgentInput, FileMeta, ListMcpToolsInput, McpCredentialInput, McpCredentialStatus, McpServerTools, ReasoningConfig, SessionEvent, ModelInfo, SessionInfo, SessionListItem, UpdateAgentInput, UploadFileInput, UsageSummary, SessionUsageRow, DailyUsageRow, McpServer, Skill, SkillVersion, ApiKeyInfo, ClientIdentity, ClientRole, PlatformStats, Tenant } from './types.js';
 type ToolHandler = (input: any) => unknown | Promise<unknown>;
 export * from './types.js';
 export declare class TarsApiError extends Error {
@@ -124,6 +124,20 @@ export declare class TarsClient {
             ok: boolean;
         }>;
     };
+    readonly mcp: {
+        /**
+         * Dial an MCP server once with the stored credential, list its tools, hang
+         * up — no session, nothing journaled. The source of truth for writing a
+         * `tools` / `blocked_tools` policy: what the server offers NOW, not what a
+         * registry says. Throws `TarsApiError` 404 `missing_credential` when
+         * `auth: 'required'` and no credential is stored for the end user or the
+         * tenant (none stored, or its refresh failed), 502 with the turn-time code
+         * (`mcp_authentication_failed_error` / `mcp_connection_failed_error`) when
+         * the dial fails or times out (15 s), and 503 `internal_error` when TARS's
+         * own credential store is unavailable.
+         */
+        listTools: (input: ListMcpToolsInput) => Promise<McpServerTools>;
+    };
     readonly skills: {
         create: (input: {
             slug: string;

package/dist/index.js

@@ -155,6 +155,30 @@ export class TarsClient {
             return this.request('DELETE', `/v1/mcp-credentials?${params}`);
         },
     };
+    // ── MCP servers ──────────────────────────────────────────────
+    mcp = {
+        /**
+         * Dial an MCP server once with the stored credential, list its tools, hang
+         * up — no session, nothing journaled. The source of truth for writing a
+         * `tools` / `blocked_tools` policy: what the server offers NOW, not what a
+         * registry says. Throws `TarsApiError` 404 `missing_credential` when
+         * `auth: 'required'` and no credential is stored for the end user or the
+         * tenant (none stored, or its refresh failed), 502 with the turn-time code
+         * (`mcp_authentication_failed_error` / `mcp_connection_failed_error`) when
+         * the dial fails or times out (15 s), and 503 `internal_error` when TARS's
+         * own credential store is unavailable.
+         */
+        listTools: (input) => {
+            const params = new URLSearchParams({ name: input.name, url: input.url });
+            if (input.transport)
+                params.set('transport', input.transport);
+            if (input.auth)
+                params.set('auth', input.auth);
+            if (input.endUserId)
+                params.set('end_user_id', input.endUserId);
+            return this.request('GET', `/v1/mcp-servers/tools?${params}`);
+        },
+    };
     // ── skills ───────────────────────────────────────────────────
     // Versioned skill bundles (zip with SKILL.md at root), pinned per agent.
     skills = {

package/dist/types.d.ts

@@ -83,9 +83,13 @@ export type SessionEvent = {
     type: 'turn_end';
     reason: 'completed' | 'interrupted' | 'error';
     usage?: {
+        /** UNCACHED input tokens only. Cache reads and writes are reported
+         *  separately below, so the full prompt is the sum of all three. */
         inputTokens?: number;
         outputTokens?: number;
+        /** Input tokens served from the provider's prompt cache. */
         cacheReadTokens?: number;
+        /** Input tokens written to the provider's prompt cache. */
         cacheWriteTokens?: number;
     };
 });
@@ -105,6 +109,20 @@ export interface McpServer {
     url: string;
     transport: 'http' | 'sse';
     auth: 'none' | 'required';
+    /**
+     * Expose only these of the server's tools to the model (its own names, as
+     * the server lists them — not the `server__tool` prefixed form). Omitted or
+     * null = every tool. Names the server doesn't offer are ignored. Non-empty,
+     * ≤256 entries, no duplicates. Mutually exclusive with `blocked_tools`.
+     */
+    tools?: string[] | null;
+    /**
+     * Hide these of the server's tools from the model and expose every other
+     * one — the complement of `tools`, for a connector that is on by default
+     * and needs a few tools removed without naming the whole inventory. Same
+     * validation as `tools`; setting both is a `validation_error`.
+     */
+    blocked_tools?: string[] | null;
 }
 export interface ClientTool<I = any> {
     name: string;
@@ -246,6 +264,28 @@ export interface McpCredentialStatus {
     expires_at: string | null;
     updated_at: string;
 }
+/** How `mcp.listTools` names the server: the same fields a declaration
+ *  carries (so the credential lookup and the dial match a turn's), plus whose
+ *  credential to use. `transport` defaults to `'http'`, `auth` to `'none'`. */
+export interface ListMcpToolsInput {
+    name: string;
+    url: string;
+    transport?: 'http' | 'sse';
+    auth?: 'none' | 'required';
+    /** Resolve this end user's credential first, then the tenant-level one;
+     *  omit for tenant-level only. Only read when `auth` is `'required'`. */
+    endUserId?: string;
+}
+/** One tool as the server lists it. `description` is capped at 500
+ *  characters (an ellipsis marks a cut); `null` when the server gave none. */
+export interface McpToolInfo {
+    name: string;
+    description: string | null;
+}
+export interface McpServerTools {
+    server: string;
+    tools: McpToolInfo[];
+}
 export interface AgentVersion {
     version: number;
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wice24/tars-sdk",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Client SDK for TARS — the self-hosted managed-agents platform (sessions, streaming turns, client tools, MCP credentials, skills, files, usage, tenant administration)",
   "type": "module",
   "exports": {