# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build Commands

```bash
cargo build              # Debug build
cargo build --release    # Release build (LTO + stripped)
cargo test               # Run all tests
cargo test test_name     # Run a single test
cargo install --path .   # Install locally
```

Or use the Makefile:
```bash
make build      # Debug build
make release    # Release build
make test       # Run tests
make install    # Install globally
make publish    # Bump version and publish to crates.io
make binary-size  # Show release binary size
```

## Architecture

CLI application with modular structure for MCP server routing and built-in servers.

### File Structure

- `src/main.rs` - CLI entry point, package routing logic
- `src/servers/mod.rs` - Server module exports
- `src/servers/common.rs` - Shared MCP types (`JsonRpcRequest`, `JsonRpcResponse`, `McpServer` trait)
- `src/servers/shell.rs` - Shell command execution server
- `src/servers/filesystem.rs` - Filesystem operations server
- `src/servers/sql.rs` - SQL database query server
- `src/servers/browser.rs` - Browser automation server (Chrome DevTools Protocol)
- `src/http/mod.rs` - HTTP transport module exports
- `src/http/server.rs` - Axum HTTP server setup, TLS config
- `src/http/handlers.rs` - POST/GET/DELETE endpoint handlers
- `src/http/session.rs` - MCP session management
- `src/http/tls.rs` - TLS config and self-signed certificate generation

### Core Flow (Package Routing)

1. **Package Discovery**: Searches crates.io, PyPI, and npm APIs for packages
2. **Popularity Sorting**: Results sorted by download count (most popular first)
3. **Cache**: User selections stored in `~/.cache/mcpz/package_mapping.toml`
4. **Execution**: Runs via `npx -y`, `uvx`, or `cargo install` + binary execution

### Key Types

- `PackageType` - Enum: `Cargo`, `Python`, `Npm` with runner/install info
- `PackageInfo` - Package metadata including downloads count
- `PackageCache` - TOML-serialized HashMap mapping search terms to (package_name, type)
- `McpServer` trait - Common interface for built-in MCP servers

### Registry APIs

- **crates.io**: `https://crates.io/api/v1/crates?q={query}` (requires User-Agent)
- **PyPI**: `https://pypi.org/pypi/{package}/json` + `https://pypistats.org/api/packages/{package}/recent`
- **npm**: `npm search --json` CLI + `https://api.npmjs.org/downloads/point/last-month/{package}`

### CLI Commands

- `run <package> [--first]` - Run package (prompts if multiple matches, `--first` picks most popular)
- `search <package>` - Non-interactive search display
- `pick <package>` - Interactive selection saved to cache
- `clear-cache` - Remove cached mappings
- `server list` - List available built-in MCP servers
- `server shell` - Run built-in MCP shell server
- `server filesystem` - Run built-in MCP filesystem server
- `server sql` - Run built-in MCP SQL server
- `server browser` - Run built-in MCP browser automation server

### Built-in MCP Servers

#### Shell Server (`server shell`)
Executes shell commands via JSON-RPC over stdio.
- `ShellServerConfig` - Working directory, timeout, shell path, allow/deny patterns
- Sandboxing via `--allow`/`--deny` patterns (deny takes precedence)
- Single tool: `execute_command`

#### Filesystem Server (`server filesystem`)
Provides filesystem operations with directory sandboxing.
- `FilesystemServerConfig` - Allowed directories list
- Path validation prevents access outside allowed directories (including symlink attacks)
- Tools: `read_file`, `read_multiple_files`, `write_file`, `edit_file`, `create_directory`, `list_directory`, `list_directory_with_sizes`, `directory_tree`, `move_file`, `search_files`, `get_file_info`, `list_allowed_directories`

#### SQL Server (`server sql`)
Query SQL databases (PostgreSQL, MySQL, MariaDB, SQLite) via MCP.
- `SqlServerConfig` - Connection string, access mode (readonly/fullaccess), timeout
- `AccessMode::ReadOnly` - Only SELECT, SHOW, DESCRIBE, EXPLAIN allowed
- `AccessMode::FullAccess` - All SQL statements allowed
- Tools: `query`, `list_tables`, `describe_table`, `execute` (fullaccess only)
- Uses `sqlx` with `AnyPool` for runtime database selection

```bash
mcpz server sql --connection postgres://user:pass@localhost:5432/db --readonly
mcpz server sql --connection mysql://user:pass@localhost:3306/db --fullaccess
mcpz server sql --connection sqlite:///path/to/file.db --readonly
mcpz server sql --connection sqlite::memory: --fullaccess
```

#### Browser Server (`server browser`)
Browser automation via Chrome DevTools Protocol.
- `BrowserServerConfig` - CDP port, Chrome path, timeout, screenshot directory, HTTP mode
- Manages Chrome process lifecycle (starts/stops Chrome)
- Connects to Chrome tabs via WebSocket
- Screenshots: saves to file (stdio mode) or returns base64 (HTTP mode)
- Tools: `start_browser`, `stop_browser`, `open_url`, `get_page`, `get_page_as_markdown`, `get_screenshot`, `execute_script`

```bash
mcpz server browser                       # Start browser server (CDP port 9222)
mcpz server browser -p 9333               # Custom CDP port
mcpz server browser --verbose             # Enable debug logging
mcpz server browser --http --port 3000    # HTTP transport mode
```

**Tool: start_browser**
- `headless` (boolean, default: false) - Run Chrome in headless mode (no visible window)

**Tool: open_url**
- `url` (string, required) - URL to navigate to
- `wait_time` (integer, default: 3) - Seconds to wait after page load

**Tool: get_screenshot**
- `full_page` (boolean, default: false) - Capture full page or just viewport
- Returns file path in stdio mode, base64 image in HTTP mode

**Tool: execute_script**
- `script` (string, required) - JavaScript code to execute in browser context

### HTTP Transport (`--http` flag)

Built-in servers can run over HTTP instead of stdio using the `--http` flag. This implements the MCP Streamable HTTP transport (2025-03-26 spec).

#### HTTP Options
- `--http` - Enable HTTP transport instead of stdio
- `-p, --port <PORT>` - Port to listen on (default: 3000)
- `--host <HOST>` - Bind address (default: 127.0.0.1)
- `--tls` - Enable HTTPS (auto-generates self-signed cert if no --cert/--key)
- `--cert <PATH>` - TLS certificate path (PEM format)
- `--key <PATH>` - TLS private key path (PEM format)
- `--origin <ORIGINS>` - Allowed CORS origins (comma-separated)

#### Examples
```bash
mcpz server shell --http                    # HTTP on localhost:3000
mcpz server filesystem --http -p 8080       # HTTP on port 8080
mcpz server shell --http --tls              # HTTPS with self-signed cert
mcpz server filesystem --http --tls --cert cert.pem --key key.pem  # HTTPS with custom cert
```

#### HTTP Module Structure
- `HttpServerConfig` - Port, host, TLS config, allowed origins
- `TlsConfig` - Certificate/key loading or self-signed generation
- `SessionManager` - UUID-based session tracking with TTL
- `AppState` - Wraps `McpServer` trait for HTTP handlers
- Endpoint: `POST/GET/DELETE /mcp` per MCP Streamable HTTP spec

### Detection Logic

1. Packages starting with `@` → npm only
2. Otherwise: search all registries for exact matches
3. If multiple exact matches: prompt user (or pick most popular with `--first`)
4. Single match: use automatically
