@apify/mcpc 0.1.4 → 0.1.6

package/docs/TODOs.md

@@ -0,0 +1,40 @@
+
+# TODOs
+
+
+- `--capabilities '{"tools":...,"prompts":...}"` to limit access to selected MCP features and tools,
+  for both proxy and normal session, for simplicity.
+- Implement resources-subscribe/resources-unsubscribe, --o file command properly, --max-size
+  automatically update the -o file on changes, without it just keep track of changed files in
+  bridge process' cache, and report in resources-list/resources-read operation
+- Store last time of all listChanged notifications on session object, so that users can see it and act on that.
+
+- Ensure "logging-set-level" works well
+
+## Later
+
+- nit: in "login", make profile color consistent with "mcpc"
+- nit: show also header / open auth statuses for HTTP servers?
+- ux: consider forking "alive" session state to "alive" and "diconnected", to indicate the remove server is not responding but bridge 
+  runs fine. We can use lastSeenAt + ping interval info for that, or status of last ping.
+- perf: make the libsecret dependency soft - only load it when using keychain, but skip for auth-less (AI sandbox) use
+- ux: Be even more forgiving with `args:=x`, when we know from tools/prompt schema the text is compatible with `x` even if the exact type is not - 
+  just re-type it dynamically to make it work.
+- nit: Cooler OAuth flow finish web page with CSS animation, add Apify example there, show mcpc info. E.g. next step - check Apify rather than close
+- security: For auth profiles, fetch the detailed user info via http, save to profiles.json and show in 'mcpc', ensure the info is up-to-date
+- later: Add unique Session.id and Profile.id and use it for OS keychain keys, to truly enable using multiple independent mcpc profiles. Use cry
+- nit: Implement typing completions (e.g. "mcpc @ap...") - not sure if that's even possible
+- later: maybe add --no-color option to disable chalk
+
+## E2E test scenarios
+
+- On "npm run release", make the two skippable OAuth e2e tests mandatory
+
+- 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.
+  We could have some special dir for long-term testing...
+
+
+# Questions
+
+- mcpc mcp.apify.com shell --- do we also open "virtual" session, how does it work exactly? Let's explain this in README.

package/docs/claude-skill/SKILL.md

@@ -22,7 +22,7 @@ mcpc @<session>
 # Tools
 mcpc <target> tools-list
 mcpc <target> tools-get <tool-name>
-mcpc <target> tools-call <tool-name> --args '{"key":"value"}'
+mcpc <target> tools-call <tool-name> key:=value key2:="string value"
 
 # Resources
 mcpc <target> resources-list
@@ -30,10 +30,10 @@ mcpc <target> resources-read <uri>
 
 # Prompts
 mcpc <target> prompts-list
-mcpc <target> prompts-get <prompt-name> --args key=value
+mcpc <target> prompts-get <prompt-name> arg1:=value1
 
 # Sessions (persistent connections)
-mcpc <server> session @<name>
+mcpc <server> connect @<name>
 mcpc @<name> <command>
 mcpc @<name> close
 
@@ -44,34 +44,32 @@ mcpc <server> logout
 
 ## Target types
 
