@apify/mcpc 0.1.2 → 0.1.4

package/README.md

@@ -1,30 +1,86 @@
-# mcpc: Universal MCP command-line client
+# `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,
-and keep long-term sessions to multiple servers in parallel.
+and keep long-term sessions to multiple servers.
 It supports all major MCP features, including tools, resources, prompts, asynchronous tasks, and notifications.
 
 `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.
+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 for the higher layer to do.
+Note that `mcpc` does not use LLMs on its own; that's a job for the higher layer.
 
-## Features
+**Key features**
 
-- 🔌 **Universal MCP client** - Works with any MCP server over Streamable HTTP or stdio.
+- 🔌 **Super compatible** - 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.
-- 📊 **`--json` output** - Easy integration with `jq`, scripts, and other CLI tools.
+- 🔧 **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.
 
+
+## Table of contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [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)
+  - [Output format](#output-format)
+    - [Human-readable (default)](#human-readable-default)
+    - [JSON mode](#json-mode)
+  - [Scripting](#scripting)
+    - [MCP server schema changes](#mcp-server-schema-changes)
+  - [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)
+- [Security](#security)
+  - [Authentication](#authentication-1)
+  - [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)
+  - [Logs](#logs)
+  - [Common issues](#common-issues)
+- [Contributing](#contributing)
+- [Authors](#authors)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+
 ## Install
 
 ```bash
@@ -37,69 +93,55 @@ npm install -g @apify/mcpc
 # List all active sessions and saved authentication profiles
 mcpc
 
-# Use a local server package referenced by MCP config file
-mcpc --config ~/.vscode/mcp.json filesystem tools-list
-
-# Login to OAuth-enabled MCP server and save authentication for future use
+# Login to remote MCP server and save OAuth credentials for future use
 mcpc mcp.apify.com login
 
-# Show information about a remote MCP server and open interactive shell
+# Show information about a remote MCP server
 mcpc mcp.apify.com
-mcpc mcp.apify.com shell
 
 # Use JSON mode for scripting
-mcpc --json mcp.apify.com tools-list
+mcpc mcp.apify.com tools-list --json
 
-# Create a persistent session (or reconnect if it exists but bridge is dead)
+# Create and use persistent MCP session
 mcpc mcp.apify.com session @test
-mcpc @test tools-call search-actors --args query="web crawler"
+mcpc @test tools-call search-actors --args keywords="web crawler"
 mcpc @test shell
+
+# Interact with a local MCP server package (stdio) referenced from config file
+mcpc --config ~/.vscode/mcp.json filesystem tools-list
 ```
 
 ## Usage
 
 ```bash
