@tangle-network/tcloud 0.4.12 → 0.4.14

package/README.md

@@ -1,6 +1,6 @@
 # tcloud
 
-TypeScript SDK and CLI for [Tangle AI Cloud](https://router.tangle.tools) — decentralized LLM inference with operator routing, reputation-based selection, and anonymous payments via ShieldedCredits.
+TypeScript SDK and CLI for [Tangle Router](https://router.tangle.tools): model routing, sandbox-backed agent calls, operator routing, and anonymous payments via ShieldedCredits.
 
 Zero framework dependencies. Pure `fetch` + SSE. Works in Node.js, Deno, Bun, and edge runtimes.
 
@@ -37,21 +37,23 @@ Zero framework dependencies. Pure `fetch` + SSE. Works in Node.js, Deno, Bun, an
 ## Installation
 
 ```bash
-npm install tcloud
+npm install @tangle-network/tcloud
 ```
 
 Or run the CLI directly:
 
 ```bash
-npx tcloud chat "What is Tangle?"
+npx @tangle-network/tcloud chat "What is Tangle?"
 ```
 
+Do not install unscoped `tcloud`. It is unrelated to Tangle.
+
 ## SDK
 
 ### Quick Start
 
 ```ts
-import { TCloud } from 'tcloud'
+import { TCloud } from '@tangle-network/tcloud'
 
 // Set model at client creation — explicit and consistent.
 const client = new TCloud({
@@ -159,7 +161,7 @@ console.log(completion.choices[0].message.content)
 Anonymous inference with no API key. Uses EIP-712 SpendAuth signatures — the operator verifies payment without learning your identity.
 
 ```ts
-import { TCloud } from 'tcloud'
+import { TCloud } from '@tangle-network/tcloud'
 
 const client = TCloud.shielded()
 const answer = await client.ask('Hello from the shadows')
@@ -361,10 +363,10 @@ tcloud auth status             # Check current auth
 ### Chat
 
 ```bash
-tcloud chat "Explain zero-knowledge proofs"
-tcloud chat -m meta-llama/llama-4-maverick "Hello"
-tcloud chat --private "Anonymous request"  # ShieldedCredits mode
-tcloud chat                                # Interactive mode
+npx @tangle-network/tcloud chat "Explain zero-knowledge proofs"
+npx @tangle-network/tcloud chat -m meta-llama/llama-4-maverick "Hello"
+npx @tangle-network/tcloud chat --private "Anonymous request"  # ShieldedCredits mode
+npx @tangle-network/tcloud chat                                # Interactive mode
 ```
 
 ### Browse
@@ -409,8 +411,8 @@ tcloud config --model gpt-4o-mini
 Environment variables:
 - `TANGLE_API_KEY` — API key (primary). One key for router + sandbox + all Tangle products.
 - `TCLOUD_API_KEY` — Deprecated alias, still honored for backwards compatibility.
-- `OPENAI_API_KEY` — Fallback API key (works because the API is OpenAI-compatible).
-- `TCLOUD_BASE_URL` — Override API base URL.
+- `TANGLE_ROUTER_URL` — Override CLI router URL.
+- `TCLOUD_API_URL` — Deprecated CLI router URL alias.
 
 ## OpenAI SDK Compatibility
 

package/dist/{chunk-THOMQXU5.js → chunk-26M4HGWE.js}

@@ -1,6 +1,6 @@
 import {
   TCloudClient
-} from "./chunk-U4VOGRVW.js";
+} from "./chunk-LUJXMUH5.js";
 
 // src/shielded.ts
 import { privateKeyToAccount } from "viem/accounts";

package/dist/chunk-GHMW4RWJ.js

@@ -0,0 +1,16 @@
+// src/version.ts
+import * as fs from "fs";
+function packageVersion() {
+  try {
+    const packageJson = JSON.parse(
+      fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8")
+    );
+    if (typeof packageJson.version === "string") return packageJson.version;
+  } catch {
+  }
+  return "0.0.0";
+}
+
+export {
+  packageVersion
+};

package/dist/{chunk-U4VOGRVW.js → chunk-LUJXMUH5.js}

@@ -998,6 +998,26 @@ var TCloudClient = class _TCloudClient {
       })
     });
   }
