Supercli MCP Dev

Supercli MCP Development

Work on MCP (Model Context Protocol) features in supercli including adapter implementation, SSE streaming support, and server integration.

MCP Adapter Architecture

The MCP adapter (cli/adapters/mcp.js) supports multiple transport modes:

Transport Modes

1. HTTP/SSE MCP: HTTP-based MCP servers with SSE streaming
2. Stdio MCP with Daemon: Local stdio MCP servers routed through daemon
3. Stdio MCP Direct: Direct stdio calls (may have compatibility issues)

Key Components

• execute(): Main entry point, routes to appropriate transport
• callHttpMcpTool(): HTTP/SSE MCP handler with JSON-RPC support
• parseSseResponse(): SSE event parser
• callStdioTool(): Direct stdio execution
• stdioCallToolJsonRpc(): Stdio JSON-RPC protocol handler
• callDaemonTool(): Daemon-routed stdio calls

HTTP/SSE Implementation

Request Format

Uses JSON-RPC 2.0 format for HTTP MCP calls:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": toolName,
    "arguments": input
  },
  "id": 1
}

Headers

Must include both content types for SSE negotiation:

{
  "Content-Type": "application/json",
  "Accept": "text/event-stream, application/json"
}

SSE Response Parsing

Parses Server-Sent Events format:

• Lines starting with event: define event type
• Lines starting with data: contain event data
• Empty lines terminate events
• Accumulates chunks and returns final result

Auto-detection

Automatically detects SSE responses via Content-Type header and falls back to JSON if not SSE.

Stdio MCP with Daemon

Configuration

{
  "adapterConfig": {
    "server": "mcp-server-name",
    "tool": "tool-name",
    "stateful": true,
    "timeout_ms": 60000
  }
}

Daemon Client

• File: cli/mcp-daemon-client.js
• Functions: callDaemonTool(), listDaemonTools()
• Maintains persistent sessions for stateful MCP servers
• Daemon runs on CLI side (not server) - starts on-demand when first command with stateful: true is executed via CLI
• Runs as detached background process with Unix socket at ~/.supercli/mcp-daemon.sock
• Persists across command executions to maintain MCP server sessions
• Better for long-running stdio MCP servers

Daemon Lifecycle:

• Auto-starts on first CLI command execution (checks socket, spawns daemon if not running)
• Server UI only stores configuration; CLI syncs and executes
• Manual control: supercli mcp daemon start/stop/status
• Detached process (unref) - doesn't block CLI
• 5-second startup timeout with retry checks

mcp-proxy Integration

What is mcp-proxy?

Transforms stdio MCP servers into HTTP/SSE endpoints. Useful for:

• Exposing local stdio MCPs over HTTP
• Testing MCP tools via HTTP clients
• Bridging stdio to SSE transport

Usage Pattern

# Start mcp-proxy
npx -y mcp-proxy --port 3002 -- npx -y @andredezzy/deep-directory-tree-mcp

# Add to supercli
supercli server mcp add '{"name":"deep-tree","url":"http://localhost:3002"}'

# Create command
supercli server commands add '{"namespace":"tree","resource":"deep","action":"list","adapter":"mcp","adapterConfig":{"url":"http://localhost:3002","tool":"get_deep_directory_tree"}}'

# Sync and use
supercli sync
supercli tree deep list --path /some/dir --depth 3

mcp-proxy Options

• --port: Port to listen on (default: 8080)
• --streamEndpoint: HTTP endpoint path (default: /mcp)
• --stateless: Disable session management
• --sseEndpoint: SSE endpoint path (default: /sse)

Server-Side MCP Management

Server Routes

• POST /api/mcp: Add MCP server
• GET /api/mcp: List MCP servers
• DELETE /api/mcp/:name: Remove MCP server

MCP Server Entry Format

{
  "name": "server-name",
  "url": "http://localhost:3002",
  "command": "npx -y @package",
  "args": ["--arg1", "--arg2"],
  "stateful": true,
  "timeout_ms": 60000,
  "headers": {},
  "env": {}
}

Server UI

• /mcp: MCP server management UI
• Add/remove servers
• View server status
• Test MCP tools

Client-Side MCP Usage

Command Configuration

{
  "namespace": "mcp",
  "resource": "server",
  "action": "tool",
  "adapter": "mcp",
  "adapterConfig": {
    "server": "mcp-server-name",
    "tool": "tool-name",
    "stateful": true
  }
}

Argument Passing

Use space syntax for CLI arguments:

• ✅ supercli tree deep list --path /dir --depth 2
• ❌ supercli tree deep list --path=/dir --depth=2

The supercli argument parser treats --key=value as a boolean flag with key=key=value, not as a key-value pair.

Testing MCP Integration

Test with mcp-proxy

# Start proxy
npx -y mcp-proxy --port 3002 -- npx -y @andredezzy/deep-directory-tree-mcp

# List tools
curl http://localhost:3002/tool -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream, application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call tool
curl http://localhost:3002/tool -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream, application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"tool-name","arguments":{}},"id":1}'

Test with Daemon

# Test daemon connection
node cli/mcp-daemon-client.js

# List tools via daemon
# (daemon client handles this internally)

Common Issues

"Not Acceptable: Client must accept both application/json and text/event-stream"

Cause: mcp-proxy requires SSE Accept header.

Fix: Ensure MCP adapter sends Accept: text/event-stream, application/json.

"Parse error: Invalid JSON-RPC message"

Cause: Wrong request format for HTTP MCP.

Fix: Use JSON-RPC 2.0 format with jsonrpc, method, params, and id fields.

"Tool not found"

Cause: Incorrect tool name or tool not exposed by MCP server.

Fix: Use tools/list method to discover available tool names.

"Input validation error"

Cause: Arguments not passed correctly or in wrong format.

Fix: Use space syntax (--key value) and verify argument schema matches tool expectations.

File Locations

• MCP Adapter: cli/adapters/mcp.js
• Daemon Client: cli/mcp-daemon-client.js
• Stdio JSON-RPC: cli/mcp-stdio-jsonrpc.js
• Server MCP Routes: server/routes/mcp.js
• Server MCP Service: server/services/mcpService.js

Development Workflow

1. Implement MCP adapter changes
2. Test with local stdio MCP or mcp-proxy
3. Update docs/server.md with new features
4. Update supercli-cli-admin-cheatsheet skill
5. Test via CLI commands
6. Verify server UI integration

Future Enhancements

• Streaming output: Implement --stream flag for incremental SSE output
• Session management: Add automatic session ID handling for stateful HTTP MCP
• Tool discovery: Auto-discover tools from MCP servers
• Schema validation: Validate arguments against tool input schemas