@letta-ai/letta-code 0.32.11 → 0.32.13

package/scripts/smoke-pypi.py

@@ -0,0 +1,236 @@
+"""Install and exercise a wheel offline, outside the checkout and without Node/npm on PATH."""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import venv
+from pathlib import Path
+
+ARGUMENT_PROBE = r"""
+import assert from 'node:assert/strict';
+assert.equal(process.env.LETTA_CODE_DISTRIBUTION, 'pypi');
+assert.deepEqual(process.argv.slice(2), ['space argument', 'unicode-λ', '--literal=$HOME']);
+assert.ok(process.execPath.includes('_payload'));
+process.exit(23); // Verify the Python launcher preserves child exit status.
+"""
+
+RUNTIME_PROBE = r"""
+import {createRequire as bootstrapRequire} from 'node:module';
+const require = bootstrapRequire(import.meta.url);
+const assert = require('node:assert/strict');
+const {createRequire} = require('node:module');
+const {spawnSync} = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+const cli = process.argv[2];
+const app = path.dirname(cli);
+const req = createRequire(cli);
+const env = {...process.env};
+delete env.NODE_OPTIONS;
+assert.equal(process.env.LETTA_CODE_DISTRIBUTION, 'pypi');
+assert.ok(process.execPath.includes('_payload'));
+const child = spawnSync('node', ['-p', 'process.execPath'], {env, encoding:'utf8'});
+assert.equal(child.status, 0, child.stderr);
+assert.equal(fs.realpathSync(child.stdout.trim()), fs.realpathSync(process.execPath));
+if (process.platform !== 'win32') {
+  const direct = spawnSync(cli, ['--version'], {env, encoding:'utf8'});
+  assert.equal(direct.status, 0, direct.stderr); // Executable bits + /usr/bin/env node.
+  assert.match(direct.stdout, /Letta Code/);
+}
+assert.ok(fs.existsSync(path.join(app, 'skills', 'letta-guide', 'SKILL.md')));
+assert.ok(fs.existsSync(path.join(app, 'assets', 'tutor-profile.png')));
+const rg = spawnSync(req('@vscode/ripgrep').rgPath, ['--version'], {env, encoding:'utf8'});
+assert.equal(rg.status, 0, rg.stderr);
+assert.match(rg.stdout, /ripgrep/);
+assert.equal(typeof req('ws').WebSocketServer, 'function');
+(async () => {
+  const {Bot} = req('grammy');
+  const bot = new Bot('123:test');
+  bot.api.config.use(async () => ({ok:true, result:{id:123, is_bot:true, first_name:'wheel', username:'wheel_bot'}}));
+  await bot.init();
+  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="3000" height="2"><rect width="3000" height="2" fill="red"/></svg>';
+  const resized = spawnSync(process.execPath, [path.join(app, 'image-resize-worker.js'), 'image/svg+xml'], {input:svg, env});
+  assert.equal(resized.status, 0, resized.stderr.toString());
+  const image = JSON.parse(resized.stdout);
+  assert.ok(image.width > 0 && image.width < 3000, JSON.stringify(image));
+  const ptyCommand = process.platform === 'win32' ? process.env.ComSpec : process.execPath;
+  const ptyArgs = process.platform === 'win32' ? ['/d', '/s', '/c', 'echo LETTA_PTY_OK'] : [cli, '--help'];
+  const ptyExpected = process.platform === 'win32' ? /LETTA_PTY_OK/ : /USAGE/;
+  const pty = req('node-pty').spawn(ptyCommand, ptyArgs, {env, cols:100, rows:30});
+  let output = '';
+  pty.onData(data => { output += data; });
+  const timeout = setTimeout(() => { pty.kill(); throw new Error('PTY timed out'); }, 30000);
+  pty.onExit(({exitCode}) => {
+    clearTimeout(timeout);
+    assert.equal(exitCode, 0, output);
+    assert.match(output, ptyExpected);
+    console.log('native PTY, image worker, ripgrep, Telegram, assets and child Node passed');
+    process.exit(0);
+  });
+})().catch(error => {console.error(error); process.exit(1)});
+// Hold the script until the asynchronous probe exits.
+await new Promise(() => {});
+"""
+
+
+def main():
+    wheel = Path(sys.argv[1]).resolve()
+    if wheel.stat().st_size >= 100 * 1024 * 1024:
+        raise SystemExit("Wheel exceeds the default PyPI 100 MiB artifact limit")
+    with tempfile.TemporaryDirectory(prefix="letta wheel smoke ") as temporary:
+        root = Path(temporary)
+        environment = root / "venv"
+        venv.create(environment, with_pip=True)
+        binary = environment / ("Scripts" if os.name == "nt" else "bin")
+        python = binary / ("python.exe" if os.name == "nt" else "python")
+        cli = binary / ("letta.exe" if os.name == "nt" else "letta")
+        subprocess.run(
+            [
+                str(python),
+                "-m",
+                "pip",
+                "install",
+                "--no-index",
+                "--no-deps",
+                str(wheel),
+            ],
+            check=True,
+        )
+        home = root / "home"
+        home.mkdir()
+        env = {
+            k: v
+            for k, v in os.environ.items()
+            if not k.startswith(("LETTA", "NODE_", "NPM_"))
+            and k not in ("AGENT_ID", "CONVERSATION_ID", "MEMORY_DIR")
+        }
+        env.update(
+            HOME=str(home),
+            USERPROFILE=str(home),
+            PATH=str(binary),
+            DISABLE_AUTOUPDATER="0",
+        )
+        if os.name == "nt":
+            env["PATH"] += os.pathsep + str(Path(os.environ["SystemRoot"]) / "System32")
+        for args, expected, code in [
+            (["--help"], "USAGE", 0),
+            (["--version"], "Letta Code", 0),
+            (["update"], "uv tool upgrade letta", 1),
+        ]:
+            result = subprocess.run(
+                [str(cli), *args],
+                cwd=root,
+                env=env,
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=45,
+            )
+            assert result.returncode == code, (args, result.stdout, result.stderr)
+            assert expected in result.stdout + result.stderr, result
+        env.update(
+            LETTA_LOCAL_BACKEND_DIR=str(root / "local-store"),
+            LETTA_LOCAL_BACKEND_EXECUTOR="deterministic",
+            LETTA_SKIP_KEYCHAIN_CHECK="1",
+        )
+        result = subprocess.run(
+            [
+                str(cli),
+                "--backend",
+                "local",
+                "--ephemeral",
+                "-m",
+                "openai/gpt-5.6-luna",
+                "-p",
+                "wheel runtime smoke",
+                "--tools=",
+                "--output-format",
+                "json",
+            ],
+            cwd=root,
+            env=env,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        assert result.returncode == 0, (result.stdout, result.stderr)
+        response = json.loads(result.stdout)
+        assert response["conversation_id"].startswith("local-conv-"), response
+        assert response["result"], response
+        print("Installed headless deterministic local turn passed")
+        argument_probe = root / "argument-probe.mjs"
+        argument_probe.write_text(ARGUMENT_PROBE, encoding="utf-8")
+        env["NODE_OPTIONS"] = "--import=" + json.dumps(argument_probe.as_uri())
+        result = subprocess.run(
+            [str(cli), "space argument", "unicode-λ", "--literal=$HOME"],
+            cwd=root,
+            env=env,
+            check=False,
+            timeout=60,
+        )
+        assert result.returncode == 23, result
+        del env["NODE_OPTIONS"]
+        payload = Path(
+            subprocess.check_output(
+                [
+                    str(python),
+                    "-c",
+                    "from pathlib import Path; import letta_code; print(Path(letta_code.__file__).parent / '_payload')",
+                ],
+                text=True,
+            ).strip()
+        )
+        node = payload / "bin" / ("node.exe" if os.name == "nt" else "node")
+        installed_cli = payload / "app" / "letta.js"
+        runtime_probe = root / "runtime-probe.mjs"
+        runtime_probe.write_text(RUNTIME_PROBE, encoding="utf-8")
+        env["PATH"] = str(node.parent) + os.pathsep + env["PATH"]
+        env["LETTA_CODE_DISTRIBUTION"] = "pypi"
+        result = subprocess.run(
+            [str(node), str(runtime_probe), str(installed_cli)],
+            cwd=root,
+            env=env,
+            check=False,
+            timeout=60,
+        )
+        assert result.returncode == 0, result
+        if os.name != "nt":
+            import selectors
+            import signal
+
+            signal_probe = root / "signal.mjs"
+            signal_probe.write_text(
+                "process.on('SIGTERM', () => process.exit(42)); console.log(process.pid); setInterval(() => {}, 1000); await new Promise(() => {});"
+            )
+            env["NODE_OPTIONS"] = "--import=" + json.dumps(signal_probe.as_uri())
+            process = subprocess.Popen(
+                [str(cli)],
+                cwd=root,
+                env=env,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+            try:
+                with selectors.DefaultSelector() as selector:
+                    selector.register(process.stdout, selectors.EVENT_READ)
+                    assert selector.select(timeout=15), "Signal probe did not start"
+                    assert int(process.stdout.readline()) == process.pid, (
+                        "Launcher did not exec Node"
+                    )
+                process.send_signal(signal.SIGTERM)
+                process.communicate(timeout=15)
+                assert process.returncode == 42, process.returncode
+            finally:
+                if process.poll() is None:
+                    process.kill()
+                    process.wait()
+            print("POSIX PID and SIGTERM forwarding passed")
+        print(f"Installed wheel smoke passed: {wheel.name}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/source-file-size-baseline.json

@@ -8,7 +8,7 @@
   "src/cli/app/AppCoordinator.tsx": 5141,
   "src/cli/app/AppView.tsx": 1735,
   "src/cli/app/use-approval-flow.ts": 1163,
-  "src/cli/app/use-configuration-handlers.ts": 1421,
+  "src/cli/app/use-configuration-handlers.ts": 1420,
   "src/cli/app/use-conversation-loop.ts": 2903,
   "src/cli/app/use-submit-handler.ts": 3979,
   "src/cli/components/AgentSelector.tsx": 1104,

package/scripts/stage-pypi-deps.mjs

@@ -0,0 +1,90 @@
+// Copy the locked runtime dependency closure, preserving Node's nested versions.
+// No dependency installation happens on the user's machine.
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const root = process.cwd();
+const app = resolve(process.argv[2]);
+// sharp-electron is only reachable under Electron, never our bundled Node.
+const roots = ["ws", "@vscode/ripgrep", "node-pty", "grammy"];
+
+function locate(name, from) {
+  for (let dir = from; ; dir = dirname(dir)) {
+    const candidate = join(dir, "node_modules", name);
+    if (existsSync(join(candidate, "package.json")))
+      return realpathSync(candidate);
+    if (dir === dirname(dir))
+      throw new Error(`Missing locked dependency ${name} from ${from}`);
+  }
+}
+function compatible(pkg) {
+  return (
+    (!pkg.os || pkg.os.includes(process.platform)) &&
+    (!pkg.cpu || pkg.cpu.includes(process.arch)) &&
+    (!pkg.libc || pkg.libc.includes("glibc"))
+  );
+}
+function copy(name, from, dest, ancestors = new Set()) {
+  const source = locate(name, from);
+  const pkg = JSON.parse(readFileSync(join(source, "package.json")));
+  if (!compatible(pkg)) return;
+  if (ancestors.has(source)) throw new Error(`Dependency cycle at ${source}`);
+  const target = join(dest, "node_modules", name);
+  mkdirSync(dirname(target), { recursive: true });
+  cpSync(source, target, {
+    recursive: true,
+    dereference: true,
+    filter: (path) =>
+      path === source ||
+      !["node_modules", ".git"].includes(
+        path.slice(source.length + 1).split(/[\\/]/)[0],
+      ),
+  });
+  const chain = new Set([...ancestors, source]);
+  const optional = pkg.optionalDependencies || {};
+  for (const dependency of Object.keys({ ...pkg.dependencies, ...optional })) {
+    try {
+      locate(dependency, source);
+    } catch (error) {
+      if (dependency in optional) continue;
+      throw error;
+    }
+    copy(dependency, source, target, chain);
+  }
+}
+for (const name of roots) copy(name, root, app);
+// Bun bundles Sharp JS but leaves its computed @img native requires unresolved.
+const sharp = locate("sharp", root);
+const sharpPackage = JSON.parse(readFileSync(join(sharp, "package.json")));
+for (const name of Object.keys(sharpPackage.optionalDependencies || {})) {
+  try {
+    locate(name, sharp);
+  } catch {
+    continue;
+  }
+  copy(name, sharp, app);
+}
+
+// Retain license notices for code in the JS bundle as well as external modules.
+function licenses(dir, destination) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory() && entry.name !== ".bin")
+      licenses(path, join(destination, entry.name));
+    else if (
+      entry.isFile() &&
+      /^(licen[sc]e|copying|notice)([.-]|$)/i.test(entry.name)
+    ) {
+      mkdirSync(destination, { recursive: true });
+      cpSync(path, join(destination, entry.name));
+    }
+  }
+}
+licenses(join(root, "node_modules"), join(app, "third-party-licenses"));