-mcpc [--json] [--config <file>] [-H|--header "K: V"] [-v|--verbose]
-     [--schema <file>] [--schema-mode <mode>] [--timeout <seconds>] 
-     [--clean|--clean=sessions,logs,profiles,all]
-     <target> <command...>
-
-# Lists all active sessions and saved authentication profiles
-mcpc         
-
-# Shows server or session info, instructions, and capabilities         
-mcpc <target>
-
-# MCP commands
-mcpc <target> tools
-mcpc <target> tools-list
-mcpc <target> tools-schema <tool-name>
-mcpc <target> tools-call <tool-name> [--args key=val key2:=json ...] [--args-file <file>]
-
-mcpc <target> prompts
-mcpc <target> prompts-list
-mcpc <target> prompts-get <prompt-name> [--args key=val key2:=json ...] [--args-file <file>]
-
-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-unsubscribe <uri>
-mcpc <target> resources-templates-list
-
-mcpc <target> logging-set-level <level>
-
-# Interactive MCP shell
-mcpc <target> shell
-
-# Persistent sessions
-mcpc <server> session @<session-name> [--profile <name>]
-mcpc @<session-name> <command...>
-mcpc @<session-name> close
-
-# Saved OAuth profiles for remote MCP servers
-mcpc <server> login [--profile <name>]
-mcpc <server> logout [--profile <name>]
+Usage: mcpc [options] [target] [command]
+
+Options:
+  -v, --version           Output the version number
+  -j, --json              Output in JSON format for scripting
+  --verbose               Enable verbose logging
+  -c, --config <file>     Path to MCP config JSON file (e.g. ".vscode/mcp.json")
+  -H, --header <header>   Add HTTP header (can be repeated)
+  --timeout <seconds>     Request timeout in seconds (default: 300)
+  --profile <name>        Authentication profile to use (default: "default")
+  --schema <file>         Validate against expected tool/prompt schema
+  --schema-mode <mode>    Schema validation mode: "strict", "compatible" (default), or "ignore"
+  --clean[=types]         Clean up mcpc data (types: "sessions,logs,profiles,all")
+  -h, --help              Display general help
+
+Targets:
+  <server-url>            Remote MCP server URL (e.g. "mcp.apify.com")
+  <config-entry>          Entry from MCP config file specified in --config (e.g. "fs")
+  @<session>              Named persistent session (e.g. "@apify")
+
+Commands:
+  help                    Show server info, instructions, and capabilities
+  shell                   Open interactive shell to run MCP commands)
+  login                   Create OAuth profile with credentials to access remote server
+  logout                  Remove OAuth profile
+  session @<session>      Create a named persistent session
+  restart @<session>      Kill and restart a session  
+  close @<session>        Close a session
 ```
 
 where `<target>` can be one of (in this order of precedence):
@@ -146,16 +188,6 @@ echo '{"query":"hello","count":10}' | mcpc @server tools-call my-tool
 - `=` assigns as string, `:=` parses as JSON
 - Stdin is automatically detected when input is piped (not interactive terminal)
 
-## Global flags
-
-- `--json` - Input and output in JSON format for scripting
-- `--config <file>` - Use MCP config JSON file (e.g., `.vscode/mcp.json`)
-- `-H, --header "Key: Value"` - Add HTTP header (can be repeated)
-- `-v, --verbose` - Enable verbose logging (shows protocol details)
-- `--timeout <seconds>` - Request timeout in seconds (default: 300)
-- `--schema <file>` - Validate against expected tool/prompt schema
-- `--schema-mode <mode>` - Schema validation mode: `strict`, `compatible`, or `ignore` (default: `compatible`)
-
 ## Authentication
 
 `mcpc` supports all standard [authentication methods](https://modelcontextprotocol.io/specification/latest/basic/authorization) for MCP servers,
@@ -210,7 +242,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 +347,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 +401,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)
@@ -398,6 +430,9 @@ mcpc
 mcpc @apify tools-list
 mcpc @apify shell
 
+# Restart the session (kills and restarts the bridge process)
+mcpc @apify restart
+
 # Close the session (terminates bridge process, but keeps authentication profile)
 mcpc @apify close
 ```
@@ -410,28 +445,66 @@ mcpc --json @apify tools-call search-actors --args query="tiktok scraper" \
   | mcpc @playwright tools-call run-browser
 ```
 
+### Output format
+
+#### Human-readable (default)
+
+Default output is formatted for human and AI readability with plain text, colors, and Markdown-like formatting.
+The text is formatted in Markdown-compatible format for AIs with colors for easy human readability.
+
+#### JSON mode
+
+If `--json` option is provided, `mcpc` always emits only a single JSON object, in order to enable scripting.
+For MCP commands, the returned objects are always consistent with the [MCP protocol specification](https://modelcontextprotocol.io/specification/latest).
+On success, the JSON object is printed to stdout, otherwise to stderr.
+
 ### Scripting
 
-`mcpc` is designed to be easily usable in (AI-generated) scripts. To ensure consistency
-of your scripts with the current MCP server interface, you can use `--schema <file>` argument
-to pass `mcpc` the expected schema. If the MCP server's current schema is incompatible,
-the command returns an error.
+`mcpc` is designed for us in (AI-generated) scripts.
+With the `--json` option, `mcpc` returns a single JSON object (object or array) as follows:
+
+- On success, the JSON object is printed to stdout
+- On error, the JSON object is printed to stderr
+
+You can use tools like `jq` to process the output.
+
+Note that `--json` option has no effect on `--help` command,
+or if there are invalid arguments, as those take precedence.
+
+For all MCP operations, the **returned JSON is and always will be strictly consistent
+with the [MCP specification](https://modelcontextprotocol.io/specification/latest)**,
+based to the protocol version negotiated between client and server in the initial handshake.
+
+Additionally, one of the core [design principles](CONTRIBUTING.md#design-principles) of `mcpc` 
+is to keep backwards compatibility to maximum extent possible, to ensure the scripts using `mcpc`
+will not break over time.
+
+#### MCP server schema changes
+
+MCP is a fluid protocol, and MCP servers can change operations and their schema at any time. 
+To ensure your scripts fail fast whenever such schema change occurs, rather than fail silently later,
+you can use the `--schema <file>` option to pass `mcpc` the expected operation schema.
+If the MCP server's current schema is incompatible, the command returns an error.
 
 ```bash
 # Save tool schema for future validation
