@apify/mcpc 0.1.0

package/TESTING.md

@@ -0,0 +1,212 @@
+# Quick Testing Guide for mcpc
+
+This guide provides quick commands to test the current implementation of mcpc.
+
+## Prerequisites
+
+```bash
+npm install
+npm run build
+```
+
+## Quick Tests
+
+### 1. Help and Version
+
+```bash
+# Show help
+node dist/cli/index.js --help
+
+# Show version
+node dist/cli/index.js --version
+```
+
+### 2. HTTP URL Targets
+
+```bash
+# Try to connect to a URL (will fail - no real server)
+node dist/cli/index.js https://example.com/mcp tools-list
+
+# With verbose logging
+node dist/cli/index.js https://example.com/mcp --verbose tools-list
+```
+
+### 3. Config File Loading
+
+```bash
+# List servers in config
+cat examples/test-config.json
+
+# Use HTTP server from config (will fail to connect)
+node dist/cli/index.js --config examples/test-config.json example-http tools-list
+
+# Try non-existent server (shows error)
+node dist/cli/index.js --config examples/test-config.json bad-server tools-list
+
+# Test environment variable substitution
+EXAMPLE_API_TOKEN=secret123 node dist/cli/index.js \
+  --config examples/test-config.json example-http tools-list
+```
+
+### 4. Package Resolution
+
+```bash
+# Create test package in node_modules
+mkdir -p node_modules/example-mcp-server
+cp -r examples/test-package/* node_modules/example-mcp-server/
+
+# Try to use the package (will fail - not a real MCP server)
+node dist/cli/index.js example-mcp-server tools-list
+
+# Try non-existent package (shows helpful error)
+node dist/cli/index.js nonexistent-package tools-list
+
+# With verbose to see resolution details
+node dist/cli/index.js example-mcp-server --verbose tools-list
+```
+
+### 5. Named Sessions (Not Implemented)
+
+```bash
+# Try named session (shows "not implemented")
+node dist/cli/index.js @my-session tools-list
+```
+
+## Real MCP Server Testing
+
+To test with an actual MCP server, you can:
+
+### Option 1: Install an official MCP server package
+
+```bash
+# Install a real MCP server (example - adjust as needed)
+npm install -g @modelcontextprotocol/server-filesystem
+
+# Use it with mcpc
+mcpc @modelcontextprotocol/server-filesystem tools-list
+```
+
+### Option 2: Use a remote MCP server
+
+```bash
+# If you have access to a real MCP server URL
+mcpc https://your-mcp-server.com tools-list
+mcpc https://your-mcp-server.com resources-list
+```
+
+### Option 3: Create a config file for your servers
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "url": "https://my-real-mcp-server.com",
+      "headers": {
+        "Authorization": "Bearer ${MY_API_KEY}"
+      }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    }
+  }
+}
+```
+
+Then use it:
+```bash
+MY_API_KEY=secret mcpc --config my-config.json my-server tools-list
+mcpc --config my-config.json filesystem resources-list
+```
+
+## Unit Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+npm test -- test/lib/config.test.ts
+npm test -- test/lib/logger.test.ts
+
+# Run with coverage
+npm run test:coverage
+
+# Watch mode
+npm run test:watch
+```
+
+## Linting
+
+```bash
+# Check for issues
+npm run lint
+
+# Auto-fix issues
+npm run lint:fix
+```
+
+## Expected Behaviors
+
+### ✅ Should Work
+
+- CLI help and version display
+- HTTP URL parsing and resolution
+- Config file loading and parsing
+- Environment variable substitution in configs
+- Package discovery in node_modules
+- Global package discovery (npm and Bun)
+- Clear error messages for missing files/packages
+- Verbose logging with --verbose flag
+
+### ❌ Will Fail (Expected)
+
+These will fail because they require actual MCP servers:
+
+- Connecting to example.com (not an MCP server)
+- Using the test package (doesn't implement MCP protocol)
+- Any command that needs actual MCP communication
+
+These will fail because they're not implemented yet:
+
+- Named sessions (@session-name)
+- Session commands (connect, close)
+- Interactive shell
+
+## Troubleshooting
+
+### "Package not found" error
+- Make sure the package is installed in node_modules or globally
+- Check the package name spelling
+- Verify package.json exists in the package
+
+### "Config file not found" error
+- Check the path to the config file
+- Use absolute path or path relative to current directory
+
+### "Server not found in config" error
+- Check the server name matches exactly (case-sensitive)
+- List available servers in the error message
+
+### "Failed to connect" error
+- This is expected when testing with non-real MCP servers
+- Use a real MCP server URL or package to test actual connections
+
+## What's Next
+
+After confirming tests work, you can proceed with:
+
+**Phase 2: Bridge & Sessions**
+- Persistent MCP connections
+- Session management
+- Unix socket IPC
+
+**Phase 3: Authentication**
+- OAuth 2.1 support
+- Keychain integration
+- Auth profile management
+
+**Phase 4: Enhancements**
+- Interactive shell
+- Caching
+- Tab completion

package/TODOs.md

@@ -0,0 +1,94 @@
+
+# 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
+
+
+- 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
+- > # 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: 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?)
+- 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
+- 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
+
+
+
+## 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:
+  - --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.
+- Things to test:
+  - handling of errors, invalid params, names, etc.
+  - pagination
+  - env vars...
+  - stdio + filesystem operations,
+  - sessions
+  - 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 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?
+- Text copy can change, but the core texts needs to be shown in both text and JSON mode
+

package/bin/mcpc

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+// Main CLI executable for mcpc
+// This wrapper imports the compiled TypeScript CLI entry point
+
+import('../dist/cli/index.js').catch((err) => {
+  console.error('Failed to load mcpc CLI:', err.message);
+  process.exit(1);
+});

package/bin/mcpc-bridge

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+// Bridge process executable for mcpc
+// This wrapper imports the compiled TypeScript bridge entry point
+
+import('../dist/bridge/index.js').catch((err) => {
+  console.error('Failed to load mcpc-bridge:', err.message);
+  process.exit(1);
+});

package/dist/bridge/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/bridge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bridge/index.ts"],"names":[],"mappings":""}