package/skills/finding-agents/SKILL.md

@@ -30,6 +30,7 @@ letta agents list [options]
 | `--tags <tag1,tag2>` | Filter by tags (comma-separated) |
 | `--match-all-tags` | Require ALL tags (default: ANY) |
 | `--include-blocks` | Include agent.blocks in response |
+| `--shared` | List agents shared with the current user |
 | `--limit <n>` | Max results (default: 20) |
 
 ## Common Patterns
@@ -44,14 +45,17 @@ letta agents list --tags "origin:letta-code"
 
 This is useful when the user is looking for agents they've worked with in Letta Code CLI sessions.
 
-### Finding All Agents
+### Finding All Accessible Agents
 
-If the user has agents created outside Letta Code (via ADE, SDK, etc.), search without the tag filter:
+List agents owned by the current user, then list agents shared with them:
 
 ```bash
 letta agents list
+letta agents list --shared
 ```
 
+Use `--query <text>` with either command to search by name.
+
 ## Examples
 
 **List all agents (up to 20):**

package/skills/letta-guide/SKILL.md

@@ -34,7 +34,8 @@ helper below fetches the live index first, so you pick a URL that exists.
    The helper retrieves `https://docs.letta.com/llms.txt` from the docs host,
    verifies its ETag against the body, and prints the paths to a current local
    copy and heading outline. Read the outline, then read the relevant index