-mcpc --json @apify tools-schema search-actors > search-actors-schema.json
+mcpc --json @apify tools-get search-actors > search-actors-schema.json
 
 # Use schema to ensure compatibility (fails if schema changed)
 mcpc @apify tools-call search-actors \
   --schema search-actors-schema.json \
   --schema-mode strict \
-  --args query="tiktok scraper"
+  --args keywords="tiktok scraper"
 ```
 
-**Schema validation modes using the `--schema-mode` parameter:**
-- `strict` - Exact schema match required (all fields, types must be identical)
-- `compatible` (default) - Backwards compatible (new optional fields OK, required fields and types must match)
-- `ignore` - Skip schema validation
+The `--schema-mode <mode>` parameter determines how `mcpc` validates the schema:
+
+- `compatible` (default) - Backwards compatible (new optional fields OK, types of required 
+  fields and passed arguments must match, descriptions are ignored). For tools, the output schema
+  is ignored.
+- `strict` - Exact schema match required (all fields, their types and descriptions must be 
+  identical). For tools, the output schema must match exactly.
+- `ignore` - Skip schema validation altogether
 
 ### Session failover
 
@@ -466,7 +539,9 @@ mcpc https://mcp.apify.com session @apify
 
 ## Logging
 
-The background bridge process logs to `~/.mcpc/bridges/mcpc-@<session-name>.log`.
+TODO: Move this to MPC features section
+
+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 +568,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.
@@ -593,6 +686,8 @@ Config files support environment variable substitution using `${VAR_NAME}` synta
 
 ## MCP protocol notes
 
+TODO: explain in detail how MCP concepts work in mcpc
+
 **Protocol initialization:**
 - `mcpc` follows the MCP initialization handshake: sends `initialize` request with protocol version and capabilities, receives server capabilities and instructions, then sends `initialized` notification
 - Protocol version negotiation: client proposes latest supported version (currently `2025-11-25`), server responds with version to use
@@ -607,10 +702,12 @@ Config files support environment variable substitution using `${VAR_NAME}` synta
 **Protocol features:**
 - `mcpc` supports all MCP primitives in both Streamable HTTP and stdio transports:
   - **Instructions**: Fetches and stores MCP server-provided `instructions`
-  - **Tools**: Executable functions with JSON Schema-validated arguments.
+  - **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
+  - **Asynchronous tasks**: Not implemented yet
+  - **Roots**: Not implemented yet
 - 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
@@ -618,38 +715,39 @@ Config files support environment variable substitution using `${VAR_NAME}` synta
 - Pings: `mcpc` periodically issues the MCP `ping` request to keep the connection alive
 - Sampling is not supported as `mcpc` has no access to an LLM
 
-## Output format
-
-### Human-readable (default)
-
-Default output is formatted for human and AI readability with plain text, colors, and Markdown-like formatting.
-
-### JSON mode (`--json`)
-
-In JSON mode, `mcpc` always emits only a single JSON object to enable scripting.
-For MCP commands, the object is always consistent with the MCP protocol specification.
-On success, the JSON object is printed to stdout, otherwise to stderr.
-
 ## Security
 
-MCP enables arbitrary tool execution and data access; treat servers like you treat shells:
+`mcpc` implements the [MCP security best practices](https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices) specification. MCP enables arbitrary tool execution and data access; treat servers like you treat shells:
 
 * Use least-privilege tokens/headers
 * Prefer trusted endpoints
 * Audit what tools do before running them
 * Review server permissions in interactive mode
 
+### Authentication
+
+**OAuth 2.1 with PKCE:**
+- Full OAuth 2.1 flow with PKCE (Proof Key for Code Exchange) via the MCP SDK
+- OAuth callback server binds to `127.0.0.1` only (not `0.0.0.0`)
+- Warning displayed for OAuth over plain HTTP (except localhost)
+- Dynamic client registration supported
+
+**Input validation:**
+- Session names validated: `^@[a-zA-Z0-9_-]{1,64}$`
+- Profile names validated: `^[a-zA-Z0-9_-]{1,64}$`
+- URLs normalized and validated (HTTPS enforced, credentials stripped)
+
 ### Credential storage
 
 **OS keychain integration:**
 - 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`
-- OAuth client: `mcpc:auth:<serverUrl>:<profileName>:oauth-client`
+- OAuth tokens: `mcpc:auth-profile:<host>:<profileName>:tokens`
+- OAuth client: `mcpc:auth-profile:<host>:<profileName>:client`
 - HTTP headers: `mcpc:session:<sessionName>:headers`
 
 ### Bridge process authentication
