Rovodev CLI MCP

An MCP server wrapper that exposes Rovodev CLI as MCP tools. Modeled after gemini-mcp-tool.

Install

npm install -g rovodev-cli-mcp

Or use with npx:

npx -y rovodev-cli-mcp

Configure in Claude Desktop

{
  "mcpServers": {
    "rovodev": {
      "command": "npx",
      "args": ["-y", "rovodev-cli-mcp"]
    }
  }
}

Environment variables to customize underlying CLI:

• ROVODEV_CLI_PATH or ROVODEV_CMD (default: acli)
• ROVODEV_SUBCOMMAND (default: "rovodev run")
• ROVODEV_CONFIG_FLAG (default: --config-file)
• ROVODEV_SHADOW_FLAG (default: --shadow)
• ROVODEV_VERBOSE_FLAG (default: --verbose)
• ROVODEV_RESTORE_FLAG (default: --restore)
• ROVODEV_YOLO_FLAG (default: --yolo)
• ROVODEV_HELP_FLAG (default: --help)

Chunking configuration (for large responses):

• MCP_CHUNK_SIZE (preferred)
• ROVODEV_CHUNK_SIZE (legacy) The first one found is used; default is 20000 characters if none are set.

Global setup for Claude Code (user scope)

Install the MCP server for your user so it’s available across projects in Claude Code.

• Add with npx (no global npm install required):

  claude mcp add -s user rovodev -- npx -y rovodev-cli-mcp
  

• Optional: use a globally installed binary instead of npx

  npm i -g rovodev-cli-mcp
  claude mcp add -s user rovodev rovodev-cli-mcp
  

• Optional: set environment overrides when adding

  claude mcp add -s user rovodev -- \
    npx -y rovodev-cli-mcp \
    -e ROVODEV_CLI_PATH=acli \
    -e ROVODEV_SUBCOMMAND="rovodev run" \
    -e ROVODEV_CONFIG_FLAG=--config-file \
    -e ROVODEV_SHADOW_FLAG=--shadow \
    -e ROVODEV_VERBOSE_FLAG=--verbose \
    -e ROVODEV_RESTORE_FLAG=--restore \
    -e ROVODEV_YOLO_FLAG=--yolo \
    -e ROVODEV_HELP_FLAG=--help
  

• Verify it’s connected:

  claude mcp list
  

• Remove from user scope (to update or uninstall):

  claude mcp remove -s user rovodev
  

Global setup for Amazon Q CLI

Install the MCP server for Amazon Q CLI to use Rovodev tools in Q chat sessions.

• Add with npx (no global npm install required):

  q mcp add --name rovodev --command npx --args "-y,rovodev-cli-mcp"
  

• Optional: set environment variables when adding

  q mcp add --name rovodev --command npx --args "-y,rovodev-cli-mcp" \
    --env "ROVODEV_CLI_PATH=acli" \
    --env "ROVODEV_SUBCOMMAND=rovodev run"
  

• Verify it's installed:

  q mcp list
  

• Check server status:

  q mcp status --name rovodev
  

• Remove (to update or uninstall):

  q mcp remove --name rovodev
  

Using tools in Q CLI: Tools are available with the rovodev___ prefix:

• rovodev___ask-rovodev - Send messages to Rovodev agent (enhanced with session support)
• rovodev___tap-rovodev - Alias for ask-rovodev
• rovodev___session_manager - Manage isolated sessions for context persistence
• rovodev___health_check - Check server health and CLI availability
• rovodev___diagnostics - Get comprehensive system diagnostics
• rovodev___next-chunk - Fetch next chunk for large responses
• rovodev___fetch-chunk - Fetch specific chunk by index
• rovodev___Help - Show Rovodev CLI help
• rovodev___Ping - Test connectivity

Local development with Claude Code

If you are iterating on this repo and want Claude Code to use your local build:

1. Install deps and build

npm i
npm run build

2. Point Claude Code at your local dist/index.js

claude mcp remove -s user rovodev || true
claude mcp add -s user rovodev -- node "$(pwd)/dist/index.js"

3. Verify connection

claude mcp list

4. Optional: quick smoke test (no Claude required)

node scripts/smoke.mjs

Notes:

