@letta-ai/letta-code 0.32.10 → 0.32.12

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

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

@@ -1,141 +0,0 @@
-# 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 .";
-```