@@ -680,17 +778,18 @@ 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)
-- Bridge sockets in `~/.mcpc/bridges/` are created with `0700` permissions
-- Log files in `~/.mcpc/logs/` are created with `0600` permissions
+- `~/.mcpc/sessions.json` is created with `0600` permissions (user-only read/write)
+- `~/.mcpc/profiles.json` is created with `0600` permissions (user-only read/write)
+- Bridge sockets in `~/.mcpc/bridges/` use default umask (typically user-only)
+- File locking via `proper-lockfile` prevents race conditions on concurrent access
 
 ### Network security
 
-- HTTPS enforced for remote servers (HTTP auto-upgraded)
-- `Origin` header validation to prevent DNS rebinding attacks
-- Local servers bind to localhost (127.0.0.1) only
+- HTTPS enforced for remote servers (HTTP auto-upgraded when no scheme provided)
+- URL normalization removes username, password, and hash from URLs
+- Local OAuth callback server binds to `127.0.0.1` only
 - No credentials logged even in verbose mode
+- `MCP-Protocol-Version` and `MCP-Session-Id` headers handled per MCP spec
 
 ## Error handling
 
@@ -728,9 +827,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,195 +868,10 @@ 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
-
-`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
-- Minimal and portable (few deps, cross-platform)
-- No slop!
-
-### Architecture overview
-
-```
-TODO: add interaction diagram
-mcpc ──> cli ├──> bridge (UNIX socket) ──> MCP server (stdio/HTTP)
-             ├──> MCP server (stdio/HTTP)
-
-mcpc (single package)
-├── src/
-│   ├── core/           # Core MCP protocol implementation
-│   ├── bridge/         # Bridge process logic
-│   ├── cli/            # CLI interface
-│   └── lib/            # Shared utilities
-├── bin/
-│   ├── mcpc            # Main CLI executable
-│   └── mcpc-bridge     # Bridge process executable
-```
-
-### Core module (runtime-agnostic)
-
-Implemented with minimal dependencies to support both Node.js (≥18.0.0) and Bun (≥1.0.0).
-
-**Core responsibilities:**
-- Transport selection and initialization (Streamable HTTP vs stdio)
-- MCP protocol implementation and version negotiation
-- Session state machine management
-- Streamable HTTP connection management (reconnection with exponential backoff)
-- Request/response correlation (JSON-RPC style with request IDs)
-- Multiplexing concurrent requests (up to 10 concurrent)
-- Event emitter for async notifications
-
-**Key dependencies:**
-- Native `fetch` API (available in Node.js 18+ and Bun)
-- Native process APIs for stdio transport
-- Minimal: UUID generation, event emitter abstraction
-
-### Bridge process
-
-Implemented as a separate executable (`mcpc-bridge`) that maintains persistent connections.
-
-**Bridge responsibilities:**
-- Session persistence (reads/writes `~/.mcpc/sessions.json` with file locking)
-- Process lifecycle management for local package servers
-- Stdio framing and protocol handling
-- Unix domain socket server for CLI communication
-- Heartbeat mechanism for health monitoring
-- Orphaned process cleanup on startup
-
-**IPC protocol:**
-- Unix domain sockets (located in `~/.mcpc/bridges/<session-name>.sock`)
-- Named pipes on Windows
-- JSON-RPC style messages over socket
-- Control messages: init, request, cancel, close, health-check
-
-**Bridge discovery:**
-- CLI reads `~/.mcpc/sessions.json` to find socket path and PID
-- Validates bridge is alive (connect to socket + health-check)
-- Auto-restarts crashed bridges (detected via socket connection failure)
-- Cleanup: removes stale socket files for dead processes
-
-**Concurrency safety:**
-- `~/.mcpc/sessions.json` protected with file locking (`proper-lockfile` package)
-- Atomic writes (write to temp file, then rename)
-- Lock timeout: 5 seconds (fails if can't acquire lock)
-
-### CLI executable
-
-The main `mcpc` command provides the user interface.
-
-**CLI responsibilities:**
-- Argument parsing (using `minimist` or similar)
-- Output formatting (human-readable vs `--json`)
-- Bridge lifecycle: start/connect/stop
-- Communication with bridge via socket
-- Interactive shell (REPL using `@inquirer/prompts`)
-- 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
-- Graceful exit handling (cleanup on Ctrl+C/Ctrl+D)
-
-### Session lifecycle
-
-1. User: `mcpc https://mcp.apify.com session @apify`
-2. CLI: Atomically creates session entry in `~/.mcpc/sessions.json`
-3. CLI: Spawns bridge process (`mcpc-bridge`)
-4. Bridge: Creates Unix socket at `~/.mcpc/bridges/apify.sock`
-5. Bridge: Performs MCP initialization handshake with server:
-   - Sends initialize request with protocol version and capabilities
-   - Receives server info, version, and capabilities
-   - Sends initialized notification to activate session
-6. Bridge: Updates session in `~/.mcpc/sessions.json` (adds PID, socket path, protocol version)
-7. CLI: Confirms session created
-
-Later...
-
-8. User: mcpc @apify tools-list
-9. CLI: Reads `~/.mcpc/sessions.json`, finds socket path
-10. CLI: Connects to bridge socket
-11. CLI: Sends `tools/list` JSON-RPC request via socket
-12. Bridge: Forwards to MCP server via Streamable HTTP
-13. Bridge: Returns response via socket
-14. CLI: Formats and displays to user
-
-
-### Error recovery
-
-**Bridge crashes:**
-1. CLI detects socket connection failure
-2. Reads `~/.mcpc/sessions.json` for last known config
-3. Spawns new bridge process
-4. Bridge re-initializes connection to MCP server
-5. Continues request
-
-**Network failures:**
-1. Bridge detects connection error
-2. Begins exponential backoff reconnection
-3. Queues incoming requests (up to 100, max 3min)
-4. On reconnect: drains queue
-5. On timeout: fails queued requests with network error
-
-**Orphaned processes:**
-1. On startup, CLI scans `~/.mcpc/bridges/` directory
-2. For each socket file, attempts connection
-3. If connection fails, reads PID from sessions.json
-4. Checks if process exists (via `kill -0` or similar)
-5. If dead: removes socket file and session entry
-6. If alive but unresponsive: kills process, removes entries
-
-## Testing strategy
-
-**Unit tests:**
-- Core protocol implementation (mocked transports)
-- Argument parsing and validation
-- Output formatting (human and JSON modes)
-
-**Integration tests:**
-- Mock MCP server (simple Streamable HTTP + stdio servers)
-- Bridge lifecycle (start, connect, restart, cleanup)
-- Session management with file locking
-- Stream reconnection logic
-
-**E2E tests:**
-- Real MCP server implementations
-- Cross-runtime (Node.js and Bun)
-- Interactive shell workflows
-
-**Test utilities:**
-- `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`:
+To see what's happening, enable detailed logging with `--verbose`:
 
 ```bash
 mcpc --verbose @apify tools-list
@@ -979,62 +892,30 @@ Bridge processes log to:
 
 Log rotation: Keep last 10MB per session, max 5 files.
 
-## Contributing
-
-Contributions are welcome!
-
-### Development setup
-
-```bash
-# Clone repository
-git clone https://github.com/apify/mcpc.git
-cd mcpc
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Build
-npm run build
-
-# Test locally
-npm link
-mcpc --help
-```
-
-### Release process
-
-```bash
-# Run tests
-npm test
-
-# Build
-npm run build
-
-# Bump version
-npm version patch|minor|major
+### Common issues
 
