---
name: mcporter-cli-conventions
source: https://app.decimal.ai/s/mcporter-cli-conventions@1/SKILL.md
source_sha256: cb540cfa10c7
---

# mcporter CLI conventions

## Contract

Emit mcporter's real command surface whenever a task drives the `mcporter` CLI: the `call` verb
with a dotted `server.tool` selector, the bare `key=value`/`key:value` argument syntax, and the
exact subcommand and flag names for inspecting, authenticating, configuring, and code-generating
MCP servers. Apply this any time a shell command or instruction targets mcporter.

## Rules

1. **Call a tool — `mcporter call <server>.<tool>`.** The target is ONE dotted token joining the
   server name and the tool name with a single `.` (`mcporter call linear.list_issues`). Never
   split it into two arguments (`mcporter call linear list_issues`) and never use `--server` /
   `--tool` flags. The `call` verb may be dropped as shorthand (`mcporter linear.list_issues`),
   but the dotted selector is mandatory.
2. **Arguments — bare `key=value` or `key:value`.** Attach tool arguments directly after the
   selector as `key=value` or `key:value` tokens (`team=ENG limit:5`), NOT as GNU flags
   (`--team ENG`). Other accepted forms:
   - Whole JSON object: `--args '{"limit":5}'` — use for nested or structured parameters.
   - Function-call: `'linear.create_issue(title: "Bug")'` — positional order follows the schema.
   - Value from a file: `key=@path` — `body=@./notes.md` reads the file as that argument's value.
3. **Inspect servers — `mcporter list`.** Bare `mcporter list` prints the configured servers;
   `mcporter list <server>` prints that server's tools. Add `--schema` (or `--all-parameters`)
   for full input parameters, `--brief` / `--signatures` for compact one-line signatures, and
   `--status` for a health check.
4. **Ad-hoc endpoints.** For a server not in config: `--stdio "<launch command>"` targets a
   locally-launched stdio server (`--stdio "bun run ./srv.ts"`); `--http-url <url>` — or passing
   the full URL directly as the selector — targets a remote HTTP server. The launch-command flag
   is `--stdio`, never `--command` / `--exec` / `--cmd`.
5. **OAuth — `mcporter auth <server|url>`.** The browser OAuth flow is the `auth` subcommand
   (`mcporter auth notion`), not `login` / `oauth` / `connect`. Add `--no-browser` to print the
   authorization URL for headless use.
6. **Config — `mcporter config <list|get|add|remove|import>`.** Register a server with
   `config add <name> <url>` (append `--auth oauth` for OAuth); read one entry with
   `config get <name>`; delete one with `config remove <name>`; pull definitions from other
   clients with `config import <cursor|claude-code|codex|...>`.
7. **Machine-readable output — `--output json`.** Add `--output json` (or the shorthand `--json`)
   to any command to get JSON; not `--format json`.
8. **Keep-alive pool — `mcporter daemon <start|status|stop|restart>`.** Pre-warm a background
   server pool with `daemon start`, check it with `daemon status`, and bounce it after config
   edits with `daemon restart`.
9. **Package a server as a CLI — `mcporter generate-cli`.** `mcporter generate-cli --command <url>`
   (or `mcporter generate-cli <server-name>`) emits a standalone CLI. Read a generated artifact's
   build metadata with `mcporter inspect-cli <path>`.
10. **TypeScript codegen — `mcporter emit-ts <server> --mode client|types`.** `--mode client`
    emits a full typed client wrapper; `--mode types` emits type-only declarations. The flag is
    `--mode`, its values `client` / `types` — never `--type` / `--target`.
11. **Config file — `config/mcporter.json`.** By default mcporter reads the project file
    `config/mcporter.json`; override with `--config <path>` (also honored, in order: `$MCPORTER_CONFIG`,
    then `$XDG_CONFIG_HOME/mcporter/mcporter.json[c]` or `~/.mcporter/mcporter.json[c]`).

## Worked examples

BEFORE = the wrong default a base model guesses; AFTER = the real mcporter form.

- Calling a tool:
  - BEFORE: `mcporter call --server github --tool create_issue --title "Bug"`
  - AFTER:  `mcporter call github.create_issue title="Bug"`
- Structured argument:
  - BEFORE: `mcporter call slack.post --channel "#general" --text hi`
  - AFTER:  `mcporter call slack.post --args '{"channel":"#general","text":"hi"}'`
- Inspecting a server's parameters:
  - BEFORE: `mcporter describe brave-search`
  - AFTER:  `mcporter list brave-search --schema`
- Local stdio server:
  - BEFORE: `mcporter call --command "python srv.py" scan path=/x`
  - AFTER:  `mcporter call --stdio "python srv.py" scan path=/x`
