@letta-ai/letta-code 0.14.7 → 0.14.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.14.7",
+  "version": "0.14.9",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {
@@ -62,7 +62,7 @@
     "check": "bun run scripts/check.js",
     "dev": "bun --loader:.md=text --loader:.mdx=text --loader:.txt=text run src/index.ts",
     "build": "node scripts/postinstall-patches.js && bun run build.js",
-    "prepare": "bun run build",
+    "prepublishOnly": "bun run build",
     "postinstall": "node scripts/postinstall-patches.js"
   },
   "lint-staged": {

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

@@ -0,0 +1,171 @@
+---
+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-path>/scripts/mcp-http.ts <url> list-tools
+
+# With auth header
+npx tsx <skill-path>/scripts/mcp-http.ts <url> --header "Authorization: Bearer KEY" list-tools
+```
+
+**For stdio servers:**
+```bash
+# First, install dependencies (one time)
+cd <skill-path>/scripts && npm install
+
+# Then connect
+npx tsx <skill-path>/scripts/mcp-stdio.ts "<command>" list-tools
+
+# Examples
+npx tsx <skill-path>/scripts/mcp-stdio.ts "npx -y @modelcontextprotocol/server-filesystem ." list-tools
+npx tsx <skill-path>/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
+
+Options:
+  --header "K: V"         Add HTTP header (repeatable)
+  --timeout <ms>          Request timeout (default: 30000)
+```
+
+**Examples:**
+```bash
+# Basic usage
+npx tsx mcp-http.ts http://localhost:3001/mcp list-tools
+
+# With authentication
+npx tsx mcp-http.ts http://localhost:3001/mcp --header "Authorization: Bearer KEY" list-tools
+
+# Call a tool
+npx tsx mcp-http.ts http://localhost:3001/mcp call vault '{"action":"search","query":"notes"}'
+```
+
+### mcp-stdio.ts - stdio Transport
+
+Connects to MCP servers that run as subprocesses. Requires npm install first.
+
+```bash
+# One-time setup
+cd <skill-path>/scripts && npm install
+
+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
+- Or `--env "API_KEY=xxx"` for stdio servers that need env vars
+
+**stdio "npm install" error:**
+- Run `cd <skill-path>/scripts && npm install` first
+- The stdio client requires the MCP SDK
+
+**Tool call fails:**
+- Use `info <tool>` to see the expected input schema
+- Ensure JSON arguments match the schema

package/skills/converting-mcps-to-skills/references/skill-templates.md

@@ -0,0 +1,141 @@
+# Skill Templates for MCP Servers
+
+When to create a dedicated skill:
+- **One-off use**: No skill needed - just use `converting-mcps-to-skills` scripts directly
+- **Repeated use**: Create a self-contained skill with customized scripts
+
+Skills should be self-contained per the [Agent Skills spec](https://agentskills.io/specification).
+
+## Naming Rules (from Agent Skills spec)
+
+The `name` field must:
+- Be lowercase letters, numbers, and hyphens only (`a-z`, `0-9`, `-`)
+- Be 1-64 characters
+- Not start or end with a hyphen
+- Not contain consecutive hyphens (`--`)
+- Match the parent directory name exactly
+
+Examples: `using-github-mcp`, `mcp-filesystem`, `slack-mcp`
+
+## Skill Template
+
+Use this template when creating a self-contained skill for an MCP server.
+
+### Directory Structure
+
+```
+using-<server-name>/
+├── SKILL.md
+└── scripts/
+    └── <server>.ts    # Customized client (copied from converting-mcps-to-skills)
+```
+
+### SKILL.md Template
+
+```markdown
+---
+name: using-<server-name>
+description: <What the server does>. Use when <trigger conditions>.
+# Optional fields:
+# license: MIT
+# compatibility: Requires network access to <service>
+---
+
+# Using <Server Name>
+
+<Brief description>
+
+## Prerequisites
+
+- <Requirements>
+
+## Quick Start
+
+```bash
+# Set API key (if needed)
+export <SERVER>_API_KEY="your-key"
+
+# List tools
+npx tsx <skill-path>/scripts/<server>.ts list-tools
+
+# Call a tool
+npx tsx <skill-path>/scripts/<server>.ts call <tool> '{"arg":"value"}'
+```
+
+## Available Tools
+
+<Document tools with examples>
+
+## Environment Variables
+
+- `<SERVER>_API_KEY` - API key for authentication
+- `<SERVER>_URL` - Override server URL (default: <default-url>)
+```
+
+### Script Template (scripts/<server>.ts)
+
+Copy the HTTP client from `converting-mcps-to-skills/scripts/mcp-http.ts` (or `mcp-stdio.ts` for stdio servers) and customize:
+
+1. Set `DEFAULT_URL` to this server's URL
+2. Rename the API key env var (e.g., `GITHUB_MCP_KEY` instead of generic)
+3. Optionally simplify the CLI for common operations
+
+The copied code is self-contained - no external dependencies for HTTP transport.
+
+```typescript
+#!/usr/bin/env npx tsx
+/**
+ * <Server Name> CLI - Self-contained MCP client
+ */
+
+// Customize these for your server
+const DEFAULT_URL = "<server-url>";
+const API_KEY = process.env.<SERVER>_API_KEY;
+
+// Copy the rest of mcp-http.ts here and adjust as needed
+// ...
+```
+
+## Example: Self-Contained Filesystem Skill
+
+A complete example of a self-contained skill for the MCP filesystem server:
+
+```
+using-mcp-filesystem/
+├── SKILL.md
+└── scripts/
+    └── filesystem.ts    # Copied and customized from mcp-stdio.ts
+```
+
+**SKILL.md:**
+```markdown
+---
+name: using-mcp-filesystem
+description: Access local filesystem via MCP. Use when user wants to read, write, or search files via MCP protocol.
+---
+
+# Using MCP Filesystem Server
+
+Access local files via the official MCP filesystem server.
+
+## Quick Start
+
+```bash
+npx tsx <skill-path>/scripts/filesystem.ts list-tools
+npx tsx <skill-path>/scripts/filesystem.ts call read_file '{"path":"./README.md"}'
+```
+
+## Available Tools
+
+- `read_file` - Read file contents
+- `write_file` - Write content to file
+- `list_directory` - List directory contents
+- `search_files` - Search for files by pattern
+- `get_file_info` - Get file metadata
+```
+
+**scripts/filesystem.ts:**
+Copy `converting-mcps-to-skills/scripts/mcp-stdio.ts` and set the default command to:
+```typescript
+const DEFAULT_COMMAND = "npx -y @modelcontextprotocol/server-filesystem .";
+```