-# Publish
-npm publish
+**"Cannot connect to bridge"**
+- Bridge may have crashed. Try: `mcpc @<session-name> tools-list` to restart the bridge
+- Check bridge is running: `ps aux | grep -e 'mcpc-bridge' -e '[m]cpc/dist/bridge'`
+- Check socket exists: `ls ~/.mcpc/bridges/`
 
-# Push tags
-git push --tags
-```
+**"Session not found"**
+- List existing sessions: `mcpc`
+- Create new session if expired: `mcpc @<session-name> close` and `mcpc <target> session @<session-name>`
 
-Please open an issue or pull request on [GitHub](https://github.com/apify/mcpc).
+**"Authentication failed"**
+- List saved OAuth profiles: `mcpc`
+- Re-authenticate: `mcpc <server> login [--profile <name>]`
+- For bearer tokens: provide `--header "Authorization: Bearer ${TOKEN}"` again
 
 
-### References
+## Contributing
 
-- [Official MCP documentation](https://modelcontextprotocol.io/llms.txt)
-- [Official TypeScript SDK for MCP servers and clients](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
-- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - CLI client implementation for reference
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, architecture overview, and contribution guidelines.
 
 ## Authors
 
-Built by [Jan Curn](https://x.com/jancurn), [Apify](https://apify.com), and contributors welcome.
+Built by [Jan Curn](https://x.com/jancurn) / [Apify](https://apify.com).
 
 ## License