-- `mcp.example.com` - Direct HTTP connection to remote server
+- `mcp.example.com` - Direct HTTPS connection to remote server
+- `localhost:8080` or `127.0.0.1:8080` - Local HTTP server (http:// is default for localhost)
 - `@session-name` - Named persistent session (faster, maintains state)
 - `config-entry` - Entry from config file (with `--config`)
 
 ## Passing arguments
 
-**Inline JSON** (recommended for complex data):
-```bash
-mcpc @s tools-call search --args '{"query":"hello","limit":10}'
-```
+Arguments use `key:=value` syntax. Values are auto-parsed as JSON when valid:
 
-**Key=value pairs** (strings):
 ```bash
-mcpc @s tools-call search --args query="hello world" filter=active
-```
+# String values
+mcpc @s tools-call search query:="hello world"
 
-**Key:=json pairs** (typed values):
-```bash
-mcpc @s tools-call search --args query="hello" limit:=10 enabled:=true
-```
+# Numbers, booleans, null (auto-parsed as JSON)
+mcpc @s tools-call search query:="hello" limit:=10 enabled:=true
 
-**From file**:
-```bash
-mcpc @s tools-call search --args-file params.json
-```
+# Complex JSON values
+mcpc @s tools-call search config:='{"nested":"value"}' items:='[1,2,3]'
 
-**From stdin** (auto-detected when piped):
-```bash
+# Force string type with JSON quotes
+mcpc @s tools-call search id:='"123"'
+
+# Inline JSON object (if first arg starts with { or [)
+mcpc @s tools-call search '{"query":"hello","limit":10}'
+
+# From stdin (auto-detected when piped)
 echo '{"query":"hello"}' | mcpc @s tools-call search
 ```
 
@@ -84,7 +82,7 @@ Always use `--json` flag for machine-readable output:
 mcpc --json @apify tools-list
 
 # Call tool and parse result with jq
-mcpc --json @apify tools-call search --args query="test" | jq '.content[0].text'
+mcpc --json @apify tools-call search query:="test" | jq '.content[0].text'
 
 # Chain commands
 mcpc --json @server1 tools-call get-data | mcpc @server2 tools-call process
@@ -96,28 +94,50 @@ Create sessions for repeated interactions:
 
 ```bash
 # Create session (or reconnect if exists)
-mcpc mcp.apify.com session @apify
+mcpc mcp.apify.com connect @apify
 
 # Use session (faster - no reconnection overhead)
 mcpc @apify tools-list
-mcpc @apify tools-call search --args query="test"
+mcpc @apify tools-call search query:="test"
+
+# Restart session (useful after server updates)
+mcpc @apify restart
 
 # Close when done
 mcpc @apify close
 ```
 
+**Session states:**
+- 🟢 **live** - Bridge running, server might or might not be responding
+- 🟡 **crashed** - Bridge crashed; auto-restarts on next use
+- 🔴 **expired** - Server rejected session; needs `close` and reconnect
+
 ## Authentication
 
 **OAuth (interactive login)**:
 ```bash
 mcpc mcp.apify.com login
-mcpc mcp.apify.com session @apify
+mcpc mcp.apify.com connect @apify
 ```
 
 **Bearer token**:
 ```bash
 mcpc -H "Authorization: Bearer $TOKEN" mcp.apify.com tools-list
-mcpc -H "Authorization: Bearer $TOKEN" mcp.apify.com session @myserver
+mcpc -H "Authorization: Bearer $TOKEN" mcp.apify.com connect @myserver
+```
+
+## Proxy server for AI isolation
+
+Create a proxy MCP server that hides authentication tokens:
+
+```bash
+# Human creates authenticated session with proxy
+mcpc mcp.apify.com connect @ai-proxy --proxy 8080
+
+# AI agent connects to proxy (no access to original tokens)
+# Note: localhost defaults to http://
+mcpc localhost:8080 tools-list
+mcpc 127.0.0.1:8080 connect @sandboxed
 ```
 
 ## Common patterns
@@ -130,7 +150,7 @@ mcpc @s tools-get tool-name
 
 **Call tool and extract text result**:
 ```bash
-mcpc --json @s tools-call my-tool --args '{}' | jq -r '.content[0].text'
+mcpc --json @s tools-call my-tool | jq -r '.content[0].text'
 ```
 
 **Read resource content**:
@@ -155,5 +175,10 @@ mcpc --config .vscode/mcp.json filesystem resources-list
 
 ```bash
 # Verbose output shows protocol details
-mcpc --verbose @s tools-call my-tool --args '{}'
+mcpc --verbose @s tools-call my-tool
 ```
+
+## Example script
+
+See [`docs/examples/company-lookup.sh`](../examples/company-lookup.sh) for a complete example
+of an AI-generated script that validates prerequisites and calls MCP tools.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apify/mcpc",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Universal command-line client for the Model Context Protocol (MCP).",
   "type": "module",
   "keywords": [
@@ -30,7 +30,7 @@
   "scripts": {
     "build": "tsc",
     "build:watch": "tsc --watch",
-    "build:toc": "doctoc README.md --github --notitle && sed -i '' '/^- \\[mcpc:/d' README.md",
+    "build:readme": "./scripts/update-readme.sh",
     "test": "npm run build && npm run test:unit && ./test/e2e/run.sh --no-build",
     "test:unit": "jest",
     "test:watch": "jest --watch",
@@ -45,7 +45,7 @@
     "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
     "clean": "rm -rf dist",
     "prebuild": "npm run clean",
-    "prepublishOnly": "npm run lint && npm run build && npm test",
+    "prepublishOnly": "npm run lint && npm run build:readme && npm run build && npm run test:unit && ./test/e2e/run.sh --no-build --parallel 1",
     "release": "bash scripts/publish.sh",
     "release:minor": "bash scripts/publish.sh minor",
     "release:major": "bash scripts/publish.sh major"
@@ -72,6 +72,7 @@
     "doctoc": "^2.2.1",
     "eslint": "^8.57.1",
     "jest": "^30.2.0",
+    "markdown-link-check": "^3.14.2",
     "nyc": "^17.1.0",
     "prettier": "^3.7.4",
     "ts-jest": "^29.4.6",

package/PUBLISHING.md

@@ -1,111 +0,0 @@
-# Publishing Guide
-
-## Reserve Package Name (Placeholder)
-
-To reserve the `mcpc` package name on npm without publishing the full implementation:
-
-1. Make sure you're logged in to npm:
-   ```bash
-   npm login
-   ```
-
-2. Run the placeholder publish script:
-   ```bash
-   npm run publish:placeholder
-   ```
-
-This will publish `mcpc@0.0.1` with a minimal placeholder that:
-- Reserves the package name
-- Points users to the GitHub repository
-- Clearly indicates the package is under development
-
-## Publish Full Version
-
-When ready to publish the full implementation:
-
-1. **Ensure everything is ready:**
-   ```bash
-   npm run build
-   npm test
-   npm run lint
-   ```
-
-2. **Update version** (choose appropriate level):
-   ```bash
-   npm version patch  # 0.0.1 -> 0.0.2
-   npm version minor  # 0.0.x -> 0.1.0
-   npm version major  # 0.x.x -> 1.0.0
-   ```
-
-3. **Publish:**
-   ```bash
-   npm publish --access public
-   ```
-
-   The `prepublishOnly` script will automatically:
-   - Clean the dist folder
-   - Run the build
-   - Run all tests
-
-4. **Push git tags:**
-   ```bash
-   git push --follow-tags
-   ```
-
-## What Gets Published
-
-Files included in the npm package (see `.npmignore`):
-- ✅ `dist/` - Compiled JavaScript
-- ✅ `bin/` - CLI executables
-- ✅ `package.json`
-- ✅ `README.md`
-- ✅ `LICENSE`
-
-Files excluded:
-- ❌ `src/` - TypeScript source (users only need compiled JS)
-- ❌ `test/` - Test files
-- ❌ `scripts/` - Development scripts
-- ❌ Config files (tsconfig.json, etc.)
-
-## Testing the Package Locally
-
-Before publishing, test what will be included:
-
-```bash
-# See what files will be published
-npm pack --dry-run
-
-# Create a tarball to inspect
-npm pack
-
-# Test installation locally
-npm install -g ./mcpc-0.1.0.tgz
-mcpc --help
-npm uninstall -g mcpc
-```
-
-## Version Strategy
-
-- `0.0.x` - Placeholder / early development
-- `0.1.0` - First functional release (direct connection working)
-- `0.2.0` - Add session management / bridge process
-- `0.3.0` - Add interactive shell
-- `1.0.0` - Stable release with all core features
-
-## Troubleshooting
-
-### "You do not have permission to publish"
-Make sure you're logged in: `npm whoami`
-
-### "Package name too similar to existing package"
-The name `mcpc` should be available, but if not, consider:
-- `@apify/mcpc` (scoped package)
-- `mcp-cli`
-- `mcpcli`
-
-### "prepublishOnly script failed"
-Fix any build or test errors before publishing:
-```bash
-npm run build
-npm test
-```

package/TODOs.md

@@ -1,46 +0,0 @@
-
-# TODOs
-
-## Next
-
-- Simplify README - there are too many top-level sections, and then show just the second level ones
-  - in README, explain the MCP commands better in a standalone section, with details how they work
-  - Expand --help to use same text as in README, add link to README
-
-- We support "prompts", "tools" etc commands ... do we need to?
-
-## MCP features
-
-- Add `--proxy [HOST:]PORT` feature to `connect` command to enable MCP proxy:
-  - `--proxy-bearer-token X` for proxy 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 resources-subscribe/resources-unsubscribe, --o file command properly, --max-size
-  automatically update the -o file on changes, without it just keep track of changed files in
-  bridge process' cache, and report in resources-list/resources-read operation
-- Add support for asynchronous tasks
-- Add support for client roots, need to figure how exactly
-
-## Later
-
-- Check how we deal with connection and command timeouts, that --timeout and timeout from config 
-  file are obeyed
-
-- Consider adding 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, show mcpc info. E.g. next step - check Apify rather than close
-- nit: For auth profiles, fetch the detailed user info via http, ensure the info is up-to-date
-- nit: add more shortcuts, e.g. --profile => -p
-- later: Add unique Session.id and Profile.id and use it for OS keychain keys, to truly enable using multiple independent mcpc profiles
-- nit: Implement typing completions (e.g. "mcpc @a...") - not sure if that's even possible
-
-
-## E2E test scenarios
-
-Later
-- 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.
-  We could have some special dir for long-term testing...