Metadata-Version: 2.4
Name: mcat-cli
Version: 0.1.4
Summary: The model-context access tool for agents and humans
Project-URL: Repository, https://github.com/briceyan/mcat-cli
Author-email: Brice Yan <briceyan3.0@gmail.com>
Keywords: agent,cli,mcp,mcp debugging,model context protocol,model-context-protocol,oauth,progressive disclosure,resources,tool calling
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: json5<1.0,>=0.12
Requires-Dist: typer<1.0,>=0.12
Description-Content-Type: text/markdown

# mcat-cli

The model-context access tool for agents and humans.

`mcat` is a concise CLI for:
- OAuth authorization against MCP servers
- MCP session initialization
- tool listing/calling
- resource listing/reading
- prompt listing/fetching

## Install

```bash
pip install mcat-cli
```

Requires Python 3.11+.

## Quick Start

1) Start OAuth authorization:

```bash
mcat auth start https://your-mcp-server.example/mcp \
  -k token.json \
  --state auth.json
```

This returns a pending result with action details (URL/code).  
Use `--wait` if you want to block until completion.

2) Complete authorization and store token:

```bash
mcat auth continue --state auth.json -k token.json
```

If `token.json` already exists, add `-o/--overwrite`.

3) Initialize an MCP session:

```bash
mcat init https://your-mcp-server.example/mcp -k token.json -o session.json
```

4) Call MCP tools/resources/prompts:

```bash
mcat tool list -s session.json
mcat tool call my_tool -i '{"foo":"bar"}' -s session.json

mcat resource list -s session.json
mcat resource list-template -s session.json
mcat resource read my://resource -s session.json

mcat prompt list -s session.json
mcat prompt get summarize -i '{"topic":"release notes"}' -s session.json
```

## KEY_REF Formats

`-k/--key-ref` accepts:
- `env://VAR`
- `.env://path:VAR`
- `.env://:VAR` (shortcut for `.env://.env:VAR`)
- `json://path`
- bare file path (same as `json://path`)

For auth flows, token output is written back to `--key-ref`.
- Missing destination is allowed (first-time auth).
- Existing destination requires `-o/--overwrite`.

## Output Contract

Most commands write compact JSON to stdout:

```json
{"ok":true,"result":{}}
```

```json
{"ok":false,"error":"message"}
```

Exception: `mcat resource read ... -o -` writes decoded bytes to stdout.

## Logging

Logs are opt-in:

```bash
mcat --log auth --log-stderr auth start ...
mcat --log app --log mcp --log-file mcat.log tool list -s session.json
```