• This server communicates over stdio. Do not print to stdout; only stderr is safe for logs.
• The server already routes logs to stderr; if you add logs, follow the same pattern.
• You can still register via npx -y rovodev-cli-mcp, but during development using node dist/index.js avoids npm network hiccups.

Troubleshooting

• "Failed to connect" in claude mcp list

  • Ensure your Node is >= 18 (node -v).
  • Ensure no output is written to stdout (stdout is reserved for the MCP protocol). This repo's logger writes to stderr only.
  • Try registering the local path: claude mcp add -s user rovodev -- node "$(pwd)/dist/index.js".
  • If using WSL, register from the Linux side; Claude Code on Windows can discover WSL user-scoped config.

• Authentication errors (API key issues)

  • If you see "Authentication Error" messages, your rovodev CLI API key may be expired or invalid
  • Check your rovodev CLI configuration and update your API key
  • The server now detects authentication issues and provides clear error messages instead of hanging

• Underlying CLI not found

  • The default command is acli. Install it or override:

  claude mcp add -s user rovodev -- \
    node "$(pwd)/dist/index.js" \
    -e ROVODEV_CLI_PATH=/path/to/your/cli
  

• Large responses

  • Use ask-rovodev first. If the response is chunked, call next-chunk repeatedly with the provided cacheKey. You can also fetch a specific page with fetch-chunk.
  • Tune chunk size with env vars (in order of precedence): MCP_CHUNK_SIZE, then legacy ROVODEV_CHUNK_SIZE.

Tools and streaming

This server supports streaming chunk-caching to reduce memory usage for large outputs. The ask-rovodev tool streams the CLI output directly into a chunk cache. If the output exceeds the page chunk size, it returns the first chunk and a cacheKey so you can fetch subsequent chunks with next-chunk or fetch-chunk.

Tools

Enhanced Core Tools

• ask-rovodev: { message?: string, prompt?: string, configFile?: string, shadow?: boolean, verbose?: boolean, restore?: boolean, yolo?: boolean, sessionId?: string, retries?: number, backoffMs?: number, args?: string[], pagechunksize?: number }
  • New: Session isolation with sessionId, retry logic with retries/backoffMs
  • Default: yolo mode is enabled for non-interactive MCP usage; set yolo: false to disable if you need interactive behavior.
  • Tip: If your message starts with dashes (e.g., --example), the underlying CLI may interpret it as a flag. The server inserts -- before such messages to prevent flag parsing.
• tap-rovodev: alias of ask-rovodev

Session Management

• session_manager: { action: "create" | "destroy" | "list" | "get" | "cleanup", sessionId?: string, timeoutMs?: number }
  • Manage isolated sessions for maintaining context across multiple commands

Health & Diagnostics

• health_check: { detailed?: boolean }
  • Check server health including CLI availability, session manager status, and environment configuration
• diagnostics: { includePerformance?: boolean, includeHealth?: boolean, includeSessions?: boolean, includeSystem?: boolean, includeRecentExecutions?: boolean, recentLimit?: number }
  • Get comprehensive system diagnostics including performance metrics and resource usage

Utility Tools

• next-chunk: { cacheKey: string } Fetch the next chunk sequentially from a cached large response
• fetch-chunk: { cacheKey: string, chunkIndex: number } (optional) Fetch a specific chunk by index
• Help: show help from underlying CLI
• Ping: connectivity test

Server behavior and tuning via env vars:

• Logging level: MCP_LOG_LEVEL (debug | info | warn | error | silent)
• Exec timeout: MCP_EXEC_TIMEOUT_MS (kill underlying CLI after N ms; includes partial stdout tail in error)
• Max stdout buffer: MCP_MAX_STDOUT_SIZE (maximum output buffer size before termination)
• Working directory: MCP_CWD (set process cwd for the underlying CLI)
• Chunk cache TTL: MCP_CHUNK_TTL_MS (default 20 minutes)
• Chunk cache max entries: MCP_CHUNK_MAX_ENTRIES (default 500)

Handling large responses (simple sequential flow)

• If the output is too large, the first ask-rovodev call returns page 1 plus a cacheKey:
  • Response header example: cacheKey: <key>, chunk: 1/N
• To continue, call next-chunk with the same cacheKey to get chunk 2, then 3, etc. until it reports no further chunks.