@mixmake/cli 0.1.1 → 0.1.5

package/README.md

@@ -4,26 +4,29 @@ Official command-line client for MixMake MCP.
 
 It handles MCP initialize/session details for common workflows:
 - get API key
-- transcribe audio
+- transcribe audio (from URL, existing `audio_id`, or a local `.mp3` / `.wav` / `.m4a` via `transcribe --file`)
 - edit transcript deletions
 - render output
 - run diagnostics
 
 ## Quick start
 
-```bash
-npx @mixmake/cli@latest doctor
-```
+Use `doctor` first, then follow the Commands block below.
 
 ## Commands
 
+When passing flags, include `--` after the package name so args go to MixMake CLI (not npm).
+
 ```bash
-npx @mixmake/cli@latest doctor
-npx @mixmake/cli@latest key --email you@example.com
-npx @mixmake/cli@latest transcribe --audio-url https://example.com/file.mp3
-npx @mixmake/cli@latest transcribe --audio-id <audio_id>
-npx @mixmake/cli@latest edit --transcript-id <id> --delete id1,id2,id3
-npx @mixmake/cli@latest render --transcript-id <id>
+npx -y @mixmake/cli@latest -- doctor
+npx -y @mixmake/cli@latest -- doctor --verbose
+npx -y @mixmake/cli@latest -- setup --email you@example.com
+npx -y @mixmake/cli@latest -- key --email you@example.com
+npx -y @mixmake/cli@latest -- transcribe --audio-url https://example.com/file.mp3
+npx -y @mixmake/cli@latest -- transcribe --audio-id <audio_id>
+npx -y @mixmake/cli@latest -- transcribe --file ./recording.mp3
+npx -y @mixmake/cli@latest -- edit --transcript-id <id> --delete id1,id2,id3
+npx -y @mixmake/cli@latest -- render --transcript-id <id>
 ```
 
 ## Configuration
@@ -36,7 +39,7 @@ Example:
 
 ```json
 {
-  "endpoint": "https://mixmake.com/api/mcp",
+  "endpoint": "https://www.mixmake.com/api/mcp",
   "apiKey": "mmk_..."
 }
 ```
@@ -47,16 +50,36 @@ Environment overrides:
 
 ## Troubleshooting
 
-Run:
+For diagnostics, run:
 
 ```bash
-npx @mixmake/cli@latest doctor
+npx -y @mixmake/cli@latest -- doctor --verbose
 ```
 
+Session notes:
+- If a replay-safe command hits `Unknown session` or `Session expired`, CLI re-initializes once and retries automatically.
+- CLI intentionally does **not** auto-replay potentially side-effecting commands like `transcribe` and `render` to avoid duplicate jobs.
+
+Local file notes:
+- `transcribe --file` uploads via signed URL under the hood, then starts transcription (same MCP `upload_audio` + `transcribe_audio` flow as the server). You need a MixMake **API key**. Run `setup` or `key` first.
+- The JSON output includes `transcript_id` and `audio_id`; use **`transcript_id`** with `edit` / `render` once transcription completes (editing does not re-run transcription).
+- Max file size **100MB**. Extensions: **.mp3**, **.wav**, **.m4a**.
+
+Setup notes:
+- `setup` validates MCP connectivity via `tools/list`, fetches an API key, and saves it to config.
+- Use `doctor --verbose` for lightweight request traces (`stage`, status, endpoint, request id).
+
 If you contact support, include:
 - request id (if present)
 - command you ran
 - timestamp and endpoint URL
+- contact email: teammixmake@gmail.com
+
+## Development
+
+```bash
+cd cli && npm test
+```
 
 ## Links
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixmake/cli",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "type": "module",
   "description": "MixMake CLI for MCP happy-path workflows",
   "license": "MIT",
