@sammorrowdrums/mcpi 0.70.9 → 0.85.0

package/docs/providers.md

@@ -1,6 +1,6 @@
 # Providers
 
-Pi supports subscription-based providers via OAuth and API key providers via environment variables or auth file. For each provider, pi knows all available models. The list is updated with every pi release.
+mcpi supports subscription-based providers via OAuth and API key providers via environment variables or auth file. Built-in catalogs ship with mcpi; configured providers may refresh newer catalogs and cache them in the cache directory's `models-store.json` for offline use.
 
 ## Table of Contents
 
@@ -8,6 +8,7 @@ Pi supports subscription-based providers via OAuth and API key providers via env
 - [API Keys](#api-keys)
 - [Auth File](#auth-file)
 - [Cloud Providers](#cloud-providers)
+- [llama.cpp](#llamacpp)
 - [Custom Providers](#custom-providers)
 - [Resolution Order](#resolution-order)
 
@@ -15,30 +16,44 @@ Pi supports subscription-based providers via OAuth and API key providers via env
 
 Use `/login` in interactive mode, then select a provider:
 
-- Claude Pro/Max
 - ChatGPT Plus/Pro (Codex)
+- Claude Pro/Max
 - GitHub Copilot
-- Google Gemini CLI
-- Google Antigravity
+- xAI (Grok/X subscription)
+- OpenRouter (OAuth-minted API key billed from OpenRouter credits)
+- Radius
+
+Use `/logout` to clear credentials. Tokens are stored in the mcpi config directory's `auth.json` and auto-refresh when expired. OpenRouter instead mints a user-controlled API key that does not expire automatically.
 
-Use `/logout` to clear credentials. Tokens are stored in `~/.pi/agent/auth.json` and auto-refresh when expired.
+### OpenAI Codex
+
+- Requires ChatGPT Plus or Pro subscription
+- Officially endorsed by OpenAI: [Codex for OSS](https://developers.openai.com/community/codex-for-oss)
+
+### Claude Pro/Max
+
+Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party harness usage draws from [extra usage](https://claude.ai/settings/usage) and is billed per token, not against Claude plan limits.
 
 ### GitHub Copilot
 
 - Press Enter for github.com, or enter your GitHub Enterprise Server domain
 - If you get "model not supported", enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
 
-### Google Providers
+### xAI (Grok/X subscription)
 
-- **Gemini CLI**: Standard Gemini models via Cloud Code Assist
-- **Antigravity**: Sandbox with Gemini 3, Claude, and GPT-OSS models
-- Both free with any Google account, subject to rate limits
-- For paid Cloud Code Assist: set `GOOGLE_CLOUD_PROJECT` env var
+- Run `/login xai`, then select **Use a subscription**
+- `XAI_API_KEY` remains available through **Use an API key**
 
-### OpenAI Codex
+### OpenRouter
 
-- Requires ChatGPT Plus or Pro subscription
-- Personal use only; for production, use the OpenAI Platform API
+- Run `/login openrouter`, then select **Sign in with OpenRouter** to open the OpenRouter PKCE authorization flow
+- The authorization creates a user-controlled OpenRouter API key billed from your OpenRouter credits
+- On remote/headless machines (e.g. over SSH) the browser cannot reach the loopback callback; paste the final redirect URL (or the authorization code) into the login prompt instead
+- `OPENROUTER_API_KEY` remains available through **Use an API key**
+
+### Radius
+
+Radius is a dynamic `pi-messages` gateway. `/login radius` stores OAuth tokens in `auth.json`; the gateway catalog is refreshed independently and cached in `models-store.json`. Custom Radius gateways can be declared in `models.json` with `"oauth": "radius"` and a gateway `baseUrl`.
 
 ## API Keys
 
@@ -48,64 +63,123 @@ Use `/login` in interactive mode and select a provider to store an API key in `a
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
-pi
+mcpi
 ```
 
 | Provider | Environment Variable | `auth.json` key |
 |----------|----------------------|------------------|
 | Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
+| Ant Ling | `ANT_LING_API_KEY` | `ant-ling` |
 | Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
 | OpenAI | `OPENAI_API_KEY` | `openai` |
+| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
+| NVIDIA NIM | `NVIDIA_API_KEY` | `nvidia` |
 | Google Gemini | `GEMINI_API_KEY` | `google` |
+| Amazon Bedrock | `AWS_BEARER_TOKEN_BEDROCK` | `amazon-bedrock` |
 | Mistral | `MISTRAL_API_KEY` | `mistral` |
 | Groq | `GROQ_API_KEY` | `groq` |
 | Cerebras | `CEREBRAS_API_KEY` | `cerebras` |
+| Cloudflare AI Gateway | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_GATEWAY_ID`) | `cloudflare-ai-gateway` |
+| Cloudflare Workers AI | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`) | `cloudflare-workers-ai` |
 | xAI | `XAI_API_KEY` | `xai` |
 | OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
 | Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
-| ZAI | `ZAI_API_KEY` | `zai` |
+| ZAI Coding Plan (Global) | `ZAI_API_KEY` | `zai` |
+| ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` | `zai-coding-cn` |
 | OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
 | OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
+| Radius | `RADIUS_API_KEY` | `radius` |
 | Hugging Face | `HF_TOKEN` | `huggingface` |
 | Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
+| Together AI | `TOGETHER_API_KEY` | `together` |
+| Baseten | `BASETEN_API_KEY` | `baseten` |
 | Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
 | MiniMax | `MINIMAX_API_KEY` | `minimax` |
 | MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
+| Qwen Token Plan (existing catalog) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan` |
+| Qwen Token Plan (Individual) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan-individual` |
+| Qwen Token Plan (China) | `QWEN_TOKEN_PLAN_CN_API_KEY` | `qwen-token-plan-cn` |
+| Xiaomi MiMo | `XIAOMI_API_KEY` | `xiaomi` |
+| Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` | `xiaomi-token-plan-cn` |
+| Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` | `xiaomi-token-plan-ams` |
+| Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` | `xiaomi-token-plan-sgp` |
 
-Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/env-api-keys.ts).
+Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/SamMorrowDrums/mcpi/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/SamMorrowDrums/mcpi/blob/main/packages/ai/src/env-api-keys.ts).
 
 #### Auth File
 
-Store credentials in `~/.pi/agent/auth.json`:
+Store credentials in `$XDG_CONFIG_HOME/mcpi/auth.json` (fallback `~/.config/mcpi/auth.json`; `%APPDATA%\mcpi\auth.json` on Windows):
 
 ```json
 {
   "anthropic": { "type": "api_key", "key": "sk-ant-..." },
+  "ant-ling": { "type": "api_key", "key": "..." },
   "openai": { "type": "api_key", "key": "sk-..." },
+  "deepseek": { "type": "api_key", "key": "sk-..." },
+  "nvidia": { "type": "api_key", "key": "nvapi-..." },
   "google": { "type": "api_key", "key": "..." },
   "opencode": { "type": "api_key", "key": "..." },
-  "opencode-go": { "type": "api_key", "key": "..." }
+  "opencode-go": { "type": "api_key", "key": "..." },
+  "together": { "type": "api_key", "key": "..." },
+  "qwen-token-plan":  { "type": "api_key", "key": "sk-sp-..." },
+  "qwen-token-plan-individual": { "type": "api_key", "key": "sk-sp-..." },
+  "qwen-token-plan-cn": { "type": "api_key", "key": "sk-sp-..." },
+  "xiaomi": { "type": "api_key", "key": "..." },
+  "xiaomi-token-plan-cn":  { "type": "api_key", "key": "..." },
+  "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
+  "xiaomi-token-plan-sgp": { "type": "api_key", "key": "..." }
 }
 ```
 
+`qwen-token-plan-individual` uses the same international endpoint and `QWEN_TOKEN_PLAN_API_KEY` as
+`qwen-token-plan`, but limits the picker to the models documented for Individual subscriptions. The existing
+provider keeps its broader catalog for backward compatibility. When using `auth.json`, store the
+credential under the provider you select; an environment variable is shared by both international providers.
+
 The file is created with `0600` permissions (user read/write only). Auth file credentials take priority over environment variables.
 
+API key credentials can also include provider-scoped environment values. These values are used before process environment variables when resolving the credential key, provider/model headers, and provider configuration such as Cloudflare account IDs, Azure OpenAI settings, Vertex project/location, Bedrock settings, `MCPI_CACHE_RETENTION`, and `HTTP_PROXY`/`HTTPS_PROXY`.
+
+```json
+{
+  "cloudflare-ai-gateway": {
+    "type": "api_key",
+    "key": "$CLOUDFLARE_API_KEY",
+    "env": {
+      "CLOUDFLARE_API_KEY": "...",
+      "CLOUDFLARE_ACCOUNT_ID": "account-id",
+      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
+    }
+  }
+}
+```
+
+Use this when mcpi should use different provider settings than the project shell environment.
+
 ### Key Resolution
 
-The `key` field supports three formats:
+The `key` field supports command execution, environment interpolation, and literals:
 
-- **Shell command:** `"!command"` executes and uses stdout (cached for process lifetime)
+- **Shell command:** `"!command"` at the start executes the whole value as a command and uses stdout (cached for process lifetime)
   ```json
   { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
   { "type": "api_key", "key": "!op read 'op://vault/item/credential'" }
   ```
-- **Environment variable:** Uses the value of the named variable
+- **Environment interpolation:** `"$ENV_VAR"` or `"${ENV_VAR}"` uses the value of the named variable. Interpolation works inside larger literals.
   ```json
-  { "type": "api_key", "key": "MY_ANTHROPIC_KEY" }
+  { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
+  { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }
   ```
-- **Literal value:** Used directly
+  `$FOO_BAR` is the variable `FOO_BAR`; use `${FOO}_BAR` when `BAR` is literal text. Missing environment variables make the value unresolved.
+- **Escapes:** `"$$"` emits a literal `"$"`; `"$!"` emits a literal `"!"` without triggering command execution.
+  ```json
+  { "type": "api_key", "key": "$$literal-dollar-prefix" }
+  { "type": "api_key", "key": "$!literal-bang-prefix" }
+  ```
+- **Literal value:** Used directly. Plain uppercase strings such as `MY_API_KEY` are literals; use `$MY_API_KEY` for environment variables.
   ```json
   { "type": "api_key", "key": "sk-ant-..." }
+  { "type": "api_key", "key": "public" }
   ```
 
 OAuth credentials are also stored here after `/login` and managed automatically.
@@ -116,7 +190,10 @@ OAuth credentials are also stored here after `/login` and managed automatically.
 
 ```bash
 export AZURE_OPENAI_API_KEY=...
-export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
+export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
+# also supported: https://your-resource.cognitiveservices.azure.com
+# also supported: https://your-resource.openai.azure.com
+# root endpoints are auto-normalized to /openai/v1
 # or use resource name instead of base URL
 export AZURE_OPENAI_RESOURCE_NAME=your-resource
 
@@ -127,6 +204,8 @@ export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o
 
 ### Amazon Bedrock
 
+Use `/login amazon-bedrock` to store a Bedrock API key, or configure one of the ambient AWS credential sources below:
+
 ```bash
 # Option 1: AWS Profile
 export AWS_PROFILE=your-profile
@@ -145,14 +224,14 @@ export AWS_REGION=us-west-2
 Also supports ECS task roles (`AWS_CONTAINER_CREDENTIALS_*`) and IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`).
 
 ```bash
-pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
+mcpi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
 ```
 
 Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name (base models and system-defined inference profiles). For application inference profiles (whose ARNs don't contain the model name), set `AWS_BEDROCK_FORCE_CACHE=1` to enable cache points:
 
 ```bash
 export AWS_BEDROCK_FORCE_CACHE=1
-pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123
+mcpi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123
 ```
 
 If you are connecting to a Bedrock API proxy, the following environment variables can be used:
@@ -168,6 +247,42 @@ export AWS_BEDROCK_SKIP_AUTH=1
 export AWS_BEDROCK_FORCE_HTTP1=1
 ```
 
+### Cloudflare AI Gateway
+
+`CLOUDFLARE_API_KEY` can be set via `/login`. The account ID and gateway slug can be set as environment variables or in the API key credential's `env` object in `auth.json`.
+
+```bash
+export CLOUDFLARE_API_KEY=...           # or use /login
+export CLOUDFLARE_ACCOUNT_ID=...
+export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
+mcpi --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"
+```
+
+Routes to OpenAI, Anthropic, and Workers AI through Cloudflare AI Gateway. Workers AI uses the Unified API (`/compat`) and prefixed model IDs (`workers-ai/@cf/...`). OpenAI uses the OpenAI passthrough route (`/openai`) with native OpenAI model IDs such as `gpt-5.1`. Anthropic uses the Anthropic passthrough route (`/anthropic`) with native Anthropic model IDs such as `claude-sonnet-4-5`.
+
+AI Gateway authentication uses `CLOUDFLARE_API_KEY` as `cf-aig-authorization`. Upstream authentication can be one of:
+
+| Mode | Request auth | Upstream auth |
+|------|--------------|---------------|
+| Workers AI | Cloudflare token only | Cloudflare-native |
+| Unified billing | Cloudflare token only | Cloudflare handles upstream auth and deducts credits |
+| Stored BYOK | Cloudflare token only | Cloudflare injects provider keys stored in the AI Gateway dashboard |
+| Inline BYOK | Cloudflare token plus upstream `Authorization` header | The request supplies the upstream provider key |
+
+For normal mcpi usage, prefer unified billing or stored BYOK. Inline BYOK requires configuring an additional upstream `Authorization` header for the Cloudflare AI Gateway provider, for example via a `models.json` provider/model override.
+
+### Cloudflare Workers AI
+
+`CLOUDFLARE_API_KEY` can be set via `/login`. `CLOUDFLARE_ACCOUNT_ID` can be set as an environment variable or in the API key credential's `env` object in `auth.json`.
+
+```bash
+export CLOUDFLARE_API_KEY=...           # or use /login
+export CLOUDFLARE_ACCOUNT_ID=...
+mcpi --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"
+```
+
+mcpi automatically sets `x-session-affinity` for [prefix caching](https://developers.cloudflare.com/workers-ai/features/prompt-caching/) discounts.
+
 ### Google Vertex AI
 
 Uses Application Default Credentials:
@@ -180,6 +295,12 @@ export GOOGLE_CLOUD_LOCATION=us-central1
 
 Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file.
 
+## llama.cpp
+
+mcpi supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage loaded models with `/llama`, and select a loaded model with `/model`.
+
+See [llama.cpp](llama-cpp.md) for server setup, model directory layout, environment variables, and command usage.
+
 ## Custom Providers
 
 **Via models.json:** Add Ollama, LM Studio, vLLM, or any provider that speaks a supported API (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). See [models.md](models.md).

package/docs/quickstart.md

@@ -0,0 +1,167 @@
+# Quickstart
+
+This page gets you from install to a useful first mcpi session.
+
+## Install
+
+mcpi is distributed as an npm package:
+
+```bash
+npm install -g --ignore-scripts @sammorrowdrums/mcpi
+```
+
+`--ignore-scripts` disables dependency lifecycle scripts during install. mcpi does not require install scripts for normal npm installs.
+
+### Uninstall
+
+Use the package manager that installed mcpi. The curl installer uses npm globally, so curl and npm installs are removed with npm:
+
+```bash
+# curl installer or npm install -g
+npm uninstall -g @sammorrowdrums/mcpi
+
+# pnpm
+pnpm remove -g @sammorrowdrums/mcpi
+
+# Yarn
+yarn global remove @sammorrowdrums/mcpi
+
+# Bun
+bun uninstall -g @sammorrowdrums/mcpi
+```
+
+Uninstalling mcpi leaves settings and credentials in `$XDG_CONFIG_HOME/mcpi` (fallback `~/.config/mcpi`; `%APPDATA%\mcpi` on Windows), sessions in `$XDG_STATE_HOME/mcpi` (fallback `~/.local/state/mcpi`; `%LOCALAPPDATA%\mcpi` on Windows), and disposable package/cache data in `$XDG_CACHE_HOME/mcpi` (fallback `~/.cache/mcpi`; `%LOCALAPPDATA%\mcpi` on Windows).
+
+Then start mcpi in the project directory you want it to work on:
+
+```bash
+cd /path/to/project
+mcpi
+```
+
+## Authenticate
+
+mcpi can use subscription providers through `/login`, or API-key providers through environment variables or the auth file.
+
+### Option 1: subscription login
+
+Start mcpi and run:
+
+```text
+/login
+```
+
+Then select a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), and GitHub Copilot.
+
+### Option 2: API key
+
+Set an API key before launching mcpi:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+mcpi
+```
+
+You can also run `/login` and select an API-key provider to store the key in `$XDG_CONFIG_HOME/mcpi/auth.json` (fallback `~/.config/mcpi/auth.json`; `%APPDATA%\mcpi\auth.json` on Windows).
+
+See [Providers](providers.md) for all supported providers, environment variables, and cloud-provider setup.
+
+## First session
+
+Once mcpi starts, type a request and press Enter:
+
+```text
+Summarize this repository and tell me how to run its checks.
+```
+
+By default, mcpi gives the model four tools:
+
+- `read` - read files
+- `write` - create or overwrite files
+- `edit` - patch files
+- `bash` - run shell commands
+
+Additional built-in read-only tools (`grep`, `find`, `ls`) are available through tool options. mcpi runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback.
+
+## Give mcpi project instructions
+
+mcpi loads context files at startup. Add an `AGENTS.md` file to tell it how to work in a project:
+
+```markdown
+# Project Instructions
+
+- Run `npm run check` after code changes.
+- Do not run production migrations locally.
+- Keep responses concise.
+```
+
+mcpi loads:
+
+- `$XDG_CONFIG_HOME/mcpi/AGENTS.md` for global instructions (fallback `~/.config/mcpi/AGENTS.md`; `%APPDATA%\mcpi\AGENTS.md` on Windows)
+- `AGENTS.md` or `CLAUDE.md` from parent directories and the current directory
+
+If a directory contains `AGENTS.override.md`, mcpi loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory.
+
+Restart mcpi, or run `/reload`, after changing context files.
+
+## Common things to try
+
+### Reference files
+
+Type `@` in the editor to fuzzy-search files, or pass files on the command line:
+
+```bash
+mcpi @README.md "Summarize this"
+mcpi @src/app.ts @src/app.test.ts "Review these together"
+```
+
+Images or text can be pasted with Ctrl+V (Alt+V on Windows); images can also be dragged into supported terminals.
+
+### Run shell commands
+
+In interactive mode:
+
+```text
+!npm run lint
+```
+
+The command output is sent to the model. Use `!!command` to run a command without adding its output to the model context.
+
+### Switch models
+
+Use `/model` or Ctrl+L to choose a model. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.
+
+### Continue later
+
+Sessions are saved automatically:
+
+```bash
+mcpi -c                  # Continue most recent session
+mcpi -r                  # Browse previous sessions
+mcpi --name "my task"    # Set session display name at startup
+mcpi --session <path|id> # Open a specific session
+```
+
+Inside mcpi, use `/resume`, `/new`, `/tree`, `/fork`, and `/clone` to manage sessions.
+
+### Non-interactive mode
+
+For one-shot prompts:
+
+```bash
+mcpi -p "Summarize this codebase"
+cat README.md | mcpi -p "Summarize this text"
+mcpi -p @screenshot.png "What's in this image?"
+```
+
+Use `--mode json` for JSON event output or `--mode rpc` for process integration.
+
+## Next steps
+
+- [Using mcpi](usage.md) - interactive mode, slash commands, sessions, context files, and CLI reference.
+- [Providers](providers.md) - authentication and model setup.
+- [Settings](settings.md) - global and project configuration.
+- [Keybindings](keybindings.md) - shortcuts and customization.
+- [mcpi Packages](packages.md) - install shared extensions, skills, prompts, and themes.
+
+Platform notes: [Windows](windows.md), [Termux](termux.md), [tmux](tmux.md), [Terminal setup](terminal-setup.md), [Shell aliases](shell-aliases.md).