-   lines to pick the best page URL.
+   lines and their applicability labels to pick a page matching the user's
+   backend and interface (see below).
 3. **Fetch the specific page directly.** Pass the exact canonical URL from the
    index back to the same helper, for example:
 
@@ -43,7 +44,8 @@ helper below fetches the live index first, so you pick a URL that exists.
      --docs-url "https://docs.letta.com/configuration/models/index.md"
    ```
 
-   Read the returned docs path before running the helper for another URL. The
+   Read the returned docs path, including its frontmatter, before applying its
+   instructions or running the helper for another URL. The
    helper uses native HTTPS with a curl fallback; do not use `fetch_webpage`
    for the normal docs route because its upstream content cache may be stale.
    Cite the public doc URL so the user can go deeper.
@@ -53,6 +55,23 @@ helper below fetches the live index first, so you pick a URL that exists.
    give your best answer, and clearly mark it as possibly out of date with a
    link to https://docs.letta.com. Never silently fall back to memory.
 
+## Match documentation to the user's setup
+
+Read each page's `applies_to` frontmatter before using its instructions:
+
+```yaml
+applies_to:
+  backends: [cloud, local]
+  interfaces: [web, desktop, cli, sdk]
+```
+
+- **Backends describe agent state, not the computer running tools.** `cloud`
+  means Letta Cloud; `local` means a user-managed backend.
+- **Interfaces** refer to the user's current interface: chat.letta.com (`web`,
+  cloud-only), CLI, Desktop, or SDK.
+- Do NOT use context from files marked `status: legacy` unless providing
+  historical context.
+
 ## Inspect or change your model from the CLI
 
 - `letta model list [--byok | --hosted]` lists available models.

package/skills/self-configuration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: self-configuration
-description: Inspect or modify Letta Code's own memory, model, context window, system prompt, compaction, permissions, toolsets, mods, skills, channels, schedules, agent secrets, and local runtime settings. Use when the user asks how this agent or conversation is configured, asks you to change how you behave or how the harness runs you, or renames you.
+description: Inspect or modify Letta Code's own memory, model, context window, system prompt, compaction, permissions, toolsets, mods, skills, channels, schedules, agent secrets, and local runtime settings. Use when the user asks how this agent or conversation is configured, asks about account usage, remaining credits, or model quota, asks you to change how you behave or how the harness runs you, or renames you.
 license: MIT
 ---
 
@@ -53,6 +53,16 @@ Local settings, server state, and the current process are different sources of t
 - `letta model set [model_handle] [--reasoning <reasoning-option>] [--default]` changes the current conversation's model or reasoning; add `--default` only when the user asks for the agent default.
 - `letta model get [--default]` gets the current model configuration; `--default` gets the agent's default configuration.
 
+### Account credits and model quota
+
+Run `letta usage` for a Markdown overview of the current plan, credit balance, and `letta/*` model quota (`lettaTier` only). Report the server's bucket (`full`, `high`, `medium`, `low`, or `empty`) and quota/daily reset timestamps as-is; do not infer exact requests or percentages. Amounts are credits, not dollars; preserve negative balances. An omitted daily reset is shown as unavailable.
+
+The command uses CLI auth and respects `LETTA_API_KEY`/`LETTA_BASE_URL`, not agent or conversation selectors. Credits belong to the organization; user-scoped quota belongs to the authenticated user, not necessarily the person chatting with the agent. In local mode, use `letta --backend cloud usage` only when the user wants Cloud account usage.
+
+Use `letta model list` for available models; credits and quota buckets do not guarantee inference availability. `letta usage` does not include session token statistics; the interactive `/usage` command is a separate surface. If either lookup fails, the command exits nonzero without partial usage. Treat that as unavailable data, not zero credits or exhausted quota.
+
+### Harness and server settings
+
 Use the secret-safe local/runtime report for harness settings, permissions, and backend diagnostics:
 
 ```bash

package/skills/converting-mcps-to-skills/SKILL.md

@@ -1,202 +0,0 @@
----
-name: converting-mcps-to-skills
-description: Connect to MCP (Model Context Protocol) servers and create skills for repeated use. Load when a user wants to use an MCP server, connect to external tools via MCP, or when they mention MCP, model context protocol, or specific MCP servers.
----
-
-# Converting MCP Servers to Skills
-
-Letta Code is not itself an MCP client, but as a general computer-use agent, you can easily connect to any MCP server using the scripts in this skill.
-
-## What is MCP?
-
-MCP (Model Context Protocol) is a standard for exposing tools to AI agents. MCP servers provide tools via JSON-RPC, either over:
-- **HTTP** - Server running at a URL (e.g., `http://localhost:3001/mcp`)
-- **stdio** - Server runs as a subprocess, communicating via stdin/stdout
-
-## Quick Start: Connecting to an MCP Server
-
-### Step 1: Determine the transport type
-
-Ask the user:
-- Is it an HTTP server (has a URL)?
-- Is it a stdio server (runs via command like `npx`, `node`, `python`)?
-
-### Step 2: Test the connection
-
-**For HTTP servers:**
-```bash
-npx tsx <SKILL_DIR>/scripts/mcp-http.ts <url> list-tools
-
-# With auth header
-npx tsx <SKILL_DIR>/scripts/mcp-http.ts <url> --header "Authorization: Bearer KEY" list-tools
-```
-Where `<SKILL_DIR>` is the Skill Directory shown when the skill was loaded (visible in the injection header).
-
-**For stdio servers:**
-```bash
-npx tsx <SKILL_DIR>/scripts/mcp-stdio.ts "<command>" list-tools
-
-# Examples
-npx tsx <SKILL_DIR>/scripts/mcp-stdio.ts "npx -y @modelcontextprotocol/server-filesystem ." list-tools
-npx tsx <SKILL_DIR>/scripts/mcp-stdio.ts "python server.py" list-tools
-```
-
-### Step 3: Explore available tools
-
-```bash
-# List all tools
-... list-tools
-
-# Get schema for a specific tool
-... info <tool-name>
-
-# Test calling a tool
-... call <tool-name> '{"arg": "value"}'
-```
-
-## Creating a Dedicated Skill
-
-When an MCP server will be used repeatedly, create a dedicated skill for it. This makes future use easier and documents the server's capabilities.
-
-### Decision: Simple vs Rich Skill
-
-**Simple skill** (just SKILL.md):
-- Good for straightforward servers
-- Documents how to use the parent skill's scripts with this specific server
-- No additional scripts needed
-
-**Rich skill** (SKILL.md + scripts/):
-- Good for frequently-used servers
-- Includes convenience wrapper scripts with defaults baked in
-- Provides a simpler interface than the generic scripts
-
-See `references/skill-templates.md` for templates.
-
-## Built-in Scripts Reference
-
-### mcp-http.ts - HTTP Transport
-
-Connects to MCP servers over HTTP. No dependencies required.
-
-```bash
-npx tsx mcp-http.ts <url> [options] <command> [args]
-
-Commands:
-  list-tools              List available tools
-  list-resources          List available resources
-  info <tool>             Show tool schema
-  call <tool> '<json>'    Call a tool
-  login                   Run OAuth flow and cache tokens for this server
-  logout                  Clear cached OAuth tokens for this server
-
-Options:
-  --header "K: V"         Add HTTP header (repeatable). Disables auto-OAuth.
-  --auth <mode>           "auto" (default), "oauth", or "none"
-  --timeout <ms>          Request timeout (default: 30000)
-```
-
-**Examples:**
-```bash
-# Basic usage
-npx tsx mcp-http.ts http://localhost:3001/mcp list-tools
-
-# With static bearer authentication
-npx tsx mcp-http.ts http://localhost:3001/mcp --header "Authorization: Bearer KEY" list-tools
-
-# OAuth-protected server (opens a browser to sign in, then caches tokens)
-npx tsx mcp-http.ts https://example.com/mcp login
-npx tsx mcp-http.ts https://example.com/mcp list-tools
-
-# Call a tool
-npx tsx mcp-http.ts http://localhost:3001/mcp call vault '{"action":"search","query":"notes"}'
-```
-
-**OAuth support:**
-When a server returns `401 WWW-Authenticate: Bearer ...` and no static
-`Authorization` header was supplied, `mcp-http.ts` will automatically:
-
-1. Discover the authorization server via `resource_metadata`, the
-   `realm=` param, or the server's own origin (`.well-known/oauth-authorization-server`
-   then `.well-known/openid-configuration`).
-2. Dynamically register a public client with PKCE (`token_endpoint_auth_method: none`).
-3. Open the system browser to the authorization endpoint, catch the redirect
-   on a `127.0.0.1` loopback port, and exchange the code for tokens.
-4. Cache the token set (and the registered client) at
-   `~/.letta/mcp-oauth/<host>_<path>.json` with `0600` perms.
-5. Auto-refresh expired access tokens using the stored refresh token before
-   each request; if refresh fails, it re-runs the browser flow once.
-
-Use `login` to run the flow explicitly (e.g. as a first step in a skill's
-setup) and `logout` to clear cached tokens. Passing an explicit
-`--header "Authorization: ..."` disables auto-OAuth so you stay in control.
-Pass `--auth none` to force static-only behavior.
-
-### mcp-stdio.ts - stdio Transport
-
-Connects to MCP servers that run as subprocesses. No dependencies required.
-
-```bash
-npx tsx mcp-stdio.ts "<command>" [options] <action> [args]
-
-Actions:
-  list-tools              List available tools
-  list-resources          List available resources
-  info <tool>             Show tool schema
-  call <tool> '<json>'    Call a tool
-
-Options:
-  --env "KEY=VALUE"       Set environment variable (repeatable)
-  --cwd <path>            Set working directory
-  --timeout <ms>          Request timeout (default: 30000)
-```
-
-**Examples:**
-```bash
-# Filesystem server
-npx tsx mcp-stdio.ts "npx -y @modelcontextprotocol/server-filesystem ." list-tools
-
-# With environment variable
-npx tsx mcp-stdio.ts "node server.js" --env "API_KEY=xxx" list-tools
-
-# Call a tool
-npx tsx mcp-stdio.ts "python server.py" call read_file '{"path":"./README.md"}'
-```
-
-## Common MCP Servers
-
-Here are some well-known MCP servers:
-
-| Server | Transport | Command/URL |
-|--------|-----------|-------------|
-| Filesystem | stdio | `npx -y @modelcontextprotocol/server-filesystem <path>` |
-| GitHub | stdio | `npx -y @modelcontextprotocol/server-github` |
-| Brave Search | stdio | `npx -y @modelcontextprotocol/server-brave-search` |
-| obsidian-mcp-plugin | HTTP | `http://localhost:3001/mcp` |
-
-## Troubleshooting
-
-**"Cannot connect" error:**
-- For HTTP: Check the URL is correct and server is running
-- For stdio: Check the command works when run directly in terminal
-
-**"Authentication required" error:**
-- Add `--header "Authorization: Bearer YOUR_KEY"` for HTTP servers using static bearers
-- Or `--env "API_KEY=xxx"` for stdio servers that need env vars
-- For OAuth-protected HTTP servers, just run any command (or `login`) — the helper
-  will do PKCE + dynamic client registration and cache tokens under
-  `~/.letta/mcp-oauth/`. Delete that file (or run `logout`) to force a re-login.
-
-**OAuth issues:**
-- "Could not discover OAuth server metadata": the server didn't include
-  `resource_metadata` and its origin doesn't serve `.well-known/oauth-authorization-server`
-  or `.well-known/openid-configuration`. Fall back to a static bearer, or point the
-  helper at the auth server manually via a custom skill.
-- "Dynamic client registration failed": the auth server disables open DCR.
-  You'll need to pre-register a client and pass its `client_id` (and any required
-  credentials) via headers, or wrap this skill with a server-specific one.
-- "state mismatch" / callback timeout: another process may be holding the browser
-  callback; re-run and complete the sign-in in the newly opened tab.
-
-**Tool call fails:**
-- Use `info <tool>` to see the expected input schema
-- Ensure JSON arguments match the schema