- OAuth sign-in:
  - BEFORE: `mcporter login sentry`
  - AFTER:  `mcporter auth sentry`
- Registering a server:
  - BEFORE: `mcporter add sentry https://mcp.sentry.dev/mcp`
  - AFTER:  `mcporter config add sentry https://mcp.sentry.dev/mcp --auth oauth`
- JSON output:
  - BEFORE: `mcporter call weather.today city=NYC --format json`
  - AFTER:  `mcporter call weather.today city=NYC --output json`
- Keep servers warm:
  - BEFORE: `mcporter serve --keep-alive`
  - AFTER:  `mcporter daemon start`
- Packaging a CLI:
  - BEFORE: `mcporter codegen --url https://mcp.grep.app/mcp`
  - AFTER:  `mcporter generate-cli --command https://mcp.grep.app/mcp`
- TypeScript client:
  - BEFORE: `mcporter emit-ts vault --type client`
  - AFTER:  `mcporter emit-ts vault --mode client`

## Edge cases & exceptions

- **Shorthand verbs.** `mcporter <server>.<tool>` (a dotted selector) infers `call`; `mcporter <server>`
  (a bare server name, no dot) infers `list`. The dot is what distinguishes a call from a list.
- **Inline vs `--args`.** Inline `key=value` is fine for flat scalars; switch to `--args '<json>'`
  the moment a value is an object or array. Do not mix inline and `--args` for the same key.
- **Coercion.** Inline values are coerced (numbers, booleans, `null`, JSON) by default; pass
  `--raw-strings` or `--no-coerce` to keep them as literal strings.
- **URL as selector.** A full `https://…/mcp` URL can stand in for `<server>` directly in `call`
  and `list`; `--http-url <url>` is the explicit equivalent.
- **Config precedence.** `--config` > `$MCPORTER_CONFIG` > project `config/mcporter.json` >
  `$XDG_CONFIG_HOME/mcporter/mcporter.json[c]` / `~/.mcporter/mcporter.json[c]`.

## Do / Don't

- DO join server and tool with a dot: `linear.list_issues`. DON'T pass two args or `--server/--tool`.
- DO pass arguments as `key=value` / `key:value`. DON'T use `--key value` GNU flags for tool arguments.
- DO inspect with `mcporter list <server> --schema`. DON'T use `describe` / `inspect` / `tools`.
- DO launch a stdio server with `--stdio "<cmd>"`. DON'T use `--command` / `--exec`.
- DO run OAuth with `mcporter auth <server>`. DON'T use `login` / `oauth` / `connect`.
- DO register with `mcporter config add <name> <url>`. DON'T use `mcporter add` / `register`.
- DO request JSON with `--output json`. DON'T use `--format json`.
- DO warm servers with `mcporter daemon start`. DON'T use `serve` / `start` / `warmup`.
- DO code-gen with `generate-cli` and `emit-ts --mode client|types`. DON'T use `codegen` / `--type`.

## Common mistakes

- Splitting `server.tool` into separate arguments or `--server`/`--tool` flags instead of the dotted selector.
- Passing tool arguments as `--key value` GNU flags rather than `key=value` / `key:value`.
- Inventing `mcporter describe` / `mcporter inspect` to see a server's tools instead of `mcporter list <server> --schema`.
- Using `--command` for a locally-launched server (the flag is `--stdio`).
- Reaching for `mcporter login` / `mcporter oauth` instead of `mcporter auth`.
- Using `mcporter add` instead of `mcporter config add`, or `mcporter import` instead of `mcporter config import`.
- Writing `--format json` for machine output instead of `--output json` / `--json`.
- Naming the codegen `codegen` / `build` instead of `generate-cli`, or using `--type` instead of `--mode` on `emit-ts`.

## Quick checklist

- [ ] Tool call: `mcporter call <server>.<tool>` (dotted selector; `call` verb or shorthand).
- [ ] Arguments: `key=value` / `key:value` / `--args '<json>'` / `key=@file` — never `--key value`.
- [ ] Inspect: `mcporter list <server> --schema` (or `--brief` / `--signatures`).
- [ ] Ad-hoc: `--stdio "<cmd>"` for local, `--http-url <url>` or a full URL for remote.
- [ ] OAuth: `mcporter auth <server|url>`.
- [ ] Config: `mcporter config add|get|remove|import`; register = `config add <name> <url>`.
- [ ] JSON: `--output json` (or `--json`).
- [ ] Keep-alive: `mcporter daemon start|status|stop|restart`.
- [ ] Codegen: `mcporter generate-cli --command <url>`; `mcporter emit-ts <server> --mode client|types`.
- [ ] Config file default `config/mcporter.json`; override `--config <path>`.