feat: Major CLI syntax overhaul to mcpc [<@session>] [<command>]

[jancurn]

Breaking change: major improvement of syntax:

mcpc <target> [<command>] => mcpc [<@session>] [<command>]

Plus various related fixes and improvements in CLI interface.

--

The existing interface of mcpc now looks like this:

Usage: mcpc [options] [command]

The main “verb” after mcpc is always expected to be a target (either URL, config entry, or sesion name). But that’s problematic and non-standard, as for example we can’t easlie introduce new global commands to mcpc such as “clean”, “x402”, “grep” etc.

This is a new proposal for the interface that introduces a more standard “mcpc ” syntax, where can also be a @session and then mcpc will operate on the session as it does now. Also, we’re getting rid of the non-session access to MCP servers (e.g. “mcpc mcp.apify.com tools-list”), it only complicates syntax and implementation.

# List all active sessions and saved authentication profiles (works same as now)
mcpc

# Print version
mcpc --version


# Print general help (both commands do the same)
mcpc --help
mcpc help

# Print help for a specific command (works even for the MCP commands like tools-list)
mcpc help <command>

# Login to remote MCP server and save OAuth credentials for future use
mcpc login mcp.apify.com [--profile <name>]
mcpc logout mcp.apify.com [--profile <name>]

# Clean up
mcpc clean [resource...]
# Resources are: sessions, profiles, logs, sockets, all
# MCP session commands - after session is connected, you can use "mcpc @<session> ..." to interact with it
mcpc connect mcp.apify.com @apify [--profile <name>] [--proxy <[host:]port>] [--proxy-bearer-token <token>]


# Connect to single entry from config file (mcpc first checks if target is valid URL - if not it checks if it's a file. So use ./xxx or ~/xxx to force file.)
mcpc connect ~/.vscode/mcp.json:filesystem @fs 

# MAYBE LATER:
# Connects to all entries from file - the 
# mcpc connect ~/.vscode/mcp.json
# Connect to all 
# mcpc connect




# All session-related commands then use "mcpc @<session> <command>" syntax:

# Print help for session and its server incl. capabilities (same as it works now)
mcpc @<session> shell
mcpc @<session> close
mcpc @<session> restart

# MCP commands (same as it works now)
mcpc @<session> tools-list
mcpc @<session> tools-get <tool-name>
mcpc @<session> tools-call <tool-name> [arg1:=val1 arg2:=val2 ... | <args-json> | <stdin]
...
mcpc @<session> ping


# General options (applicable to multiple commands)
--json
--verbose
--timeout
--header
--help

[Copilot]

Pull request overview

This PR implements a breaking, command-first CLI redesign for mcpc, shifting from mcpc <target> [command] to mcpc [<@session>] [<command>] and removing direct one-shot access to servers (users must connect to create a session before running MCP commands).

Changes:

• Introduces top-level verb commands (connect, login, logout, clean, help, x402) and routes MCP operations through @session targets.
• Adds parsing utilities for server arguments (parseServerArg) and session subcommand detection (hasSubcommand); removes legacy --config/target parsing logic.
• Updates unit + E2E tests and refreshes user-facing docs (README/CLAUDE/CHANGELOG) to reflect the new interface.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/cli/index.ts	Reworks CLI routing into top-level commands vs session subcommands; adds connect/login/logout/clean/help wiring.
src/cli/parser.ts	Removes legacy target/config parsing; adds hasSubcommand and parseServerArg.
src/cli/helpers.ts	Removes direct-connection client path; withMcpClient now enforces session-only usage.
src/cli/commands/sessions.ts	Updates connectSession argument ordering to match new connect command flow.
src/lib/errors.ts	Updates auth error guidance strings to new command syntax.
src/lib/utils.ts	Removes unused isFile/isDirectory helpers and stat import.
test/unit/cli/index.test.ts	Replaces findTarget tests with coverage for parseServerArg and hasSubcommand.
test/e2e/lib/framework.sh	Removes implicit test-header injection from run_mcpc; adds header injection only in create_session.
test/e2e/suites/**	Updates E2E invocations to `mcpc connect <server
README.md	Updates embedded --help output snippet to new usage/commands list.
CLAUDE.md	Updates documented CLI usage patterns to the new session-first workflow.
CHANGELOG.md	Documents the breaking syntax change and migration examples.
docs/TODOs.md	Adds notes/examples related to x402 and an auth/session bug (needs syntax refresh).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

@jancurn I've opened a new pull request, #30, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

Pull request overview

Copilot reviewed 41 out of 42 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.