@apify/mcpc 0.1.2 → 0.1.3

package/README.md

@@ -1,7 +1,7 @@
 # mcpc: Universal MCP command-line client
 
 `mcpc` is a CLI for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/),
-which maps MCP requests to intuitive commands for shell access, scripts, and AI coding agents.
+which maps MCP operations to intuitive commands for interactive shell use, scripts, and AI coding agents.
 
 `mcpc` can connect to any MCP server over Streamable HTTP or stdio transports,
 securely login via OAuth credentials and store credentials,
@@ -11,16 +11,86 @@ It supports all major MCP features, including tools, resources, prompts, asynchr
 `mcpc` is handy for manual testing of MCP servers, scripting,
 and AI coding agents to use MCP in ["code mode"](https://www.anthropic.com/engineering/code-execution-with-mcp),
 for better accuracy and lower token compared to traditional tool function calling.
-After all, UNIX-compatible shell script is THE most universal coding language, for both people and LLMs.
-
-Note that `mcpc` is deterministic and does not use any LLM on its own; that's for the higher layer to do.
+After all, UNIX-compatible shell script is THE most universal coding language, for people and LLMs alike.
+
+Note that `mcpc` is deterministic and does not use any LLM on its own; that's left for the higher layer.
+
+<!--
+## Table of contents
+
+TODO: Simplify README - there are too many top-level sections, and then show just the second level ones
+-->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+<!--
+- [Features](#features)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Usage](#usage)
+  - [MCP command arguments](#mcp-command-arguments)
+- [Global flags](#global-flags)
+- [Authentication](#authentication)
+  - [No authentication](#no-authentication)
+  - [Bearer token authentication](#bearer-token-authentication)
+  - [OAuth authentication](#oauth-authentication)
+    - [Authentication profiles](#authentication-profiles)
+    - [Authentication behavior](#authentication-behavior)
+    - [Multiple accounts for the same server](#multiple-accounts-for-the-same-server)
+  - [Authentication precedence](#authentication-precedence)
+  - [Authentication profiles storage format](#authentication-profiles-storage-format)
+- [Sessions](#sessions)
+  - [Managing sessions](#managing-sessions)
+  - [Piping between sessions](#piping-between-sessions)
+  - [Scripting](#scripting)
+  - [Session failover](#session-failover)
+- [Logging](#logging)
+- [Cleanup](#cleanup)
+- [Configuration](#configuration)
+  - [MCP config JSON file](#mcp-config-json-file)
+  - [Environment variables](#environment-variables)
+- [MCP protocol notes](#mcp-protocol-notes)
+- [Output format](#output-format)
+  - [Human-readable (default)](#human-readable-default)
+  - [JSON mode (`--json`)](#json-mode---json)
+- [Security](#security)
+  - [Credential storage](#credential-storage)
+  - [Bridge process authentication](#bridge-process-authentication)
+  - [File permissions](#file-permissions)
+  - [Network security](#network-security)
+- [Error handling](#error-handling)
+  - [Exit codes](#exit-codes)
+  - [Retry strategy](#retry-strategy)
+- [Interactive shell](#interactive-shell)
+- [Claude Code skill](#claude-code-skill)
+- [Troubleshooting](#troubleshooting)
+  - [Common issues](#common-issues)
+  - [Debug mode](#debug-mode)
+  - [Logs](#logs)
+- [Development](#development)
+  - [Design principles](#design-principles)
+  - [Architecture overview](#architecture-overview)
+  - [Core module (runtime-agnostic)](#core-module-runtime-agnostic)
+  - [Bridge process](#bridge-process)
+  - [CLI executable](#cli-executable)
+  - [Session lifecycle](#session-lifecycle)
+  - [Error recovery](#error-recovery)
+- [Testing strategy](#testing-strategy)
+- [Contributing](#contributing)
+  - [Development setup](#development-setup)
+  - [Release process](#release-process)
+  - [References](#references)
+- [Authors](#authors)
+- [License](#license)
+-->
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Features
 
 - 🔌 **Universal MCP client** - Works with any MCP server over Streamable HTTP or stdio.
 - 🔄 **Persistent sessions** - Keep multiple server connections alive simultaneously.
 - 🚀 **Zero setup** - Connect to remote servers instantly with just a URL.
-- 🔧 **Full protocol support** - Tools, resources, prompts, sampling, dynamic discovery, and async notifications.
+- 🔧 **Full protocol support** - Tools, resources, prompts, dynamic discovery, and async notifications.
 - 📊 **`--json` output** - Easy integration with `jq`, scripts, and other CLI tools.
 - 🤖 **AI-friendly** - Designed for code generation and automated workflows.
 - 🔒 **Secure** - OS keychain integration for credentials, encrypted auth storage.
@@ -82,8 +152,8 @@ mcpc <target> prompts-get <prompt-name> [--args key=val key2:=json ...] [--args-
 
 mcpc <target> resources
 mcpc <target> resources-list
-mcpc <target> resources-read <uri> [-o <file>] [--max-size <bytes>]
-mcpc <target> resources-subscribe <uri> # TODO
+mcpc <target> resources-read <uri>
+mcpc <target> resources-subscribe <uri>
 mcpc <target> resources-unsubscribe <uri>
 mcpc <target> resources-templates-list
 
@@ -210,7 +280,7 @@ This allows you to:
 - Manage credentials independently from sessions
 
 **Key concepts:**
-- **Authentication profile**: Named set of OAuth credentials for a specific server (stored in `~/.mcpc/auth-profiles.json` + OS keychain)
+- **Authentication profile**: Named set of OAuth credentials for a specific server (stored in `~/.mcpc/profiles.json` + OS keychain)
 - **Session**: Active connection to a server that may reference an authentication profile (stored in `~/.mcpc/sessions.json`)
 - **Default profile**: When `--profile` is not specified, `mcpc` uses the authentication profile named `default`
 
@@ -315,7 +385,7 @@ When multiple authentication methods are available, `mcpc` uses this precedence
 
 ### Authentication profiles storage format
 
-By default, authentication profiles are stored in the `~/.mcpc/auth-profiles.json` file with the following structure:
+By default, authentication profiles are stored in the `~/.mcpc/profiles.json` file with the following structure:
 
 ```json
 {
@@ -369,7 +439,7 @@ Instead of forcing every command to reconnect and reinitialize (which is slow an
 `mcpc` saves its state to `~/.mcpc/` directory (unless overridden by `MCPC_HOME_DIR`), in the following files:
 
 - `~/.mcpc/sessions.json` - Active sessions with references to authentication profiles (file-locked for concurrent access)
-- `~/.mcpc/auth-profiles.json` - Authentication profiles (OAuth metadata, scopes, expiry)
+- `~/.mcpc/profiles.json` - Authentication profiles (OAuth metadata, scopes, expiry)
 - `~/.mcpc/bridges/` - Unix domain socket files for each bridge process
 - `~/.mcpc/logs/bridge-*.log` - Log files for each bridge process
 - OS keychain - Sensitive credentials (OAuth tokens, bearer tokens, client secrets)
@@ -466,7 +536,7 @@ mcpc https://mcp.apify.com session @apify
 
 ## Logging
 
-The background bridge process logs to `~/.mcpc/bridges/mcpc-@<session-name>.log`.
+The background bridge process logs to `~/.mcpc/logs/bridge-<session-name>.log`.
 The main `mcpc` process doesn't save log files, but you can use `--verbose` flag to print all logs to stderr.
 
 MCP servers can be instructed to adjust their [logging level](https://modelcontextprotocol.io/specification/latest/server/utilities/logging)
@@ -493,6 +563,24 @@ mcpc @apify logging-set-level error
 **Note:** This sets the logging level on the **server side**. The actual log output depends on the server's implementation.
 
 
+## Cleanup
+
+You can clean up the `mcpc` state and data using the `--clean` option:
+
+```bash
+# Safe non-destructive cleanup: remove expired sessions, delete old orphaned logs
+mcpc --clean
+
+# Clean specific resources (comma-separated)
+mcpc --clean=sessions      # Kill bridges, delete all sessions
+mcpc --clean=profiles      # Delete all authentication profiles
+mcpc --clean=logs          # Delete all log files
+mcpc --clean=sessions,logs # Clean multiple resource types
+
+# Nuclear option: remove everything
+mcpc --clean=all           # Delete all sessions, profiles, logs, and sockets
+```
+
 ## Configuration
 
 Configuration can be provided via file, environment variables, or command-line flags.
@@ -610,7 +698,7 @@ Config files support environment variable substitution using `${VAR_NAME}` synta
   - **Tools**: Executable functions with JSON Schema-validated arguments.
   - **Resources**: Data sources identified by URIs (e.g., `file:///path/to/file`, `https://example.com/data`), with optional subscriptions for change notifications
   - **Prompts**: Reusable message templates with customizable arguments
-  - **Completion**: Provides access to Completion API for tools and resources, and offers completions in shell mode
+  - **Completion**: Provides access to Completion API for tools and resources
 - Supports server logging settings (`logging/setLevel`) and messages (`notifications/message`), and prints them to stderr or stdout based on verbosity level.
 - Handles server notifications: progress tracking, logging, and change notifications (`notifications/tools/list_changed`, `notifications/resources/list_changed`, `notifications/prompts/list_changed`)
 - Request multiplexing: supports up to 10 concurrent requests, queues up to 100 additional requests
@@ -645,7 +733,7 @@ MCP enables arbitrary tool execution and data access; treat servers like you tre
 - OAuth refresh tokens are stored in the OS keychain (access tokens are kept in memory only)
 - OAuth client credentials (client_id, client_secret from dynamic registration) are stored in the keychain
 - All HTTP headers from `--header` flags are stored per-session in the keychain (as JSON)
-- The `~/.mcpc/auth-profiles.json` file only contains metadata (server URL, scopes, timestamps) - never tokens
+- The `~/.mcpc/profiles.json` file only contains metadata (server URL, scopes, timestamps) - never tokens
 
 **Keychain entries:**
 - OAuth tokens: `mcpc:auth:<serverUrl>:<profileName>:oauth-tokens`
@@ -681,7 +769,7 @@ This architecture ensures:
 ### File permissions
 
 - `~/.mcpc/sessions.json` is set to `0600` (user-only read/write)
-- `~/.mcpc/auth-profiles.json` is set to `0600` (user-only read/write)
+- `~/.mcpc/profiles.json` is set to `0600` (user-only read/write)
 - Bridge sockets in `~/.mcpc/bridges/` are created with `0700` permissions
 - Log files in `~/.mcpc/logs/` are created with `0600` permissions
 
@@ -728,9 +816,8 @@ mcpc @apify shell
 ```
 
 **Features:**
-- Command history (saved to `~/.mcpc/history`, last 1000 commands)
-- Tab completion for commands, tool names, and resource URIs
-- Multi-line editing with arrow keys
+- Command history with arrow key navigation (saved to `~/.mcpc/history`, last 1000 commands)
+- Real-time server notifications displayed during session
 - Prompt shows session name: `mcpc(@apify)> `
 
 **Shell-specific commands:**
@@ -770,17 +857,60 @@ Then restart Claude Code. The skill enables Claude to interact with MCP servers
 
 See [`claude-skill/README.md`](./claude-skill/README.md) for details.
 
-## Implementation
+
+## Troubleshooting
+
+### Common issues
+
+**"Cannot connect to bridge"**
+- Bridge may have crashed. Try: `mcpc <server> session @<session-name>`
+- Check bridge is running: `ps aux | grep -e 'mcpc-bridge' -e '[m]cpc/dist/bridge'`
+- Check socket exists: `ls ~/.mcpc/bridges/`
+
+**"Session not found"**
+- Session may have expired. Create new session: `mcpc <target> session @<session-name>`
+- List existing sessions: `mcpc`
+
+**"Authentication failed"**
+- List saved profiles: `mcpc`
+- Re-authenticate: `mcpc <server> login [--profile <name>]`
+- For bearer tokens: provide `--header "Authorization: Bearer ${TOKEN}"` again
+
+### Debug mode
+
+Enable detailed logging with `--verbose`:
+
+```bash
+mcpc --verbose @apify tools-list
+```
+
+This shows:
+- Protocol negotiation details
+- JSON-RPC request/response messages
+- Streaming events and reconnection attempts
+- Bridge communication (socket messages)
+- File locking operations
+- Prints server log messages with severity `debug`, `info`, and `notice` to standard output
+
+### Logs
+
+Bridge processes log to:
+- `~/.mcpc/logs/bridge-<session-name>.log`
+
+Log rotation: Keep last 10MB per session, max 5 files.
+
+## Development
 
 `mcpc` is under active development and some things might not work 100% yet. You have been warned.
 
 ### Design principles
 
 - Delightful for humans and AI agents alike (interactive + scripting)
-- One clear way to do things (orthogonal commands, no surprises, saving tokens)
-- Do not ask for user input (except `shell` and `login`)
-- Be forgiving, always help users make forward progress (great errors + guidance)
-- JSON strictly consistency with the MCP specification
+- Avoid unnecessary interaction loops, provide sufficient context, yet be concise (save tokens)
+- One clear way to do things (orthogonal commands, no surprises)
+- Do not ask for user input (except `shell` and `login`, no unexpected OAuth flows)
+- Be forgiving, always help users make progress (great errors + guidance)
+- Be consistent with the [MCP specification](https://modelcontextprotocol.io/specification/latest), with `--json` strictly
 - Minimal and portable (few deps, cross-platform)
 - No slop!
 
@@ -854,18 +984,18 @@ Implemented as a separate executable (`mcpc-bridge`) that maintains persistent c
 The main `mcpc` command provides the user interface.
 
 **CLI responsibilities:**
-- Argument parsing (using `minimist` or similar)
+- Argument parsing using Commander.js
 - Output formatting (human-readable vs `--json`)
 - Bridge lifecycle: start/connect/stop
 - Communication with bridge via socket
-- Interactive shell (REPL using `@inquirer/prompts`)
+- Interactive shell (REPL using Node.js `readline`)
 - Configuration file loading (standard MCP JSON format)
 - Credential management (OS keychain via `keytar` package)
 
 **Shell implementation:**
-- Built on `@inquirer/prompts` for input handling
-- Command history using `~/.mcpc/history`
-- Tab completion using inquirer autocomplete and MCP completion API
+- Built on Node.js `readline` module for input handling with history support
+- Command history using `~/.mcpc/history` (last 1000 commands)
+- Real-time notification display during shell sessions
 - Graceful exit handling (cleanup on Ctrl+C/Ctrl+D)
 
 ### Session lifecycle
@@ -938,47 +1068,6 @@ Later...
 - `examples/test-server/` - Reference MCP server for testing
 - `test/mock-keychain.ts` - Mock OS keychain for testing
 
-## Troubleshooting
-
-### Common issues
-
-**"Cannot connect to bridge"**
-- Bridge may have crashed. Try: `mcpc <server> session @<session-name>`
-- Check bridge is running: `ps aux | grep -e 'mcpc-bridge' -e '[m]cpc/dist/bridge'`
-- Check socket exists: `ls ~/.mcpc/bridges/`
-
-**"Session not found"**
-- Session may have expired. Create new session: `mcpc <target> session @<session-name>`
-- List existing sessions: `mcpc`
-
-**"Authentication failed"**
-- List saved profiles: `mcpc`
-- Re-authenticate: `mcpc <server> login [--profile <name>]`
-- For bearer tokens: provide `--header "Authorization: Bearer ${TOKEN}"` again
-
-### Debug mode
-
-Enable detailed logging with `--verbose`:
-
-```bash
-mcpc --verbose @apify tools-list
-```
-
-This shows:
-- Protocol negotiation details
-- JSON-RPC request/response messages
-- Streaming events and reconnection attempts
-- Bridge communication (socket messages)
-- File locking operations
-- Prints server log messages with severity `debug`, `info`, and `notice` to standard output
-
-### Logs
-
-Bridge processes log to:
-- `~/.mcpc/logs/bridge-<session-name>.log`
-
-Log rotation: Keep last 10MB per session, max 5 files.
-
 ## Contributing
 
 Contributions are welcome!
@@ -1006,23 +1095,26 @@ mcpc --help
 
 ### Release process
 
-```bash
-# Run tests
-npm test
-
-# Build
-npm run build
-
-# Bump version
-npm version patch|minor|major
+Use the release script to publish a new version (must be on `main` branch):
 
-# Publish
-npm publish
-
-# Push tags
-git push --tags
+```bash
+npm run release          # patch version bump (0.1.2 → 0.1.3)
+npm run release:minor    # minor version bump (0.1.2 → 0.2.0)
+npm run release:major    # major version bump (0.1.2 → 1.0.0)
 ```
 
+The script automatically:
+- Ensures you're on `main` branch
+- Ensures working directory is clean (no uncommitted changes)
+- Ensures branch is up-to-date with remote
+- Runs lint, build, and tests
+- Bumps the version in package.json
+- Creates a git commit and annotated tag (`v{version}`)
+- Pushes the commit and tag to origin
+- Publishes to npm
+
+After publishing, create a GitHub release at the provided link.
+
 Please open an issue or pull request on [GitHub](https://github.com/apify/mcpc).
 
 

package/TODOs.md

@@ -1,93 +1,85 @@
 
 # TODOs
 
-
 ## Bugs
-- Seems calling invalid/unknown MCP command in shell (perhaps also normally) causes the bridge to be flagged as expired
-
-- reconnection doesn't work
-mcpc @apify session                                                                                                        1 ✘
-error: missing required argument 'name'
+...
 
 
 ## Next
 
-- nit: consistent good server and session info, on server/session info, print also auth info
-  - [Using session: apify-docs] => change to show server + transport + version? + auth info!!!
-    Active MCP sessions:
-    @fs → npx (stdio) --- show also args instead of just "npx"
-  - print PID of bridge process
-
-Visual examples:
-
-    Xxx/
-    ├── run.sh                    # Master runner (parallel by suite)
-    ├── lib/
-    │   ├── common.sh             # Assertions, temp dirs, cleanup
-    │   ├── server.sh             # Start/stop test server helpers
-    │   └── mcpc.sh               # Wrapper to invoke mcpc with coverage
-    ├── fixtures/
-    │   └── configs/              # Test config files
-    ├── server/
-    │   └── index.ts              # Configurable test MCP server
-    │
-
- * ▐▛███▜▌ *   Claude Code v2.0.75
-* ▝▜█████▛▘ *  Opus 4.5 · Claude Team
- *  ▘▘ ▝▝  *   ~/Projects/mcpc
+- Expand --help to use same text as in README, add link to README
 
+BIG: We need to decide whether to show Markdown-ish or not
 
-- Better error handling:
-  - "mcpc https://mcp.sentry.dev/mcp" with an unknown sever => should hint to use "login"
-  - Handle MCP errors by failing the command tool, e.g. invalid tool name..
 
-- implement resources-subscribe/resources-unsubscribe command properly
+- implement resources-subscribe/resources-unsubscribe, --o file command properly, --max-size
 - > # TODO: automatically update the -o file on changes, without it just keep track of changed files in bridge process' cache, and report in resources-list
-
-
+  
+  
 ## Security
 - Double-check the MCP security guidelines
 - OAuth issuer - maybe save it and double-check it to ensure domain is not spoofed?
 
-
 ## Later
 
+- nit: Print version info to logs, and link to https://github.com/apify/mcpc (to right release tag) - add this also to --help
+
+- Implement "mcpc @session restart" 
+
 - nit: Colorize output, e.g. JSONs in one color. MCP provided data like descriptions and instructions in orange.
   -  warnings could be orange, errors red
-- - docs: add Claude Skills file to /docs, maybe also man page?
-- Add support for MCP elicitations, and potentially for sampling (e.g. via shell interface?)
+- nit: Cooler OAuth flow finish web page with CSS animation, add Apify example there. E.g. next step - check Apify rather than close
+
 - Add `--proxy [HOST:]PORT` feature to `connect` command to enable MCP proxy:
   - `--proxy-bearer-token X` to require auth token for better security
   - `--proxy-capabilities tools:TOOL_NAME,TOOL_NAME2,...,prompts[:...],...` to limit access to selected MCP features and tools
     (what if tools have ":" or "," in their names?)
     In theory, we could add limit of capabilities to normal sessions, but the LLM could still break out of it, so what's the point.
   - Explain this is useful for AI sandboxing!
-- Implement typing completions (e.g. "mcpc @a...") - not sure how difficult that is
-- nit: Nicer OAuth flow finish web page, add Apify example there. E.g. next step - check Apify rather than close
+
+- For auth profiles, fetch the detailed user info from http, ensure the info is up-to-date
+- Add support for MCP elicitations, and potentially for sampling (e.g. via shell interface?)
+
 - nit: cooler OAuth web pages "Authentication successful!" - show mcpc info
 - audit that on every command, we print next steps as examples
 - more shortcuts, e.g. --profile => -p
 - nit: in README, explain the MCP commands better in a standlone section, with details how they work
+- Add unique Session.id and Profile.id and use it for OS keychain keys, to truly enable using multiple independent mcpc profiles
+- When user runs --clean=profiles, print warning if some sessions were using them 
+
+- nit: Implement typing completions (e.g. "mcpc @a...") - not sure how difficult that is
+
+
 
 
 
 ## E2E test scenarios
-- add end-to-end tests e.g. under `test/e2e` - one bash script per test suite , organized in directories, and one master script that runs them all or selected ones (per directory) in parallel
-- Invariants:
+- DONE: add end-to-end tests e.g. under `test/e2e` - one bash script per test suite , organized in directories,and one master script that runs them all or selected ones (per directory) in parallel
+- Invariants (ideally test this for all commands used in other tests, or is it better just to always test one thing?):
   - --verbose only adds extra info to stderr, never to stdout
   - --json always returns single JSON object to stdout on success (exit code = 0), or an object or nothing at all on error (exit code != 0)
 - We'll need a testing server with all the available features and configurable, for testing.
+- "npm run test:coverage" doesn't seem to work and cover e2e tests
 - Things to test:
   - handling of errors, invalid params, names, etc.
   - pagination
   - env vars...
-  - stdio + filesystem operations,
+  - stdio + filesystem operations
   - sessions
+  - test stdio transport with fs mcp server
+  - test expired session (create fake record in session.json) - ensure attempts to use it will fail with the right error
   - for all commands, tests --verbose doesn't print anything extra to stdout, --json returns json
   - that on session close we send HTTP DELETE https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
-  - Test session failover - e.g. kill the bridge process, and try to access the session again (should be restarted)
+  - Test session failover - e.g. kill the bridge process, and try to access the session again - should be restarted, work, and have same MCP-Session-Id
+  - Test auth - if no profile available and server requires OAuth, we need to fail with info what to do! e.g. "mcpc https://mcp.sentry.dev/mcp --verbose"
   - Test server session aborting - if session is aborted by server, bridge process should exit and set session status to "expired"
-  - Test auth profiles work long-term and sessions too
-- Can we track test coverage also this way?
+  - Test auth profiles work long-term and sessions too - basically when running some tests the next day they should use old saved auths and sessions
+  - Test "mcpc @test close" and "mcpc <server> session @test" in rapid succession, it should work and use different pid (check sessions.json)
+  - Ensure calling invalid/unknown MCP command in shell and normally doesn't causes the bridge to be flagged as expired or dead
 - Text copy can change, but the core texts needs to be shown in both text and JSON mode
-
+- Testing servers we can use:
+  - https://mcp.apify.com (for testing real OAuth login, we can create various accounts, both OAuth and API tokens)
+  - https://mcp.apify.com/tools=docs (anonymous, no auth needed)
+  - https://mcp.sentry.dev/mcp (for testing if no auth profile available)
+  - ideally get some on non-standard port, maybe localhost
+