Metadata-Version: 2.3
Name: mcphee
Version: 0.1.0
Summary: Interactive MCP client CLI — connect to any MCP server via stdio, SSE, or HTTP
Keywords: mcp,model-context-protocol,cli,client
Author: David Gwartney
Author-email: David Gwartney <david.gwartney@gmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Dist: click>=8.3.2
Requires-Dist: fastmcp>=3.2.4,<4
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: rich>=15.0.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/dgwartney/mcphee
Project-URL: Repository, https://github.com/dgwartney/mcphee
Project-URL: Issues, https://github.com/dgwartney/mcphee/issues
Description-Content-Type: text/markdown

# mcphee

[![CI](https://github.com/dgwartney/mcphee/actions/workflows/ci.yml/badge.svg)](https://github.com/dgwartney/mcphee/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/mcphee.svg)](https://pypi.org/project/mcphee/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

**mcphee** is an interactive CLI client for [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers.
Connect to any MCP server — local (stdio) or remote (SSE / Streamable HTTP) — and explore its tools, resources,
and prompts in a rich interactive REPL.

---

## Features

- **Universal transport support** — stdio, SSE, and Streamable HTTP
- **Interactive REPL** — Vi mode (default) or Emacs mode with full line editing
- **Tab completion** — fuzzy-match tool names, resource URIs, prompt names, and their parameters
- **Auto-suggestions** — fish-shell style history suggestions as you type
- **Persistent history** — across sessions, XDG-compliant location
- **Named profiles** — save connection configs in `~/.config/mcphee/profiles.toml`
- **Rich output** — syntax-highlighted JSON, tables, and panels; toggle to raw JSON with `#json`
- **Meta-commands** — `#refresh`, `#export`, `#timeout`, `#debug`, and more

---

## Installation

### Recommended: uv tool (isolated, no venv management)

```bash
# From PyPI
uv tool install mcphee

# From GitHub (latest main)
uv tool install git+https://github.com/dgwartney/mcphee

# Specific tag or commit
uv tool install "git+https://github.com/dgwartney/mcphee@v0.1.0"

# From a local clone
uv tool install .
```

After installation the `mcphee` command is available globally without activating a virtual environment. Upgrade with:

```bash
uv tool upgrade mcphee
```

### pip

```bash
pip install mcphee
```

---

## Quick Start

```bash
# Connect to a local stdio MCP server
mcphee connect --stdio 'npx -y @modelcontextprotocol/server-filesystem /tmp'

# Connect via SSE with an API key header
mcphee connect --sse http://localhost:8080/sse --header x-api-key=secret

# Connect via Streamable HTTP
mcphee connect --http http://localhost:8080/mcp

# Connect using a saved profile
mcphee connect --profile myserver
```

Once connected you'll enter the interactive REPL:

```
╭─ mcphee ──────────────────────────────────────────────────────╮
│ Connected via http                                            │
│ http://localhost:8080/mcp                                     │
│ Type help for commands or exit to quit.                       │
╰───────────────────────────────────────────────────────────────╯
> list tools
> call read_file path=/tmp/notes.txt
> list resources
> read file:///tmp/notes.txt
> list prompts
> prompt summarize text="hello world"
> exit
```

---

## REPL Command Reference

| Command | Syntax | Description |
|---------|--------|-------------|
| `list tools` | `list tools` | List all available tools |
| `list resources` | `list resources` | List all available resources |
| `list prompts` | `list prompts` | List all available prompts |
| `call` | `call <tool> [key=value ...]` | Invoke a tool with arguments |
| `read` | `read <uri>` | Read a resource by URI |
| `prompt` | `prompt <name> [key=value ...]` | Get a prompt with arguments |
| `help` | `help` | Show command reference |
| `exit` / `quit` | `exit` | Disconnect and exit |

### Argument syntax

Tool and prompt arguments are passed as `key=value` pairs:

```
> call read_file path=/tmp/foo.txt
> call search query="hello world" limit=10
> prompt summarize text="Some long text here" language=en
```

Values are automatically typed: `true`/`false` to bool, integers to int, JSON arrays/objects to parsed.

---

## Meta-Command Reference

Meta-commands begin with `#` and control the REPL session:

| Command | Syntax | Description |
|---------|--------|-------------|
| `#clear` | `#clear` | Clear the terminal screen |
| `#refresh` | `#refresh` | Re-fetch tools/resources/prompts, rebuild completions |
| `#json` | `#json` | Toggle JSON vs Rich pretty output |
| `#history` | `#history [N]` | Show last N commands (default 20) |
| `#export` | `#export [path]` | Export last result to a JSON file |
| `#timeout` | `#timeout <seconds>` | Set request timeout |
| `#debug` | `#debug` | Toggle verbose debug output |
| `#help` | `#help` | Show meta-command reference |

---

## Profile Management

Save connection configs so you don't have to retype them:

```bash
# Add a profile interactively
mcphee profile add myserver

# List all profiles
mcphee profile list

# Remove a profile
mcphee profile remove myserver
```

Profile TOML schema (`~/.config/mcphee/profiles.toml`):

```toml
[profiles.lumen]
mode = "http"
url = "http://localhost:8080/mcp"
[profiles.lumen.headers]
x-api-key = "secret"

[profiles.filesystem]
mode = "stdio"
command = "npx -y @modelcontextprotocol/server-filesystem /tmp"

[profiles.weather]
mode = "sse"
url = "http://weather-api.internal/sse"
```

---

## Configuration Paths (XDG)

mcphee follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/):

| Data | Path |
|------|------|
| Profiles | `$XDG_CONFIG_HOME/mcphee/profiles.toml` (default: `~/.config/mcphee/profiles.toml`) |
| History | `$XDG_DATA_HOME/mcphee/history` (default: `~/.local/share/mcphee/history`) |

---

## Key Bindings

The REPL uses **Vi mode** by default. Use `--emacs` to switch to Emacs mode.

| Mode | Keys | Action |
|------|------|--------|
| Vi normal | `h l w b 0 $` | Move cursor |
| Vi normal | `x dd u` | Delete / undo |
| Vi normal | `/` | Search forward |
| Both | Up / Down arrows | History recall |
| Both | `Ctrl+R` | Reverse history search |
| Vi insert | `Esc` | Switch to normal mode |

---

## Publishing to PyPI

Releases are published by the `Publish` GitHub Actions workflow (`.github/workflows/publish.yml`) using
PyPI Trusted Publishing (OIDC), so no API tokens are stored anywhere.

One-time setup on <https://pypi.org> (and <https://test.pypi.org> for dry runs), under
**Account → Publishing → Add a pending publisher**:

| Field | Value |
|---|---|
| PyPI Project Name | `mcphee` |
| Owner | `dgwartney` |
| Repository name | `mcphee` |
| Workflow name | `publish.yml` |
| Environment name | `pypi` (use `testpypi` on TestPyPI) |

To release:

1. Bump `version` in `pyproject.toml` (PyPI never accepts the same version twice).
2. Dry run: **Actions → Publish → Run workflow → target `testpypi`**, then install from TestPyPI:
   `uv tool install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ mcphee`
3. Publish: create a GitHub Release tagged `vX.Y.Z` — the workflow uploads to PyPI.

To build locally without publishing: `uv build` (writes `dist/mcphee-*.whl` and `.tar.gz`).

---

## License

MIT