+  /** Run a multi-step deep-research task through Tangle Router billing and
+   *  provider routing (POST /v1/research). Slower and costlier than `search` —
+   *  the provider synthesizes an answer over many fetches. Pick depth with
+   *  `effort` (provider-specific vocabulary; see {@link ResearchOptions.effort}). */
+  async research(options) {
+    return this._request(`${this.baseURL}/research`, {
+      method: "POST",
+      body: JSON.stringify({
+        query: options.query,
+        provider: options.provider,
+        model: options.model,
+        effort: options.effort,
+        maxResults: options.maxResults,
+        searchRecency: options.searchRecency,
+        includeDomains: options.includeDomains,
+        excludeDomains: options.excludeDomains,
+        outputSchema: options.outputSchema
+      })
+    });
+  }
   /** Text-to-speech */
   async speech(options) {
     const res = await this._requestRaw(`${this.baseURL}/audio/speech`, {

package/dist/{chunk-UBUCUSCF.js → chunk-ZJCWJGPM.js}

@@ -4,10 +4,10 @@ import {
 import {
   createShieldedClient,
   generateWallet
-} from "./chunk-THOMQXU5.js";
+} from "./chunk-26M4HGWE.js";
 import {
   TCloudClient
-} from "./chunk-U4VOGRVW.js";
+} from "./chunk-LUJXMUH5.js";
 
 // src/index.ts
 import {

package/dist/cli.cjs

@@ -6,6 +6,13 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -23,6 +30,238 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// src/version.ts
+function packageVersion() {
+  try {
+    const packageJson = JSON.parse(
+      fs.readFileSync(new URL("../package.json", import_meta.url), "utf-8")
+    );
+    if (typeof packageJson.version === "string") return packageJson.version;
+  } catch {
+  }
+  return "0.0.0";
+}
+var fs, import_meta;
+var init_version = __esm({
+  "src/version.ts"() {
+    "use strict";
+    fs = __toESM(require("fs"), 1);
+    import_meta = {};
+  }
+});
+
+// src/mcp.ts
+var mcp_exports = {};
+__export(mcp_exports, {
+  runMcpServer: () => runMcpServer
+});
+function optionalMaxResults(value) {
+  if (value == null) return void 0;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : void 0;
+}
+function requireEnum(value, allowed, label) {
+  if (value == null) return void 0;
+  if (typeof value !== "string" || !allowed.has(value)) {
+    throw new InvalidParams(`invalid ${label}: ${String(value)}`);
+  }
+  return value;
+}
+function optionalDomains(value) {
+  if (!Array.isArray(value)) return void 0;
+  const domains = value.filter((d) => typeof d === "string");
+  return domains.length ? domains : void 0;
+}
+async function runMcpServer(client, opts = {}) {
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stdout;
+  const rl = readline.createInterface({ input });
+  const send = (msg) => {
+    output.write(`${JSON.stringify(msg)}
+`);
+  };
+  const ok = (id, result) => send({ jsonrpc: "2.0", id, result });
+  const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+  const toolError = (id, message) => ok(id, { content: [{ type: "text", text: message }], isError: true });
+  process.stderr.write("tcloud mcp: web_search + deep_research server ready (stdio)\n");
+  async function handleRequest(req) {
+    const { id, method, params } = req;
+    try {
+      if (method === "initialize") {
+        const requested = params?.protocolVersion ?? DEFAULT_PROTOCOL_VERSION;
+        const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.has(requested) ? requested : DEFAULT_PROTOCOL_VERSION;
+        ok(id, {
+          protocolVersion,
+          capabilities: { tools: {} },
+          serverInfo: { name: "tangle-tcloud", version: packageVersion() }
+        });
+      } else if (method === "tools/list") {
+        ok(id, { tools: TOOLS });
+      } else if (method === "tools/call") {
+        const name = params?.name;
+        if (name === "web_search") {
+          await handleWebSearch(id, params?.arguments ?? {});
+        } else if (name === "deep_research") {
+          await handleDeepResearch(id, params?.arguments ?? {});
+        } else {
+          fail(id, -32602, `unknown tool: ${String(name)}`);
+        }
+      } else {
+        fail(id, -32601, `method not found: ${String(method)}`);
+      }
+    } catch (e) {
+      if (e instanceof InvalidParams) {
+        fail(id, -32602, e.message);
+      } else {
+        fail(id, -32603, e instanceof Error ? e.message : String(e));
+      }
+    }
+  }
+  async function handleWebSearch(id, args) {
+    const query = String(args.query ?? "").trim();
+    if (!query) {
+      fail(id, -32602, 'web_search requires a non-empty "query"');
+      return;
+    }
+    const provider = requireEnum(args.provider, SEARCH_PROVIDERS, "provider");
+    const searchRecency = requireEnum(args.recency, RECENCY_WINDOWS, "recency");
+    const maxResults = optionalMaxResults(args.maxResults);
+    const includeDomains = optionalDomains(args.includeDomains);
+    const excludeDomains = optionalDomains(args.excludeDomains);
+    try {
+      const resp = await client.search({
+        query,
+        ...provider ? { provider } : {},
+        ...maxResults != null ? { maxResults } : {},
+        ...searchRecency ? { searchRecency } : {},
+        ...includeDomains ? { includeDomains } : {},
+        ...excludeDomains ? { excludeDomains } : {}
+      });
+      const hits = resp.data ?? [];
+      const text = hits.length ? hits.map((h, i) => `${i + 1}. ${h.title}
+   ${h.url}${h.snippet ? `
+   ${h.snippet}` : ""}`).join("\n\n") : `No results for "${resp.query ?? query}".`;
+      ok(id, { content: [{ type: "text", text }] });
+    } catch (e) {
+      toolError(id, e instanceof Error ? e.message : String(e));
+    }
+  }
+  async function handleDeepResearch(id, args) {
+    const query = String(args.query ?? "").trim();
+    if (!query) {
+      fail(id, -32602, 'deep_research requires a non-empty "query"');
+      return;
+    }
+    const provider = requireEnum(args.provider, RESEARCH_PROVIDERS, "provider");
+    const searchRecency = requireEnum(args.searchRecency, RECENCY_WINDOWS, "searchRecency");
+    const maxResults = optionalMaxResults(args.maxResults);
+    const includeDomains = optionalDomains(args.includeDomains);
+    const excludeDomains = optionalDomains(args.excludeDomains);
+    try {
+      const resp = await client.research({
+        query,
+        ...provider ? { provider } : {},
+        ...typeof args.effort === "string" ? { effort: args.effort } : {},
+        ...maxResults != null ? { maxResults } : {},
+        ...searchRecency ? { searchRecency } : {},
+        ...includeDomains ? { includeDomains } : {},
+        ...excludeDomains ? { excludeDomains } : {},
+        ...args.outputSchema !== void 0 ? { outputSchema: args.outputSchema } : {}
+      });
+      const sources = resp.results ?? [];
+      const sourceList = sources.length ? `
+
+Sources:
+${sources.map((h, i) => `${i + 1}. ${h.title}
+   ${h.url}`).join("\n")}` : "";
+      const text = `${resp.answer ?? ""}${sourceList}`.trim() || `No research result for "${resp.query ?? query}".`;
+      ok(id, { content: [{ type: "text", text }] });
+    } catch (e) {
+      toolError(id, e instanceof Error ? e.message : String(e));
+    }
+  }
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let req;
+    try {
+      req = JSON.parse(trimmed);
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+      continue;
+    }
+    if (req.id === void 0 || req.id === null) continue;
+    void handleRequest(req);
+  }
+}
+var readline, SEARCH_PROVIDERS, RESEARCH_PROVIDERS, RECENCY_WINDOWS, SUPPORTED_PROTOCOL_VERSIONS, DEFAULT_PROTOCOL_VERSION, DOMAIN_FILTER_SCHEMA, TOOLS, InvalidParams;
+var init_mcp = __esm({
+  "src/mcp.ts"() {
+    "use strict";
+    readline = __toESM(require("readline"), 1);
+    init_version();
+    SEARCH_PROVIDERS = /* @__PURE__ */ new Set(["perplexity", "exa", "you", "parallel", "tavily", "brave"]);
+    RESEARCH_PROVIDERS = /* @__PURE__ */ new Set(["perplexity", "exa", "you", "parallel", "tavily"]);
+    RECENCY_WINDOWS = /* @__PURE__ */ new Set(["day", "week", "month", "year"]);
+    SUPPORTED_PROTOCOL_VERSIONS = /* @__PURE__ */ new Set(["2025-06-18", "2025-03-26"]);
+    DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+    DOMAIN_FILTER_SCHEMA = {
+      type: "array",
+      items: { type: "string" }
+    };
+    TOOLS = [
+      {
+        name: "web_search",
+        description: "Search the web via the Tangle router and return live results (title, url, snippet). Use it to find primary sources and to VERIFY that a citation (paper, PMID/DOI, patent, fact) actually exists before relying on it.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "The search query." },
+            provider: {
+              type: "string",
+              description: "Optional provider: exa | parallel | perplexity | tavily | brave | you."
+            },
+            maxResults: { type: "number", description: "Optional max number of results." },
+            recency: { type: "string", description: "Optional recency window: day | week | month | year." },
+            includeDomains: { ...DOMAIN_FILTER_SCHEMA, description: "Optional: restrict results to these domains." },
+            excludeDomains: { ...DOMAIN_FILTER_SCHEMA, description: "Optional: drop results from these domains." }
+          },
+          required: ["query"]
+        }
+      },
+      {
+        name: "deep_research",
+        description: 'Run a multi-step DEEP RESEARCH task via the Tangle router: the provider reads many sources and returns one synthesized answer with citations. Slower and costlier than web_search \u2014 use it for questions that need cross-source synthesis (current API/version landscapes, comparisons, "state of X"), not single-fact lookups.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "The research question." },
+            provider: {
+              type: "string",
+              description: "Optional provider: you | exa | perplexity | tavily | parallel."
+            },
+            effort: {
+              type: "string",
+              description: "Optional depth/cost dial (provider-specific): you lite|standard|deep|exhaustive \xB7 perplexity minimal|low|medium|high \xB7 exa deep-lite|deep|deep-reasoning \xB7 tavily mini|pro|auto \xB7 parallel lite|base|core|pro|ultra."
+            },
+            maxResults: { type: "number", description: "Optional max number of supporting sources." },
+            searchRecency: { type: "string", description: "Optional recency window: day | week | month | year." },
+            includeDomains: { ...DOMAIN_FILTER_SCHEMA, description: "Optional: restrict sources to these domains." },
+            excludeDomains: { ...DOMAIN_FILTER_SCHEMA, description: "Optional: drop sources from these domains." },
+            outputSchema: {
+              type: "object",
+              description: "Optional JSON schema requesting structured output from the provider."
+            }
+          },
+          required: ["query"]
+        }
+      }
+    ];
+    InvalidParams = class extends Error {
+    };
+  }
+});
+
 // src/cli.ts
 var import_commander = require("commander");
 
