ruvscan

RuvScan is an MCP server that integrates with Claude Code CLI, Codex CLI, and Claude Desktop to turn GitHub exploration into a guided, intent-aware discovery experience. It acts as a back-end service that leverages the GitHub API (via a provided token) to surface relevant tools, libraries, and patterns across repositories, with an emphasis on sublinear or creative transfer solutions. Once the backend Docker container is running and the MCP is registered in your CLI, you can invoke the MCP through Claude or Codex commands to get contextual recommendations, shortlists of candidate repos, and usage guidance for integrating found tools into your project. The server ships with a ready-made ruvscan-mcp entry point and is designed to work alongside ruvnet resources and other edge-case repos.

To use it effectively, ensure the backend is running (docker compose up -d in the ruvscan repository) and that you have a valid GitHub token exposed as GITHUB_TOKEN wherever you operate the MCP client. In Claude Desktop, you configure the MCP with the uvx entrypoint and the ruvscan-mcp package, providing the token and any other environment variables you need. In Codex, install the MCP package globally (pipx install -e .) and configure the client with the token and API URL if needed. When you pose a request, RuvScan will fetch relevant GitHub results, interpret them in a developer-centric way, and present actionable suggestions or direct integration hints.

Prerequisites:\n- Docker and Docker Compose installed on your system.\n- Python 3.10+ if you plan to run the MCP client or develop locally.\n- Git installed to clone the repository.\n- A GitHub token with repo (read) and read:org scopes for broad access if needed.\n\nOption A — Run the MCP server via Docker (recommended for quick start):\n1. Clone the repository and navigate to it:\nbash\ngit clone https://github.com/ruvnet/ruvscan.git && cd ruvscan\n\n2. Start the backend in the background:\nbash\ndocker compose up -d\n\n3. Ensure the MCP entrypoint is available (ruvscan-mcp should be installed in the container).\n\nOption B — Install and run the MCP server locally with uvx (Python-based, recommended for CLI integration):\n1. Ensure Python 3.10+ is installed.\n2. Install the MCP package in editable mode (from the repository location):\nbash\n# from the repository root (ruvscan)\npipx install -e .\n\n3. Run the MCP server using uvx (as configured in the README):\nbash\nuvx ruvscan-mcp\n\n4. If needed, expose a GITHUB_TOKEN in your environment:\nbash\nexport GITHUB_TOKEN=ghp_your_github_token_here\n\n\nOption C — Quick start with Codex CLI (integrates via pipx and config):\n1. Start the Docker backend as in Option A.\n2. Install the MCP package globally with pipx:\nbash\npipx install -e .\n\n3. Configure Codex with the MCP server settings (token and URL as needed).\ntoml\n[mcp_servers.ruvscan]\ncommand = "ruvscan-mcp"\n[mcp_servers.ruvscan.env]\nGITHUB_TOKEN = "ghp_your_github_token_here"\nrUVSCAN_API_URL = "http://localhost:8000"\n\n4. Run Codex and test the MCP via: codex mcp list or interact with the MCP in a conversation.\n\nPrerequisites note:\n- A valid GitHub token is required for calls to the GitHub API. Without it, you will hit rate limits and functionality may be limited.

Tips and caveats:\n- The MCP depends on a working backend Docker container. Start the docker-compose setup first before registering the MCP in any client.\n- Always supply GITHUB_TOKEN in environments where the MCP client runs to avoid anonymous rate limits. Consider using a token with scoped access (repo, read:org).\n- If you change configuration (e.g., API URL or env vars), restart the MCP client to ensure changes take effect.\n- For Claude Desktop, the config example shows using uvx with env GITHUB_TOKEN; ensure the token is kept secret and not committed to config files.\n- When upgrading ruvscan or its MCP, re-register or reconfigure in your MCP clients if the API surface changes.\n- The server is designed to surface cross-domain or cross-repo tooling ideas; validate any suggested tools for license compatibility and maintenance status before integrating into production.\n- If you encounter rate limits, consider staggering requests or caching results locally where appropriate.