@@ -11,7 +11,7 @@
   },
   "homepage": "https://mixmake.com/for-agents",
   "bugs": {
-    "url": "https://github.com/swappysh/mixmake/issues"
+    "email": "teammixmake@gmail.com"
   },
   "keywords": [
     "mixmake",
@@ -25,7 +25,8 @@
   },
   "scripts": {
     "start": "node ./src/index.js",
-    "doctor": "node ./src/index.js doctor"
+    "doctor": "node ./src/index.js doctor",
+    "test": "node --test src/*.test.js"
   },
   "engines": {
     "node": ">=20"

package/src/config.js

@@ -2,7 +2,7 @@ import { homedir } from 'node:os';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
-const DEFAULT_ENDPOINT = 'https://mixmake.com/api/mcp';
+const DEFAULT_ENDPOINT = 'https://www.mixmake.com/api/mcp';
 const CONFIG_DIR = path.join(homedir(), '.config', 'mixmake');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
 
@@ -14,7 +14,10 @@ export async function loadConfig() {
       endpoint: parsed.endpoint || DEFAULT_ENDPOINT,
       apiKey: parsed.apiKey || null,
     };
-  } catch {
+  } catch (err) {
+    if (err && typeof err === 'object' && 'code' in err && err.code !== 'ENOENT') {
+      throw err;
+    }
     return {
       endpoint: DEFAULT_ENDPOINT,
       apiKey: null,

package/src/index.js

@@ -1,6 +1,26 @@
 #!/usr/bin/env node
-import { callTool, extractToolText, initialize } from './mcpClient.js';
+import readline from 'node:readline/promises';
+
+import {
+  callRpc,
+  callToolWithOptions,
+  extractToolText,
+  initializeWithOptions,
+  shouldReinitializeSession,
+} from './mcpClient.js';
 import { getConfigPath, loadConfig, saveConfig, withEnvOverrides } from './config.js';
+import { tryParseJson } from './parseJson.js';
+import {
+  defaultUploadLabel,
+  putBufferToSignedUrl,
+  readAudioFileForUpload,
+} from './localUpload.js';
+
+function toolResultForCli(out) {
+  const text = extractToolText(out.payload);
+  const parsed = tryParseJson(text);
+  return { text, parsed, display: parsed ?? out.payload };
+}
 
 function parseArgs(argv) {
   const positionals = [];
@@ -23,13 +43,35 @@ function parseArgs(argv) {
   return { positionals, flags };
 }
 
+async function uploadLocalThroughMcp({ endpoint, apiKey, filePath, labelFlag, trace }) {
+  const { buffer, contentType } = await readAudioFileForUpload(filePath);
+  const label = defaultUploadLabel(filePath, labelFlag);
+  const out = await callToolWithSessionRecovery({
+    endpoint,
+    apiKey,
+    name: 'upload_audio',
+    args: { label },
+    allowReplay: false,
+    trace,
+  });
+  const { parsed } = toolResultForCli(out);
+  const uploadUrl = parsed?.upload_url;
+  const audioId = parsed?.audio_id;
+  if (typeof uploadUrl !== 'string' || typeof audioId !== 'string') {
+    throw new Error('upload_audio did not return upload_url and audio_id');
+  }
+  await putBufferToSignedUrl(uploadUrl, buffer, contentType);
+  return { audio_id: audioId, label };
+}
+
 function usage() {
   console.log(`mixmake <command> [flags]
 
 Commands:
-  doctor
+  doctor [--verbose]
+  setup [--email <email>] [--verbose]
   key --email <email>
-  transcribe --audio-url <url> | --audio-id <id> [--label <label>]
+  transcribe --audio-url <url> | --audio-id <id> | --file <path> [--label <label>]
   edit --transcript-id <id> --delete <id1,id2,...>
   render --transcript-id <id>
 
@@ -45,6 +87,47 @@ function printResult(label, data) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+function printRecoveryNotice(toolName) {
+  console.error(`Session expired or drifted while calling ${toolName}; re-initializing once and retrying.`);
+}
+
+async function callToolWithSessionRecovery({
+  endpoint,
+  apiKey,
+  name,
+  args,
+  allowReplay = false,
+  trace,
+}) {
+  const invoke = (init) =>
+    callToolWithOptions(
+      { endpoint, sessionId: init.sessionId, token: init.token, apiKey, name, args },
+      { trace }
+    );
+
+  let init = await initializeWithOptions(endpoint, { trace });
+  try {
+    return await invoke(init);
+  } catch (err) {
+    if (!allowReplay || !shouldReinitializeSession(err)) throw err;
+    printRecoveryNotice(name);
+    init = await initializeWithOptions(endpoint, { trace });
+    return invoke(init);
+  }
+}
+
+async function resolveSetupEmail(flagEmail) {
+  if (typeof flagEmail === 'string' && flagEmail.trim()) return flagEmail.trim();
+  if (!process.stdin.isTTY) return null;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const email = (await rl.question('Email for MixMake API key: ')).trim();
+    return email || null;
+  } finally {
+    rl.close();
+  }
+}
+
 async function main() {
   const { positionals, flags } = parseArgs(process.argv.slice(2));
   const cmd = positionals[0];
@@ -55,9 +138,15 @@ async function main() {
 
   const config = withEnvOverrides(await loadConfig());
   const endpoint = config.endpoint;
+  const verbose = Boolean(flags.verbose);
+  const trace = verbose
+    ? (event) => {
+        console.error('[trace]', JSON.stringify(event));
+      }
+    : undefined;
 
   if (cmd === 'doctor') {
-    const init = await initialize(endpoint);
+    const init = await initializeWithOptions(endpoint, { trace });
     printResult('doctor', {
       ok: true,
       endpoint,
@@ -69,30 +158,56 @@ async function main() {
     return;
   }
 
+  if (cmd === 'setup') {
+    const email = await resolveSetupEmail(flags.email);
+    if (!email) throw new Error('No email provided. Use --email or enter one at prompt.');
+    const init = await initializeWithOptions(endpoint, { trace });
+    const session = {
+      endpoint,
+      sessionId: init.sessionId,
+      token: init.token,
+      apiKey: config.apiKey,
+    };
+    const listOut = await callRpc({ ...session, method: 'tools/list' }, { trace });
+    const keyOut = await callToolWithOptions({ ...session, name: 'get_api_key', args: { email } }, { trace });
+    const { text, parsed } = toolResultForCli(keyOut);
+    const key = parsed?.api_key || parsed?.key || null;
+    if (!key) {
+      const trimmed = typeof text === 'string' ? text.trim() : '';
+      throw new Error(trimmed || 'get_api_key did not return a parsable key');
+    }
+    if (!process.env.MIXMAKE_API_KEY) {
+      await saveConfig({ endpoint, apiKey: key });
+    }
+    printResult('setup', {
+      ok: true,
+      endpoint,
+      email,
+      config_path: getConfigPath(),
+      tools_count: listOut.payload?.result?.tools?.length ?? null,
+      request_id: keyOut.requestId || init.requestId || null,
+    });
+    return;
+  }
+
   if (cmd === 'key') {
     const email = flags.email;
     if (!email || typeof email !== 'string') throw new Error('--email is required');
-    const init = await initialize(endpoint);
-    const out = await callTool({
+    const out = await callToolWithSessionRecovery({
       endpoint,
-      sessionId: init.sessionId,
-      token: init.token,
       apiKey: config.apiKey,
       name: 'get_api_key',
       args: { email },
+      allowReplay: true,
+      trace,
     });
-    const text = extractToolText(out.payload);
-    printResult('get_api_key', text ? JSON.parse(text) : out.payload);
-
-    try {
-      const parsed = text ? JSON.parse(text) : null;
-      const key = parsed?.api_key || parsed?.key || null;
-      if (key && !process.env.MIXMAKE_API_KEY) {
-        await saveConfig({ endpoint, apiKey: key });
-        console.log(`\nSaved api_key to ${getConfigPath()}`);
-      }
-    } catch {
-      // no-op: only auto-save if response shape is predictable JSON
+    const { parsed, display } = toolResultForCli(out);
+    printResult('get_api_key', display);
+
+    const key = parsed?.api_key || parsed?.key || null;
+    if (key && !process.env.MIXMAKE_API_KEY) {
+      await saveConfig({ endpoint, apiKey: key });
+      console.log(`\nSaved api_key to ${getConfigPath()}`);
     }
     return;
   }
@@ -100,19 +215,38 @@ async function main() {
   if (cmd === 'transcribe') {
     const audioUrl = flags['audio-url'];
     const audioId = flags['audio-id'];
+    const file = flags.file;
     const label = flags.label;
-    if (!audioUrl && !audioId) throw new Error('Provide --audio-url or --audio-id');
-    const init = await initialize(endpoint);
-    const out = await callTool({
+    const sources = [audioUrl, audioId, file].filter((x) => typeof x === 'string' && x).length;
+    if (sources !== 1) {
+      throw new Error('Provide exactly one of --audio-url, --audio-id, or --file');
+    }
+    let resolvedUrl;
+    let resolvedId;
+    if (typeof audioUrl === 'string' && audioUrl) {
+      resolvedUrl = audioUrl;
+    } else if (typeof audioId === 'string' && audioId) {
+      resolvedId = audioId;
+    } else {
+      const up = await uploadLocalThroughMcp({
+        endpoint,
+        apiKey: config.apiKey,
+        filePath: file,
+        labelFlag: label,
+        trace,
+      });
+      resolvedId = up.audio_id;
+    }
+    const out = await callToolWithSessionRecovery({
       endpoint,
-      sessionId: init.sessionId,
-      token: init.token,
       apiKey: config.apiKey,
       name: 'transcribe_audio',
-      args: { audio_url: audioUrl, audio_id: audioId, label },
+      args: { audio_url: resolvedUrl, audio_id: resolvedId, label },
+      allowReplay: false,
+      trace,
     });
-    const text = extractToolText(out.payload);
-    printResult('transcribe_audio', text ? JSON.parse(text) : out.payload);
+    const result = toolResultForCli(out);
+    printResult('transcribe_audio', result.display);
     return;
   }
 
@@ -125,34 +259,32 @@ async function main() {
       .split(',')
       .map((s) => s.trim())
       .filter(Boolean);
-    const init = await initialize(endpoint);
-    const out = await callTool({
+    const out = await callToolWithSessionRecovery({
       endpoint,
-      sessionId: init.sessionId,
-      token: init.token,
       apiKey: config.apiKey,
       name: 'edit_transcript',
       args: { transcript_id: transcriptId, deleted_ids: deletedIds },
+      allowReplay: true,
+      trace,
     });
-    const text = extractToolText(out.payload);
-    printResult('edit_transcript', text ? JSON.parse(text) : out.payload);
+    const result = toolResultForCli(out);
+    printResult('edit_transcript', result.display);
     return;
   }
 
   if (cmd === 'render') {
     const transcriptId = flags['transcript-id'];
     if (!transcriptId || typeof transcriptId !== 'string') throw new Error('--transcript-id is required');
-    const init = await initialize(endpoint);
-    const out = await callTool({
+    const out = await callToolWithSessionRecovery({
       endpoint,
-      sessionId: init.sessionId,
-      token: init.token,
       apiKey: config.apiKey,
       name: 'render_audio',
       args: { transcript_id: transcriptId },
+      allowReplay: false,
+      trace,
     });
-    const text = extractToolText(out.payload);
-    printResult('render_audio', text ? JSON.parse(text) : out.payload);
+    const result = toolResultForCli(out);
+    printResult('render_audio', result.display);
     return;
   }
 

package/src/localUpload.js

@@ -0,0 +1,42 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+
+export const MAX_AUDIO_BYTES = 100 * 1024 * 1024;
+
+/** Rejects byte sizes over the CLI upload limit. */
+export function assertWithinMaxAudioBytes(size) {
+  if (size > MAX_AUDIO_BYTES) throw new Error('File exceeds 100MB limit');
+}
+
+export function audioContentTypeForPath(filePath) {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith('.mp3')) return 'audio/mpeg';
+  if (lower.endsWith('.wav')) return 'audio/wav';
+  if (lower.endsWith('.m4a')) return 'audio/mp4';
+  throw new Error('Unsupported extension: use .mp3, .wav, or .m4a');
+}
+
+export async function readAudioFileForUpload(filePath) {
+  const st = await stat(filePath);
+  assertWithinMaxAudioBytes(st.size);
+  const buffer = await readFile(filePath);
+  const contentType = audioContentTypeForPath(filePath);
+  return { buffer, contentType, size: st.size };
+}
+
+export async function putBufferToSignedUrl(uploadUrl, buffer, contentType) {
+  const res = await fetch(uploadUrl, {
+    method: 'PUT',
+    headers: { 'Content-Type': contentType },
+    body: buffer,
+  });
+  if (!res.ok) {
+    const detail = (await res.text()).trim().slice(0, 200);
+    throw new Error(`Storage upload failed (${res.status}): ${detail}`);
+  }
+}
+
+export function defaultUploadLabel(filePath, labelFlag) {
+  if (typeof labelFlag === 'string' && labelFlag.trim()) return labelFlag.trim();
+  return basename(filePath);
+}

package/src/localUpload.test.js

@@ -0,0 +1,87 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  MAX_AUDIO_BYTES,
+  assertWithinMaxAudioBytes,
+  audioContentTypeForPath,
+  defaultUploadLabel,
+  putBufferToSignedUrl,
+  readAudioFileForUpload,
+} from './localUpload.js';
+
+test('audioContentTypeForPath maps extensions', () => {
+  assert.equal(audioContentTypeForPath('/a/b.X.mp3'), 'audio/mpeg');
+  assert.equal(audioContentTypeForPath('c.wav'), 'audio/wav');
+  assert.equal(audioContentTypeForPath('d.m4a'), 'audio/mp4');
+});
+
+test('audioContentTypeForPath rejects unknown extension', () => {
+  assert.throws(() => audioContentTypeForPath('x.flac'), /Unsupported extension/);
+});
+
+test('defaultUploadLabel prefers flag', () => {
+  assert.equal(defaultUploadLabel('/path/to/foo.mp3', '  my label  '), 'my label');
+  assert.equal(defaultUploadLabel('/path/to/foo.mp3', undefined), 'foo.mp3');
+});
+
+test('readAudioFileForUpload reads small file', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'mixmake-cli-test-'));
+  const filePath = join(dir, 't.mp3');
+  await writeFile(filePath, Buffer.from([1, 2, 3]));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  const { buffer, contentType, size } = await readAudioFileForUpload(filePath);
+  assert.equal(contentType, 'audio/mpeg');
+  assert.equal(size, 3);
+  assert.equal(buffer.length, 3);
+});
+
+test('assertWithinMaxAudioBytes allows at limit', () => {
+  assertWithinMaxAudioBytes(MAX_AUDIO_BYTES);
+});
+
+test('assertWithinMaxAudioBytes rejects over limit', () => {
+  assert.throws(() => assertWithinMaxAudioBytes(MAX_AUDIO_BYTES + 1), /100MB/);
+});
+
+test('putBufferToSignedUrl PUTs buffer and returns on OK', async (t) => {
+  const orig = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = orig;
+  });
+  let seenUrl;
+  let seenInit;
+  globalThis.fetch = async (url, init) => {
+    seenUrl = url;
+    seenInit = init;
+    return { ok: true, status: 200, text: async () => '' };
+  };
+  const buf = Buffer.from([9, 8, 7]);
+  await putBufferToSignedUrl('https://signed.example/put', buf, 'audio/mpeg');
+  assert.equal(seenUrl, 'https://signed.example/put');
+  assert.equal(seenInit.method, 'PUT');
+  assert.deepEqual(seenInit.body, buf);
+  const ct =
+    seenInit.headers?.['Content-Type'] ?? seenInit.headers?.['content-type'];
+  assert.equal(ct, 'audio/mpeg');
+});
+
+test('putBufferToSignedUrl throws with status and trimmed body on failure', async (t) => {
+  const orig = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = orig;
+  });
+  globalThis.fetch = async () => ({
+    ok: false,
+    status: 403,
+    text: async () => '  forbidden  ',
+  });
+  await assert.rejects(
+    () => putBufferToSignedUrl('https://signed.example/put', Buffer.from([1]), 'audio/wav'),
+    /Storage upload failed \(403\): forbidden/,
+  );
+});

package/src/mcpClient.js

@@ -1,4 +1,15 @@
 const ACCEPT = 'application/json, text/event-stream';
+const PROTOCOL_VERSION = '2025-06-18';
+
+export class McpHttpError extends Error {
+  constructor(message, { status, requestId, payload } = {}) {
+    super(message);
+    this.name = 'McpHttpError';
+    this.status = status ?? null;
+    this.requestId = requestId ?? null;
+    this.payload = payload ?? null;
+  }
+}
 
 function stripTrailingSlash(url) {
   return url.endsWith('/') ? url.slice(0, -1) : url;
@@ -8,23 +19,35 @@ function headers(base = {}) {
   return {
     Accept: ACCEPT,
     'Content-Type': 'application/json',
+    'MCP-Protocol-Version': PROTOCOL_VERSION,
     ...base,
   };
 }
 
-export async function initialize(endpoint) {
+function bearerHeaders(token, sessionId, apiKey) {
+  const h = {
+    Authorization: `Bearer ${token}`,
+    'Mcp-Session-Id': sessionId,
+  };
+  if (apiKey) h['X-Mixmake-Api-Key'] = apiKey;
+  return h;
+}
+
+export async function initializeWithOptions(endpoint, options = {}) {
+  const { trace } = options;
   const body = {
     jsonrpc: '2.0',
     id: 1,
     method: 'initialize',
     params: {
-      protocolVersion: '2025-03-26',
+      protocolVersion: PROTOCOL_VERSION,
       capabilities: {},
       clientInfo: { name: 'mixmake-cli', version: '0.1.0' },
     },
   };
 
-  const res = await fetch(stripTrailingSlash(endpoint), {
+  const url = stripTrailingSlash(endpoint);
+  const res = await fetch(url, {
     method: 'POST',
     headers: headers(),
     body: JSON.stringify(body),
@@ -32,20 +55,32 @@ export async function initialize(endpoint) {
   });
 
   const requestId = res.headers.get('x-request-id');
-  const sessionId = res.headers.get('mcp-session-id') || res.headers.get('Mcp-Session-Id');
+  const sessionId = res.headers.get('mcp-session-id');
   const payload = await safeJson(res);
   const token = payload?.result?._meta?.sessionToken;
 
   if (!res.ok) {
-    throw new Error(`initialize failed (${res.status})${requestId ? ` request_id=${requestId}` : ''}`);
+    throw new McpHttpError(formatHttpError('initialize', res.status, requestId, payload), {
+      status: res.status,
+      requestId,
+      payload,
+    });
   }
+  trace?.({
+    stage: 'initialize',
+    endpoint: url,
+    status: res.status,
+    requestId: requestId || null,
+    ok: true,
+  });
   if (!sessionId || !token) {
     throw new Error(`initialize missing session details${requestId ? ` request_id=${requestId}` : ''}`);
   }
   return { sessionId, token, requestId, payload };
 }
 
-export async function callTool({ endpoint, sessionId, token, apiKey, name, args, id = 2 }) {
+export async function callToolWithOptions({ endpoint, sessionId, token, apiKey, name, args, id = 2 }, options = {}) {
+  const { trace } = options;
   const body = {
     jsonrpc: '2.0',
     id,
@@ -55,23 +90,30 @@ export async function callTool({ endpoint, sessionId, token, apiKey, name, args,
       arguments: args,
     },
   };
-  const extraHeaders = {
-    Authorization: `Bearer ${token}`,
-    'Mcp-Session-Id': sessionId,
-  };
-  if (apiKey) extraHeaders['X-Mixmake-Api-Key'] = apiKey;
-
-  const res = await fetch(stripTrailingSlash(endpoint), {
+  const url = stripTrailingSlash(endpoint);
+  const res = await fetch(url, {
     method: 'POST',
-    headers: headers(extraHeaders),
+    headers: headers(bearerHeaders(token, sessionId, apiKey)),
     body: JSON.stringify(body),
     redirect: 'follow',
   });
   const requestId = res.headers.get('x-request-id');
   const payload = await safeJson(res);
   if (!res.ok) {
-    throw new Error(`tool ${name} failed (${res.status})${requestId ? ` request_id=${requestId}` : ''}`);
+    throw new McpHttpError(formatHttpError(`tool ${name}`, res.status, requestId, payload), {
+      status: res.status,
+      requestId,
+      payload,
+    });
   }
+  trace?.({
+    stage: 'tools/call',
+    tool: name,
+    endpoint: url,
+    status: res.status,
+    requestId: requestId || null,
+    ok: true,
+  });
   if (payload?.error) {
     const msg = payload.error?.message || 'unknown error';
     throw new Error(`tool ${name} error: ${msg}${requestId ? ` request_id=${requestId}` : ''}`);
@@ -79,12 +121,60 @@ export async function callTool({ endpoint, sessionId, token, apiKey, name, args,
   return { payload, requestId };
 }
 
+export function shouldReinitializeSession(error) {
+  if (!(error instanceof McpHttpError)) return false;
+  if (error.status === 404 || error.status === 410) return true;
+  const msg = `${error.message} ${(error.payload?.error?.message ?? '')}`.toLowerCase();
+  return msg.includes('unknown session') || msg.includes('session expired');
+}
+
+export async function callRpc({ endpoint, sessionId, token, apiKey, method, params, id = 2 }, options = {}) {
+  const { trace } = options;
+  const body = { jsonrpc: '2.0', id, method, params };
+
+  const url = stripTrailingSlash(endpoint);
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: headers(bearerHeaders(token, sessionId, apiKey)),
+    body: JSON.stringify(body),
+    redirect: 'follow',
+  });
+  const requestId = res.headers.get('x-request-id');
+  const payload = await safeJson(res);
+  if (!res.ok) {
+    throw new McpHttpError(formatHttpError(method, res.status, requestId, payload), {
+      status: res.status,
+      requestId,
+      payload,
+    });
+  }
+  trace?.({
+    stage: method,
+    endpoint: url,
+    status: res.status,
+    requestId: requestId || null,
+    ok: true,
+  });
+  if (payload?.error) {
+    const msg = payload.error?.message || 'unknown error';
+    throw new Error(`${method} error: ${msg}${requestId ? ` request_id=${requestId}` : ''}`);
+  }
+  return { payload, requestId };
+}
+
 function safeJson(res) {
   return res
     .json()
     .catch(async () => ({ raw: await res.text().catch(() => ''), error: { message: 'non-json response' } }));
 }
 
+function formatHttpError(label, status, requestId, payload) {
+  const rpcMessage = payload?.error?.message;
+  const raw = typeof payload?.raw === 'string' ? payload.raw.trim() : '';
+  const details = rpcMessage || raw || 'no response details';
+  return `${label} failed (${status}): ${details}${requestId ? ` request_id=${requestId}` : ''}`;
+}
+
 export function extractToolText(payload) {
-  return payload?.result?.content?.find?.((item) => item.type === 'text')?.text;
+  return payload?.result?.content?.find((item) => item.type === 'text')?.text;
 }

package/src/mcpClient.test.js

@@ -0,0 +1,201 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  McpHttpError,
+  initializeWithOptions,
+  callRpc,
+  callToolWithOptions,
+  shouldReinitializeSession,
+  extractToolText,
+} from './mcpClient.js';
+
+function headersMap(obj) {
+  const map = new Map(Object.entries(obj).map(([k, v]) => [k.toLowerCase(), v]));
+  return {
+    get(name) {
+      const v = map.get(name.toLowerCase());
+      return v === undefined ? null : v;
+    },
+  };
+}
+
+function jsonResponse({ ok = true, status = 200, headers = {}, json }) {
+  return {
+    ok,
+    status,
+    headers: headersMap(headers),
+    json: async () => json,
+    text: async () => '',
+  };
+}
+
+const ORIGINAL_FETCH = globalThis.fetch;
+
+test.afterEach(() => {
+  globalThis.fetch = ORIGINAL_FETCH;
+});
+
+test('shouldReinitializeSession treats 404 and 410 as recoverable', () => {
+  assert.equal(shouldReinitializeSession(new McpHttpError('x', { status: 404 })), true);
+  assert.equal(shouldReinitializeSession(new McpHttpError('x', { status: 410 })), true);
+  assert.equal(shouldReinitializeSession(new McpHttpError('x', { status: 401 })), false);
+});
+
+test('shouldReinitializeSession matches session messaging', () => {
+  assert.equal(
+    shouldReinitializeSession(new McpHttpError('Unknown session x', { status: 400, payload: {} })),
+    true
+  );
+  const err = new McpHttpError('x', {
+    status: 400,
+    payload: { error: { message: 'Session expired' } },
+  });
+  assert.equal(shouldReinitializeSession(err), true);
+});
+
+test('shouldReinitializeSession false for non-McpHttpError', () => {
+  assert.equal(shouldReinitializeSession(new Error('x')), false);
+});
+
+test('extractToolText reads first text content item', () => {
+  assert.equal(extractToolText(null), undefined);
+  assert.equal(
+    extractToolText({ result: { content: [{ type: 'text', text: 'hello' }] } }),
+    'hello'
+  );
+});
+
+test('initializeWithOptions returns session token and runs trace', async () => {
+  const traces = [];
+  globalThis.fetch = async (url, init) => {
+    assert.match(String(url), /https:\/\/example\.com\/api\/mcp$/);
+    assert.equal(init.method, 'POST');
+    const body = JSON.parse(init.body);
+    assert.equal(body.method, 'initialize');
+    return jsonResponse({
+      headers: { 'mcp-session-id': 'sid-1', 'x-request-id': 'req-1' },
+      json: {
+        result: {
+          serverInfo: { name: 'mixmake', version: '1' },
+          _meta: { sessionToken: 'jwt-here' },
+        },
+      },
+    });
+  };
+
+  const r = await initializeWithOptions('https://example.com/api/mcp/', {
+    trace: (e) => traces.push(e),
+  });
+
+  assert.equal(r.sessionId, 'sid-1');
+  assert.equal(r.token, 'jwt-here');
+  assert.equal(r.requestId, 'req-1');
+  assert.equal(traces.length, 1);
+  assert.equal(traces[0].stage, 'initialize');
+  assert.ok(!('sessionId' in traces[0]));
+});
+
+test('initializeWithOptions throws McpHttpError when HTTP not ok', async () => {
+  globalThis.fetch = async () =>
+    jsonResponse({
+      ok: false,
+      status: 503,
+      json: { error: { message: 'unavailable' } },
+    });
+
+  await assert.rejects(
+    () => initializeWithOptions('https://example.com/api/mcp'),
+    (err) => err instanceof McpHttpError && err.status === 503
+  );
+});
+
+test('initializeWithOptions throws when session id or token missing on 200', async () => {
+  globalThis.fetch = async () =>
+    jsonResponse({
+      json: { result: { serverInfo: {}, _meta: { sessionToken: 't' } } },
+      headers: {},
+    });
+
+  await assert.rejects(
+    () => initializeWithOptions('https://example.com/api/mcp'),
+    /initialize missing session details/
+  );
+});
+
+test('callRpc tools/list without params omits params from JSON body', async () => {
+  let body;
+  globalThis.fetch = async (url, init) => {
+    body = JSON.parse(init.body);
+    return jsonResponse({ json: { result: { tools: [] } } });
+  };
+
+  await callRpc({
+    endpoint: 'https://example.com/api/mcp',
+    sessionId: 's',
+    token: 't',
+    method: 'tools/list',
+  });
+
+  assert.equal(body.jsonrpc, '2.0');
+  assert.equal(body.method, 'tools/list');
+  assert.equal('params' in body, false);
+});
+
+test('callRpc runs trace on HTTP success', async () => {
+  const traces = [];
+  globalThis.fetch = async () => jsonResponse({ json: { result: { tools: [] } } });
+
+  await callRpc(
+    { endpoint: 'https://example.com/api/mcp', sessionId: 's', token: 't', method: 'tools/list' },
+    { trace: (e) => traces.push(e) }
+  );
+
+  assert.equal(traces.length, 1);
+  assert.equal(traces[0].stage, 'tools/list');
+  assert.equal(traces[0].ok, true);
+});
+
+test('callToolWithOptions sends auth headers and invokes trace', async () => {
+  const traces = [];
+  globalThis.fetch = async (url, init) => {
+    const h = new Headers(init.headers);
+    assert.equal(h.get('Authorization'), 'Bearer mytoken');
+    assert.equal(h.get('Mcp-Session-Id'), 'msid');
+    const body = JSON.parse(init.body);
+    assert.equal(body.method, 'tools/call');
+    assert.equal(body.params.name, 'get_api_key');
+    return jsonResponse({ json: { result: { content: [{ type: 'text', text: '{"api_key":"mmk_x"}' }] } } });
+  };
+
+  const out = await callToolWithOptions(
+    {
+      endpoint: 'https://example.com/api/mcp',
+      sessionId: 'msid',
+      token: 'mytoken',
+      name: 'get_api_key',
+      args: { email: 'u@example.com' },
+    },
+    { trace: (e) => traces.push(e) }
+  );
+
+  assert.equal(traces[0].stage, 'tools/call');
+  assert.equal(traces[0].tool, 'get_api_key');
+  assert.match(out.payload.result.content[0].text, /mmk_/);
+});
+
+test('callToolWithOptions throws on JSON-RPC error in 200 body', async () => {
+  globalThis.fetch = async () =>
+    jsonResponse({ json: { error: { message: 'tool failed' } } });
+
+  await assert.rejects(
+    () =>
+      callToolWithOptions({
+        endpoint: 'https://example.com/api/mcp',
+        sessionId: 's',
+        token: 't',
+        name: 'x',
+        args: {},
+      }),
+    /tool x error: tool failed/
+  );
+});

package/src/parseJson.js

@@ -0,0 +1,8 @@
+export function tryParseJson(input) {
+  if (typeof input !== 'string' || !input) return null;
+  try {
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}

package/src/parseJson.test.js

@@ -0,0 +1,17 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { tryParseJson } from './parseJson.js';
+
+test('tryParseJson parses valid JSON', () => {
+  assert.deepEqual(tryParseJson('{"a":1}'), { a: 1 });
+});
+
+test('tryParseJson returns null for invalid JSON', () => {
+  assert.equal(tryParseJson('{'), null);
+});
+
+test('tryParseJson returns null for empty or non-string', () => {
+  assert.equal(tryParseJson(''), null);
+  assert.equal(tryParseJson(null), null);
+  assert.equal(tryParseJson(1), null);
+});