@@ -1026,6 +1265,26 @@ var TCloudClient = class _TCloudClient {
       })
     });
   }
+  /** Run a multi-step deep-research task through Tangle Router billing and
+   *  provider routing (POST /v1/research). Slower and costlier than `search` —
+   *  the provider synthesizes an answer over many fetches. Pick depth with
+   *  `effort` (provider-specific vocabulary; see {@link ResearchOptions.effort}). */
+  async research(options) {
+    return this._request(`${this.baseURL}/research`, {
+      method: "POST",
+      body: JSON.stringify({
+        query: options.query,
+        provider: options.provider,
+        model: options.model,
+        effort: options.effort,
+        maxResults: options.maxResults,
+        searchRecency: options.searchRecency,
+        includeDomains: options.includeDomains,
+        excludeDomains: options.excludeDomains,
+        outputSchema: options.outputSchema
+      })
+    });
+  }
   /** Text-to-speech */
   async speech(options) {
     const res = await this._requestRaw(`${this.baseURL}/audio/speech`, {
@@ -2007,40 +2266,40 @@ var TCloud = class _TCloud extends TCloudClient {
 };
 
 // src/cli.ts
-var fs = __toESM(require("fs"), 1);
+init_version();
+var fs2 = __toESM(require("fs"), 1);
 var path = __toESM(require("path"), 1);
-var readline = __toESM(require("readline"), 1);
+var readline2 = __toESM(require("readline"), 1);
 var import_child_process = require("child_process");
-var import_meta = {};
 var CONFIG_DIR = path.join(process.env.HOME || "~", ".tcloud");
 var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
 var WALLETS_FILE = path.join(CONFIG_DIR, "wallets.json");
 function ensureDir() {
-  if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  if (!fs2.existsSync(CONFIG_DIR)) fs2.mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
 }
 function loadConfig() {
   ensureDir();
-  const fileConfig = fs.existsSync(CONFIG_FILE) ? JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8")) : { apiUrl: "https://router.tangle.tools", defaultModel: "gpt-4o-mini", chainId: 3799 };
+  const fileConfig = fs2.existsSync(CONFIG_FILE) ? JSON.parse(fs2.readFileSync(CONFIG_FILE, "utf-8")) : { apiUrl: "https://router.tangle.tools", defaultModel: "gpt-4o-mini", chainId: 3799 };
   return {
     ...fileConfig,
     ...process.env.TANGLE_ROUTER_URL ? { apiUrl: process.env.TANGLE_ROUTER_URL.replace(/\/v1\/?$/, "") } : {},
     ...process.env.TCLOUD_API_URL ? { apiUrl: process.env.TCLOUD_API_URL.replace(/\/v1\/?$/, "") } : {},
-    ...process.env.TANGLE_API_KEY ? { apiKey: process.env.TANGLE_API_KEY } : {},
-    ...process.env.TCLOUD_API_KEY ? { apiKey: process.env.TCLOUD_API_KEY } : {}
+    ...process.env.TCLOUD_API_KEY ? { apiKey: process.env.TCLOUD_API_KEY } : {},
+    ...process.env.TANGLE_API_KEY ? { apiKey: process.env.TANGLE_API_KEY } : {}
   };
 }
 function saveConfig(c) {
   ensureDir();
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(c, null, 2), { mode: 384 });
+  fs2.writeFileSync(CONFIG_FILE, JSON.stringify(c, null, 2), { mode: 384 });
 }
 function loadWallets() {
   ensureDir();
-  if (fs.existsSync(WALLETS_FILE)) return JSON.parse(fs.readFileSync(WALLETS_FILE, "utf-8"));
+  if (fs2.existsSync(WALLETS_FILE)) return JSON.parse(fs2.readFileSync(WALLETS_FILE, "utf-8"));
   return [];
 }
 function saveWallets(w) {
   ensureDir();
-  fs.writeFileSync(WALLETS_FILE, JSON.stringify(w, null, 2), { mode: 384 });
+  fs2.writeFileSync(WALLETS_FILE, JSON.stringify(w, null, 2), { mode: 384 });
 }
 function getClient(opts) {
   const config = loadConfig();
@@ -2073,16 +2332,6 @@ function teeType(value) {
   if (!value) return void 0;
   return value.toLowerCase();
 }
-function packageVersion() {
-  try {
-    const packageJson = JSON.parse(
-      fs.readFileSync(new URL("../package.json", import_meta.url), "utf-8")
-    );
-    if (typeof packageJson.version === "string") return packageJson.version;
-  } catch {
-  }
-  return "0.0.0";
-}
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
@@ -2292,7 +2541,7 @@ program.command("chat").description("Chat with a model").argument("[message]", "
   const client = getClient({ private: opts.private });
   const model = opts.model || loadConfig().defaultModel;
   if (!message) {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
     console.log(`tcloud chat \u2014 ${model}${opts.private ? " (private)" : ""}
 Ctrl+C to exit.
 `);
@@ -2382,6 +2631,11 @@ program.command("search").description("Search the web").argument("<query>", "Sea
     process.exit(1);
   }
 });
+program.command("mcp").description('Run a Model Context Protocol (stdio) server exposing Tangle tools (web_search, deep_research). Mount with: { "command": ["tcloud", "mcp"] }').action(async () => {
+  const { runMcpServer: runMcpServer2 } = await Promise.resolve().then(() => (init_mcp(), mcp_exports));
+  const client = getClient();
+  await runMcpServer2(client);
+});
 program.command("image-generate").description("Generate an image").requiredOption("-p, --prompt <prompt>", "Prompt").option("-m, --model <model>", "Image model").option("--size <size>", "Output size").option("--quality <quality>", "Output quality").option("-n, --count <n>", "Number of images").option("--response-format <format>", "url or b64_json").option("--json", "Print raw JSON response").action(async (opts) => {
   const client = getClient();
   try {
@@ -2441,7 +2695,7 @@ program.command("speech").description("Generate speech audio").requiredOption("-
       model: opts.model,
       voice: opts.voice
     });
-    fs.writeFileSync(opts.output, Buffer.from(audio));
+    fs2.writeFileSync(opts.output, Buffer.from(audio));
     const result = { output: opts.output, bytes: audio.byteLength };
     if (opts.json) printJson(result);
     else console.log(opts.output);
@@ -2453,7 +2707,7 @@ program.command("speech").description("Generate speech audio").requiredOption("-
 program.command("transcribe").description("Transcribe an audio file").argument("<file>", "Audio file").option("-m, --model <model>", "Transcription model").option("--language <language>", "Language hint").option("--prompt <prompt>", "Prompt hint").option("--json", "Print raw JSON response").action(async (file, opts) => {
   const client = getClient();
   try {
-    const data = fs.readFileSync(file);
+    const data = fs2.readFileSync(file);
     const blob = new Blob([data]);
     const resp = await client.transcribe(blob, {
       model: opts.model,

package/dist/cli.js

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
 import {
   TCloud
-} from "./chunk-UBUCUSCF.js";
+} from "./chunk-ZJCWJGPM.js";
+import {
+  packageVersion
+} from "./chunk-GHMW4RWJ.js";
 import {
   TCloudSandbox
 } from "./chunk-GNACB23W.js";
 import {
   generateWallet
-} from "./chunk-THOMQXU5.js";
-import "./chunk-U4VOGRVW.js";
+} from "./chunk-26M4HGWE.js";
+import "./chunk-LUJXMUH5.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -29,8 +32,8 @@ function loadConfig() {
     ...fileConfig,
     ...process.env.TANGLE_ROUTER_URL ? { apiUrl: process.env.TANGLE_ROUTER_URL.replace(/\/v1\/?$/, "") } : {},
     ...process.env.TCLOUD_API_URL ? { apiUrl: process.env.TCLOUD_API_URL.replace(/\/v1\/?$/, "") } : {},
-    ...process.env.TANGLE_API_KEY ? { apiKey: process.env.TANGLE_API_KEY } : {},
-    ...process.env.TCLOUD_API_KEY ? { apiKey: process.env.TCLOUD_API_KEY } : {}
+    ...process.env.TCLOUD_API_KEY ? { apiKey: process.env.TCLOUD_API_KEY } : {},
+    ...process.env.TANGLE_API_KEY ? { apiKey: process.env.TANGLE_API_KEY } : {}
   };
 }
 function saveConfig(c) {
@@ -77,16 +80,6 @@ function teeType(value) {
   if (!value) return void 0;
   return value.toLowerCase();
 }
-function packageVersion() {
-  try {
-    const packageJson = JSON.parse(
-      fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8")
-    );
-    if (typeof packageJson.version === "string") return packageJson.version;
-  } catch {
-  }
-  return "0.0.0";
-}
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
@@ -386,6 +379,11 @@ program.command("search").description("Search the web").argument("<query>", "Sea
     process.exit(1);
   }
 });
+program.command("mcp").description('Run a Model Context Protocol (stdio) server exposing Tangle tools (web_search, deep_research). Mount with: { "command": ["tcloud", "mcp"] }').action(async () => {
+  const { runMcpServer } = await import("./mcp.js");
+  const client = getClient();
+  await runMcpServer(client);
+});
 program.command("image-generate").description("Generate an image").requiredOption("-p, --prompt <prompt>", "Prompt").option("-m, --model <model>", "Image model").option("--size <size>", "Output size").option("--quality <quality>", "Output quality").option("-n, --count <n>", "Number of images").option("--response-format <format>", "url or b64_json").option("--json", "Print raw JSON response").action(async (opts) => {
   const client = getClient();
   try {

package/dist/{client-CaD5Oal0.d.ts → client-CaPP4njg.d.cts}

@@ -186,6 +186,54 @@ interface SearchResponse {
         billing_units?: Record<string, unknown>;
     };
 }
+/** Providers served by the router's research API (POST /v1/research). Mirrors
+ *  SearchProvider minus `brave` (no research API). Each has its own `effort`
+ *  vocabulary — see ResearchOptions.effort. */
+type ResearchProvider = 'perplexity' | 'exa' | 'you' | 'parallel' | 'tavily';
+interface ResearchOptions {
+    query: string;
+    provider?: ResearchProvider;
+    /** Alias accepted by the Router for provider-compatible clients. */
+    model?: ResearchProvider;
+    /** Depth/cost dial, provider-specific:
+     *  perplexity minimal|low|medium|high · you lite|standard|deep|exhaustive ·
+     *  exa deep-lite|deep|deep-reasoning · tavily mini|pro|auto ·
+     *  parallel lite|base|core|pro|ultra. Omit for the provider default. */
+    effort?: string;
+    maxResults?: number;
+    searchRecency?: SearchRecency;
+    includeDomains?: string[];
+    excludeDomains?: string[];
+    /** Optional JSON schema requesting structured output from the provider. */
+    outputSchema?: unknown;
+}
+interface ResearchHit {
+    title: string;
+    url: string;
+    snippet?: string;
+    publishedAt?: string;
+    source?: string;
+}
+interface ResearchResponse {
+    id: string;
+    object: 'research.result' | string;
+    provider: ResearchProvider;
+    query: string;
+    /** The synthesized multi-step research answer. */
+    answer: string;
+    /** Supporting sources behind the answer. */
+    results: ResearchHit[];
+    citations: string[];
+    /** Present when an outputSchema was requested and the provider honored it. */
+    structured?: unknown;
+    usage?: {
+        upstream_cost?: number;
+        billed_cost?: number;
+        gross_margin?: number;
+        markup?: number;
+        billing_units?: Record<string, unknown>;
+    };
+}
 interface WebSearchPlugin {
     id: 'web';
     engine?: 'native' | 'exa' | 'parallel' | 'firecrawl';
@@ -1039,6 +1087,11 @@ declare class TCloudClient {
     rerank(options: RerankOptions): Promise<RerankResponse>;
     /** Search the web through Tangle Router billing and provider routing. */
     search(options: SearchOptions): Promise<SearchResponse>;
+    /** Run a multi-step deep-research task through Tangle Router billing and
+     *  provider routing (POST /v1/research). Slower and costlier than `search` —
+     *  the provider synthesizes an answer over many fetches. Pick depth with
+     *  `effort` (provider-specific vocabulary; see {@link ResearchOptions.effort}). */
+    research(options: ResearchOptions): Promise<ResearchResponse>;
     /** Text-to-speech */
     speech(options: {
         model?: string;
@@ -1356,4 +1409,4 @@ declare class TCloudError extends Error {
     constructor(status: number, message: string);
 }
 
-export { type SpendAuth as $, type ApiKeyInfo as A, type BatchJobResponse as B, type ChatCompletion as C, type RerankOptions as D, type EmbeddingOptions as E, type FineTuningJob as F, type GatewayOptions as G, type RerankResponse as H, type ImageEditAttachment as I, type JobEvent as J, type RetryConfig as K, type RotatingRoutingConfig as L, type Model as M, type RotationStats as N, type Operator as O, type PricingTier as P, type RoutingConfig as Q, type RotatingClientConfig as R, type RoutingStrategy as S, TCloudClient as T, type SandboxChatOptions as U, type SearchHit as V, type SearchOptions as W, type SearchProvider as X, type SearchRecency as Y, type SearchResponse as Z, type ShieldedConfig as _, type TCloudConfig as a, type SpendingLimits as a0, TCloudError as a1, type TierConfig as a2, type TranscriptionResponse as a3, type UpdateKeyOptions as a4, type VideoGenerateOptions as a5, type VideoResponse as a6, type WatchJobOptions as a7, type WebSearchPlugin as a8, type AvatarGenerateRequest as b, type AvatarGenerateResponse as c, type AvatarJobStatus as d, type AvatarResult as e, type BatchRequest as f, type BridgeOptions as g, BridgeSession as h, type ChatCompletionChunk as i, type ChatMessage as j, type ChatOptions as k, type ChatPlugin as l, type CompletionOptions as m, type CompletionResponse as n, type CreateKeyOptions as o, type CreatedKey as p, type CreditBalance as q, type EmbeddingResponse as r, type FineTuningJobOptions as s, type ImageEditOptions as t, type ImageGenerateOptions as u, type ImageResponse as v, type OperatorInfo as w, type PrivacyConfig as x, PrivateRouter as y, type PrivateRouterConfig as z };
+export { type SearchProvider as $, type ApiKeyInfo as A, type BatchJobResponse as B, type ChatCompletion as C, type RerankOptions as D, type EmbeddingOptions as E, type FineTuningJob as F, type GatewayOptions as G, type RerankResponse as H, type ImageEditAttachment as I, type JobEvent as J, type ResearchHit as K, type ResearchOptions as L, type Model as M, type ResearchProvider as N, type Operator as O, type PricingTier as P, type ResearchResponse as Q, type RotatingClientConfig as R, type RetryConfig as S, type TCloudConfig as T, type RotatingRoutingConfig as U, type RotationStats as V, type RoutingConfig as W, type RoutingStrategy as X, type SandboxChatOptions as Y, type SearchHit as Z, type SearchOptions as _, TCloudClient as a, type SearchRecency as a0, type SearchResponse as a1, type ShieldedConfig as a2, type SpendAuth as a3, type SpendingLimits as a4, TCloudError as a5, type TierConfig as a6, type TranscriptionResponse as a7, type UpdateKeyOptions as a8, type VideoGenerateOptions as a9, type VideoResponse as aa, type WatchJobOptions as ab, type WebSearchPlugin as ac, type AvatarGenerateRequest as b, type AvatarGenerateResponse as c, type AvatarJobStatus as d, type AvatarResult as e, type BatchRequest as f, type BridgeOptions as g, BridgeSession as h, type ChatCompletionChunk as i, type ChatMessage as j, type ChatOptions as k, type ChatPlugin as l, type CompletionOptions as m, type CompletionResponse as n, type CreateKeyOptions as o, type CreatedKey as p, type CreditBalance as q, type EmbeddingResponse as r, type FineTuningJobOptions as s, type ImageEditOptions as t, type ImageGenerateOptions as u, type ImageResponse as v, type OperatorInfo as w, type PrivacyConfig as x, PrivateRouter as y, type PrivateRouterConfig as z };