iflow-mcp_hulupeep_ruvscan-mcp 0.5.0__py3-none-any.whl

iflow_mcp_hulupeep_ruvscan_mcp-0.5.0.dist-info/METADATA

@@ -0,0 +1,1222 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_hulupeep_ruvscan-mcp
+Version: 0.5.0
+Summary: RuvScan MCP Server - Sublinear intelligence for GitHub discovery
+Project-URL: Homepage, https://github.com/ruvnet/ruvscan
+Project-URL: Documentation, https://github.com/ruvnet/ruvscan#readme
+Project-URL: Repository, https://github.com/ruvnet/ruvscan
+Project-URL: Issues, https://github.com/ruvnet/ruvscan/issues
+Author-email: Ruvnet <support@ruvnet.ai>
+License: MIT OR Apache-2.0
+Keywords: ai,claude,github,mcp,semantic-search,sublinear
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🧠 RuvScan - MCP Server for Intelligent GitHub Discovery
+
+[![License](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)
+[![MCP Server](https://img.shields.io/badge/MCP-Server-green.svg)](https://modelcontextprotocol.io)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/badge/PyPI-ruvscan--mcp-blue.svg)](https://pypi.org/project/ruvscan-mcp/)
+[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](docker-compose.yml)
+
+> **Give Claude the power to discover GitHub tools with sublinear intelligence.**
+
+RuvScan is a **Model Context Protocol (MCP) server** that connects to Claude Code CLI, Codex, and Claude Desktop. It turns GitHub into your AI's personal innovation scout — finding tools, frameworks, and solutions you'd never think to search for.
+
+**Oh, it's a work in progress - so suggest changes to make it better.*
+
+
+
+It comes packaged with RUVNET repo but you can add ANY other repo like Andrej Kaparthy's or other folks on the edge of what you are working on. 
+
+ 
+
+---
+
+## 🎯 What Is This?
+
+**A GitHub search that actually understands what you're trying to build.**
+
+### The Problem
+
+You're building something new (an app or feature). You know there's probably a library, framework, or algorithm out there that could 10× your project. But:
+
+- 🔍 **Search is broken** - You'd have to know the exact keywords
+- 📚 **Too many options** - Millions of repos, most irrelevant
+- 🎯 **Wrong domain** - The best solution might be in a totally different field
+- ⏰ **Takes forever** - Hours of browsing docs and READMEs
+
+### The Solution
+
+**RuvScan thinks like a creative developer**, not a search engine:
+
+```
+You: "I'm building an AI app. Context recall is too slow."
+
+RuvScan: "Here's a sublinear-time solver that could replace your
+          vector database queries. It's from scientific computing,
+          but the O(log n) algorithm applies perfectly to semantic
+          search. Here's how to integrate it..."
+```
+
+**It finds:**
+- ✨ **Outside-the-box solutions** - Tools from other domains that apply to yours
+
+- ⚡ **Performance wins** - Algorithms you didn't know existed
+
+- 🔧 **Easy integration** - Tells you exactly how to use what it finds
+
+- 🧠 **Creative transfers** - "This solved X, but you can use it for Y"
+
+  
+
+How you phrase your request helps the tool give you straightforward help or at the edge kind of solutions. Here are a few more examples of how you might phrase to show different solutions. (more examples further on)
+
+### Example requests
+
+The actual response will be in understandable plain English while suggesting state of the art. 
+
+
+
+  1. *“I just want a drop-in script that downloads my inbox and saves each email as JSON—what should I try?*” → byroot/mail or DusanKasan/parsemail for dead-simple IMAP/MIME to
+     structured JSON.
+  2. *“Give me a starter repo that already watches Gmail and writes summaries to a Notion page.”* → openai/gpt-email-summarizer-style templates or lucasmic/imap-to-webhook for plug-and-
+     play workflows.
+  3. *“Show me open-source email parsers I can drop into a Python summarizer—IMAP fetch, MIME decoding, nothing fancy.”* → DusanKasan/parsemail or inboxkitten/mail-parser for turnkey
+     IMAP/MIME handling.
+  4. “*I’m summarizing email on cheap Chromebooks. Which repos include tiny embeddings or approximate search so I can stay under 1 GB RAM?”* → ruvnet/sublinear-time-solver or facebook/faiss-lite to slot in sublinear similarity on low-RAM hardware.
+  5. “*Need policy/compliance topic detectors with clear audit trails. Point me to rule-based or interpretable NLP projects built for email streams.”* → ruvnet/FACT plus
+     CaselawAccessProject/legal-topic-models for deterministic caching plus transparent classifiers.
+  6. **“My pipeline can only see messages once. Find streaming or incremental NLP algorithms (reservoir sampling, online transformers, CRDT logs) that pair well with an email*
+     summarizer.”* → ruvnet/MidStream or openmessaging/stream-query for single-pass, reservoir-style processing.
+  7. “*Newsletters are 90 % of my inbox. Recommend DOM-first or layout-aware extraction toolkits I can chain before summarization so tables and sections survive.”* → postlight/mercury-
+     parser or mozilla/readability to strip and structure HTML before summarizing.
+  8. *“Legal demands reproducible summaries. Surface repos that memoize LLM calls (FACT-style hashing, deterministic agents) so the same thread always yields the same text.”* → ruvnet/
+     FACT or explosion/spaCy-ray patterns that hash embeddings/results for audit trails.
+  9. **“I’m willing to repurpose exotic tooling—sublinear solvers, sparse matrix DOM walkers, flow-based streaming engines—if you can explain how they’d accelerate large-scale email*
+     summarization. What should I investigate?”* → ruvnet/sublinear-time-solver (DOM walker mode), apache/arrow (columnar email batches), and ruvnet/flow-nexus (cost-propagation for batched summarization) as creative transfers.
+
+---
+
+## ⚡ Install in 30ish Seconds
+
+RuvScan works with **Claude Code CLI**, **Codex CLI**, and **Claude Desktop**. Pick your platform:
+
+
+
+Note: TWO Things need to happen to have this working. 
+
+1. The BACKEND (docker ) must be running in a separate terminal window and 
+2. The MCP needs to be added to your CLI or claude 
+3. 2 After installing do /MCP and check if it is installed correctly (you will see an x or worse, no tools showing). If either are true, just ask claude - hey fix my ruvscan mcp server. 
+
+### For Claude Code CLI
+
+```bash
+# 1. Start RuvScan backend
+git clone https://github.com/ruvnet/ruvscan.git && cd ruvscan
+docker compose up -d
+
+# 2. Add MCP server to Claude
+claude mcp add ruvscan --scope user --env GITHUB_TOKEN=ghp_your_token -- uvx ruvscan-mcp
+
+# 3. Start using it!
+claude
+```
+
+### For Codex CLI (Quick Install)
+
+```bash
+# 1. Start RuvScan backend
+git clone https://github.com/ruvnet/ruvscan.git && cd ruvscan
+docker compose up -d
+
+# 2. Install globally with pipx
+pipx install -e .
+
+# 3. Configure in ~/.codex/config.toml
+# See "For Codex CLI" section below for configuration details
+
+# 4. Start using it!
+codex
+```
+
+> ℹ️ **GitHub personal access token required.** RuvScan calls the GitHub API heavily; without a token you will immediately hit anonymous rate limits and scans will fail. Create a fine-grained or classic token with `repo` (read) and `read:org` scope, then expose it as `GITHUB_TOKEN` everywhere you run the MCP client and backend.
+
+### For Claude Desktop
+
+**1. Start the backend:**
+```bash
+git clone https://github.com/ruvnet/ruvscan.git && cd ruvscan
+docker compose up -d
+```
+
+**2. Add to config** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+```json
+{
+  "mcpServers": {
+    "ruvscan": {
+      "command": "uvx",
+      "args": ["ruvscan-mcp"],
+      "env": {
+        "GITHUB_TOKEN": "ghp_your_github_token_here"
+      }
+    }
+  }
+}
+```
+
+**3. Restart Claude Desktop** (Cmd+Q and reopen)
+
+### For Codex CLI
+
+Codex CLI speaks the same MCP protocol. After starting the Docker backend:
+
+**Step 1: Install RuvScan globally with pipx**
+
+```bash
+cd ruvscan
+pipx install -e .
+```
+
+**Step 2: Configure Codex**
+
+Edit `~/.codex/config.toml` and add:
+
+```toml
+[mcp_servers.ruvscan]
+command = "ruvscan-mcp"
+
+[mcp_servers.ruvscan.env]
+GITHUB_TOKEN = "ghp_your_github_token_here"
+RUVSCAN_API_URL = "http://localhost:8000"
+```
+
+**Step 3: Test it works**
+
+```bash
+# From any directory
+cd /tmp
+codex mcp list | grep ruvscan
+# Should show: ruvscan  ruvscan-mcp  -  GITHUB_TOKEN=*****, RUVSCAN_API_URL=*****  -  enabled
+
+# Start a conversation
+codex
+> Can you scan the anthropics GitHub organization?
+```
+
+> ✅ **Global Installation**: RuvScan is now available in ALL projects and directories!
+
+---
+
+#### Alternative: Using codex mcp add (if available)
+
+If your Codex build includes the `mcp add` command:
+
+```bash
+codex mcp add --env GITHUB_TOKEN=ghp_your_token --env RUVSCAN_API_URL=http://localhost:8000 -- ruvscan-mcp ruvscan
+```
+
+> 🧪 When experimenting with `mcp dev`, run `mcp dev --transport sse src/ruvscan_mcp/mcp_stdio_server.py`.
+> The server now performs a health check and shuts down with a clear explanation if no client completes the handshake within five minutes (for example, when the transport is mismatched).
+
+---
+
+#### Troubleshooting Codex CLI
+
+**Check MCP server status:**
+```bash
+codex mcp list
+```
+
+**Verify command exists:**
+```bash
+which ruvscan-mcp
+# Should output: /home/your-user/.local/bin/ruvscan-mcp
+```
+
+**Test command directly:**
+```bash
+ruvscan-mcp --help
+```
+
+**View Codex logs:**
+```bash
+tail -f ~/.codex/log/codex-tui.log
+```
+
+📚 **Detailed Codex Setup Guide:** [docs/CODEX_CLI_SETUP.md](docs/CODEX_CLI_SETUP.md)
+
+### GitHub Token Checklist
+
+- Create a personal access token (classic or fine-grained) with read access to the repos you care about plus `read:org`. GitHub’s walkthrough lives here: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic
+- Export it in your shell (`export GITHUB_TOKEN=ghp_...`) before running `docker compose`, `uvicorn`, or `codex/claude mcp add` so the backend can authenticate API calls.
+- For Docker-based runs, copy `.env.example` to `.env` and drop the token there so the containers inherit it.
+- Optionally add the same value to `.env.local`; `scripts/seed_database.py` will pick it up automatically when seeding.
+- **Cost:** GitHub does not charge for issuing or using a PAT. Your scans only consume API rate quota on the account that created the token; standard rate limits refresh hourly. If you're on an enterprise plan, the usage just rolls into the org's normal API allowances.
+- Treat the token like a password. Store it in your secret manager and revoke it from https://github.com/settings/tokens if it ever leaks.
+
+### What `docker compose up` Runs
+
+- `mcp-server` (Python/FastAPI) — hosts the MCP HTTP API on port 8000, reads `GITHUB_TOKEN`, writes data to `./data/ruvscan.db`, and exposes `/scan`, `/query`, `/compare`, and `/analyze` endpoints.
+- `scanner` (Go) — background workers (port 8081 on the host ↔ 8080 in-container) that call the GitHub REST API, fetch README/topic metadata, and POST results back to the MCP server at `/ingest`.
+- `rust-engine` (Rust) — optional gRPC service for Johnson–Lindenstrauss O(log n) similarity; disabled by default and only launched when you run `docker compose --profile rust-debug up`.
+- Shared volumes — `./data` and `./logs` are bind-mounted so your SQLite DB and logs persist across container restarts.
+
+**📖 Full Installation Guide:** [docs/MCP_INSTALL.md](docs/MCP_INSTALL.md)
+
+---
+
+## 🌱 Sample Data & Optional Seeding
+
+Out of the box, RuvScan already includes a `data/ruvscan.db` file packed with ~100 public repositories from the **ruvnet** organization. That means a fresh clone can answer questions like “What do we have for real-time streaming?” as soon as the MCP server starts—no extra steps required.
+
+### When would I run the seed script?
+
+- **Refresh the included catalog** (pick up new ruvnet repos or README changes).
+- **Add another user/org** so your local MCP knows about your own code.
+- **Rebuild the database** after deleting `data/ruvscan.db`.
+
+```bash
+# Refresh the bundled ruvnet dataset
+python3 scripts/seed_database.py --org ruvnet
+
+# Add a different org or user (ex. OpenAI)
+python3 scripts/seed_database.py --org openai --limit 30
+
+# Skip README downloads for a quick metadata-only pass
+python3 scripts/seed_database.py --no-readmes
+```
+
+Prefer clicks over scripts? Tell your MCP client:
+- **Claude / Codex prompt:** “Use scan_github on org anthropics with a limit of 25.”
+- **CLI:** `./scripts/ruvscan scan org anthropics --limit 25`
+
+Either route stores the new repos alongside the preloaded ruvnet entries so every future query can reference them.
+
+**Check what's inside:**
+```bash
+sqlite3 data/ruvscan.db "SELECT COUNT(*), MIN(org), MAX(org) FROM repos;"
+```
+
+### What does RuvScan store locally?
+
+- Everything lives in the `data/ruvscan.db` SQLite file. Each row captures the repo’s owner, name, description, topics, README text, star count, primary language, and the `last_scan` timestamp so we know when it was fetched.
+- The MCP tools only read from this file; the only way new repos show up is when you seed or run a `scan_github` command (either via CLI or Claude).
+- No background internet crawling happens after a scan completes—what you see is exactly what’s stored in SQLite.
+
+### How do I see which repos are cached?
+
+```bash
+# Show every org/user currently in the catalog
+sqlite3 data/ruvscan.db "
+  SELECT org, COUNT(*) AS repos
+  FROM repos
+  GROUP BY org
+  ORDER BY repos DESC;"
+
+# Peek at the latest entries to confirm what's fresh
+sqlite3 data/ruvscan.db "
+  SELECT full_name, stars, datetime(last_scan) AS last_seen
+  FROM repos
+  ORDER BY last_scan DESC
+  LIMIT 10;"
+```
+
+Prefer a friendlier view? Run `./scripts/ruvscan cards --limit 20` to list the top cached repos with summaries.
+
+### How do I wipe the catalog and start over?
+
+1. Stop whatever is talking to RuvScan (`docker compose down` or Ctrl‑C the dev server).
+2. (Optional) Back up the old database: `cp data/ruvscan.db data/ruvscan.db.bak`.
+3. Remove the file: `rm -f data/ruvscan.db`.
+4. Seed again with whatever scope you want:
+
+```bash
+python3 scripts/seed_database.py --org ruvnet --limit 100
+# or
+./scripts/ruvscan scan org my-company --limit 50
+```
+
+Re‑start the MCP server and it will only know about the repos you just seeded or scanned.
+
+⚠️ **Reminder:** the database keeps `last_scan` timestamps. Updating the same org simply refreshes the rows instead of duplicating them. If you rely on the bundled sample data, consider re-running the refresh monthly so the catalog stays current.
+
+📚 **Full Guide:** [Database Seeding Documentation](docs/DATABASE_SEEDING.md)
+
+---
+
+## 🤔 How RuvScan Suggests Some Tools (and Skips Others)
+
+RuvScan scores every cached repository against your intent using three simple signals:
+
+1. **Token overlap** – does the repo description/README mention the same concepts you typed?
+2. **Efficiency boost** – extra credit for words like “optimize,” “streaming,” “sublinear,” etc.
+3. **Reality check** – star count and recent scans nudge mature, maintained projects upward.
+
+The goal is to surface repos that obviously help without making you stretch too far.
+
+### Real example: “Scan email for policy updates”
+
+- **Your ask:** “Build a tool that scans incoming email for important policy updates and compliance requirements.”
+- **What surfaced:** `freeCodeCamp/mail-for-good`, `DusanKasan/parsemail`, `ruvnet/FACT`, etc. Those repos talk about *email parsing*, *campaign pipelines*, and *deterministic summaries*—keywords that overlap the request almost perfectly.
+- **What you might have expected:** `ruvnet/sublinear-time-solver` (which includes a DOM extractor that could chew through large HTML archives).
+- **Why it was skipped:** the solver’s README highlights *Johnson–Lindenstrauss projection*, *sparse matrix solvers*, and *Flow-Nexus streaming*. None of those tokens match “email,” “policy,” or “compliance,” so its overlap score stayed below the default `min_score=0.6`. RuvScan saw it as “clever infrastructure, but unrelated to your words,” so it deferred to mail-focused repos.
+
+### How to explore outside-the-box options
+
+- **Nudge the intent:** mention the bridge explicitly (“…or should I repurpose sublinear-time-solver’s DOM tool for compliance emails?”). Now the tokenizer sees “sublinear” and “DOM,” boosting that repo.
+- **Lower the threshold:** call `query_leverage` with `min_score=0.4` and `max_results=10` to let more fringe ideas through.
+- **Widen the context:** add an engineering note or PRD link so the SAFLA reasoning layer understands why a matrix solver might help an email scanner.
+
+By default, RuvScan errs on the side of *obvious fit*. If you want it to wander into “this sounds weird but might work” territory, just give it permission with a hint or a looser score cutoff.
+
+---
+
+## 💬 Using RuvScan in Claude
+
+Once installed, just talk to Claude naturally:
+
+### Example 1: Scan GitHub Organizations
+
+**You:** "Scan the Anthropics GitHub organization"
+
+**Claude:** *Uses `scan_github` tool*
+```
+Scan initiated for org: anthropics
+Status: initiated
+Estimated repositories: 50
+Message: Scan initiated - workers processing in background
+```
+
+### Example 2: Make Reasoning Reproducible
+
+**You:** "I need to debug why my agent made a decision yesterday. Any deterministic tooling?"
+
+**Claude:** *Uses `query_leverage` and surfaces FACT*
+
+```
+Repository: ruvnet/FACT
+Relevance Score: 0.89
+Complexity: O(1)
+
+Summary: Deterministic caching framework that replays every LLM call with SHA256 hashes.
+
+Why This Helps: Guarantees identical outputs for the same prompts, letting you trace agent decisions step by step.
+
+How to Use: pip install fact-cache && from fact import FACTCache
+
+Capabilities: Deterministic replay, prompt hashing, audit trails
+```
+
+### Example 3: Compare Frameworks
+
+**You:** "Compare facebook/react and vuejs/core for me"
+
+**Claude:** *Uses `compare_repositories` tool*
+```
+Repository Comparison (O(log n) complexity)
+
+facebook/react vs vuejs/core
+
+Similarity Score: 0.78
+Complexity: O(log n)
+
+Analysis: Both are component-based UI frameworks with virtual DOM, but React
+has larger ecosystem and more enterprise adoption. Vue has simpler learning
+curve and better built-in state management.
+```
+
+### Example 4: Understand the Reasoning
+
+**You:** "Show me the reasoning chain for why you recommended that solver"
+
+**Claude:** *Uses `analyze_reasoning` tool*
+```
+Reasoning Chain for ruvnet/sublinear-time-solver:
+
+- Detected performance optimization intent
+- Matched O(log n) complexity with vector search problem
+- Found Johnson-Lindenstrauss dimension reduction capability
+- Cross-domain transfer from scientific computing to AI/ML
+- Verified WASM support for browser integration
+
+(Retrieved from FACT deterministic cache)
+```
+
+### Example 5: Mine Existing Ruvnet Stacks
+
+**You:** "I already have the ruvnet repos seeded. What should I reuse for real-time streaming?"
+
+**Claude:** *Calls `query_leverage` and surfaces existing entries*
+```
+Repository: ruvnet/MidStream
+Relevance Score: 0.91
+
+Summary: WASM-accelerated multiplexing layer for realtime inference
+
+Why This Helps: Drop it in front of your LangChain stack to swap synchronous
+requests for bidirectional streams. Built to pair with sublinear-time-solver.
+
+How to Use: docker pull ghcr.io/ruvnet/midstream:latest
+```
+
+---
+
+## 🚀 What Can You Build With This?
+
+RuvScan powers **3 types of killer tools**:
+
+### 1. 🏗️ Builder Co-Pilot (IDE Integration)
+
+**Imagine**: Your code editor that suggests relevant libraries as you type.
+
+```javascript
+// You're writing:
+async function improveContextRetrieval(query) {
+  // ...
+}
+
+// RuvScan suggests:
+💡 Found: sublinear-time-solver
+   "Replace linear search with O(log n) similarity"
+   Relevance: 0.94 | Integration: 2 minutes
+```
+
+**Use Cases**:
+- VS Code extension
+- Cursor integration
+- GitHub Copilot alternative
+- JetBrains plugin
+
+### 2. 🤖 AI Agent Intelligence Layer
+
+**Imagine**: Your AI agents that automatically discover and integrate new tools.
+
+```python
+# Your AI agent:
+agent.goal("Optimize database queries")
+
+# RuvScan finds and explains:
+{
+  "tool": "cached-sublinear-solver",
+  "why": "Replace O(n²) joins with O(log n) approximations",
+  "how": "pip install sublinear-solver && ..."
+}
+```
+
+**Use Cases**:
+- Autonomous coding agents
+- DevOps automation
+- System optimization bots
+- Research assistants
+
+### 3. 📊 Discovery Engine (Product/Research)
+
+**Imagine**: A tool that finds innovation opportunities across your entire tech stack.
+
+```bash
+$ ruvscan scan --org mycompany
+$ ruvscan query "What could 10× our ML pipeline?"
+
+Found 8 leverage opportunities:
+1. Replace sklearn with sublinear solver (600× faster)
+2. Use MidStream for real-time inference (80% cost savings)
+3. ...
+```
+
+**Use Cases**:
+- Tech stack audits
+- Performance optimization hunts
+- Architecture reviews
+- Competitive research
+
+---
+
+## 🛠️ What Tools Does Claude Get?
+
+When you install RuvScan as an MCP server, Claude gains 4 powerful tools:
+
+| Tool | What It Does | Example Use |
+|------|--------------|-------------|
+| **`scan_github`** | Scan any GitHub org, user, or topic | "Scan the openai organization" |
+| **`query_leverage`** | Find relevant tools with O(log n) semantic search | "Find tools for real-time collaboration" |
+| **`compare_repositories`** | Compare repos with sublinear similarity | "Compare NextJS vs Remix" |
+| **`analyze_reasoning`** | View FACT cache reasoning chains | "Why did you recommend that library?" |
+
+---
+
+**What's new:**
+
+- RuvScan now fetches up to 200 repositories per scan, starting with a fast README sweep before deeper analysis.
+- The first time the MCP server starts it automatically preloads the entire `ruvnet` organization, so you can ask questions immediately.
+- Query responses include a concise summary and a structured Markdown briefing that highlights the opportunity, expected benefit, and integration path for each recommendation.
+- Every answer reminds you to share a Product Requirements Document (PRD) or similar artifact so the follow-up analysis can be even more specific.
+- The server now performs a health check and shuts down with a clear explanation if no client completes the handshake within five minutes (for example, when the transport is mismatched). This prevents the server from hanging silently when run with the wrong transport (for example, `mcp dev` without `--transport sse`) or when the backend API is unreachable.
+
+## 🎬 Demo: Complete Workflow
+
+### In Claude Code CLI
+
+```bash
+$ claude
+
+You: I'm working on a Python project that processes large datasets.
+     The performance is terrible. What GitHub tools could help?
+
+Claude: Let me search for high-performance data processing tools...
+        [Uses query_leverage tool]
+
+        I found several relevant projects:
+
+        1. ruvnet/sublinear-time-solver (Relevance: 0.94)
+           - TRUE O(log n) algorithms for matrix operations
+           - Could replace your O(n²) operations with O(log n)
+           - Install: pip install sublinear-solver
+
+        2. apache/arrow (Relevance: 0.88)
+           - Columnar data format for fast analytics
+           - 100× faster than pandas for large datasets
+
+        Would you like me to scan the Apache organization to find more tools?
+
+You: Yes, scan the apache organization
+
+Claude: [Uses scan_github tool]
+        Scanning Apache Foundation repositories...
+        Found 150+ repositories. Indexing them now.
+```
+
+### In Claude Desktop
+
+<img src="https://via.placeholder.com/800x400/1e1e1e/00ff00?text=Claude+Desktop+Screenshot" alt="Claude Desktop with RuvScan" />
+
+1. Open Claude Desktop
+2. See the tools icon (🔧) showing RuvScan is connected
+3. Ask questions naturally - Claude uses RuvScan automatically
+4. Get intelligent suggestions with reasoning chains
+
+---
+
+## ⚡ Alternative: Run as Standalone API (2 Minutes)
+
+### Option 1: Docker (For Direct API Use)
+
+```bash
+# 1. Clone and setup
+git clone https://github.com/ruvnet/ruvscan.git
+cd ruvscan
+cp .env.example .env
+
+# 2. Add your GitHub token to .env
+# GITHUB_TOKEN=ghp_your_token_here
+
+# 3. Start everything
+docker compose up -d
+
+# 4. Try it!
+./scripts/ruvscan query "Find tools for real-time AI performance"
+```
+
+### Option 2: Direct HTTP API
+
+```bash
+# Query for leverage
+curl -X POST http://localhost:8000/query \
+  -H "Content-Type: application/json" \
+  -d '{
+    "intent": "How can I speed up my vector database?",
+    "max_results": 5
+  }'
+```
+
+### Option 3: Python Integration
+
+```python
+import httpx
+
+async def find_leverage(what_you_are_building):
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            "http://localhost:8000/query",
+            json={"intent": what_you_are_building}
+        )
+        return response.json()
+
+# Use it
+ideas = await find_leverage(
+    "Building a real-time collaboration editor"
+)
+
+for idea in ideas:
+    print(f"💡 {idea['repo']}")
+    print(f"   {idea['outside_box_reasoning']}")
+    print(f"   Integration: {idea['integration_hint']}")
+```
+
+---
+
+## 🎨 Real-World Examples
+
+### Example 1: Performance Optimization
+
+**You ask:**
+```
+"Pandas melts when I process multi-GB analytics data. I need something columnar."
+```
+
+**RuvScan finds:**
+```json
+{
+  "repo": "apache/arrow",
+  "outside_box_reasoning": "Arrow gives you a columnar in-memory format with
+    vectorized kernels. Swap it in to keep data compressed on the wire and
+    eliminate Python GIL bottlenecks.",
+  "integration_hint": "pip install pyarrow && use datasets.to_table()"
+}
+```
+
+### Example 2: Architecture Discovery
+
+**You ask:**
+```
+"Need a way to replay AI reasoning for debugging."
+```
+
+**RuvScan finds:**
+```json
+{
+  "repo": "ruvnet/FACT",
+  "outside_box_reasoning": "FACT caches every LLM interaction
+    with deterministic hashing. Replay any conversation
+    exactly as it happened. Built for reproducible AI.",
+  "integration_hint": "from fact import FACTCache;
+    cache = FACTCache()"
+}
+```
+
+### Example 3: Domain Transfer
+
+**You ask:**
+```
+"Building a recommendation system. Need fast similarity."
+```
+
+**RuvScan finds:**
+```json
+{
+  "repo": "scientific-computing/spectral-graph",
+  "outside_box_reasoning": "This is from bioinformatics,
+    but the spectral clustering algorithm works perfectly
+    for collaborative filtering. O(n log n) vs O(n²).",
+  "integration_hint": "Adapt the adjacency matrix code
+    to your user-item matrix"
+}
+```
+
+---
+
+## 🔥 Why RuvScan Is Different
+
+### Traditional Search
+```
+You → "vector database speed" → GitHub
+Results: 10,000 vector DB libraries
+Problem: You already KNEW about vector databases
+```
+
+### RuvScan
+```
+You → "My vector DB is slow" → RuvScan
+Results: Sublinear algorithms, compression techniques,
+         caching strategies from OTHER domains
+Problem: SOLVED with ideas you'd never have found
+```
+
+**The secret**: RuvScan uses:
+- 🧠 **Semantic understanding** (not keyword matching)
+- 🔀 **Cross-domain reasoning** (finds solutions from other fields)
+- ⚡ **Sublinear algorithms** (TRUE O(log n) similarity search)
+- 🎯 **Deterministic AI** (same question = same answer, always)
+
+---
+
+## 🎓 For Engineers: How It Works
+
+Now let's get technical...
+
+### Architecture: Tri-Language Hybrid System
+
+RuvScan is built as a **hybrid intelligence system** combining:
+
+```
+🐍 Python  → MCP Orchestrator (FastAPI)
+            → FACT Cache (deterministic reasoning)
+            → SAFLA Agent (analogical inference)
+
+🦀 Rust    → Sublinear Engine (gRPC)
+            → Johnson-Lindenstrauss projection
+            → TRUE O(log n) semantic comparison
+
+🐹 Go      → Concurrent Scanner (GitHub API)
+            → Rate-limited fetching
+            → Parallel processing
+```
+
+### The Intelligence Stack
+
+#### 1. Sublinear Similarity (Rust)
+
+**Problem**: Comparing your query to 10,000 repos is O(n) — too slow.
+
+**Solution**: Johnson-Lindenstrauss dimension reduction.
+
+```rust
+// Reduce 1536-dimensional vectors to O(log n)
+let jl = JLProjection::new(1536, 0.5);
+let reduced = jl.project(&embedding);
+
+// Now compare in compressed space
+let similarity = sublinear_similarity(&query, &corpus);
+// Complexity: O(log n) vs O(n)
+```
+
+**Mathematical guarantee**: Distances preserved within (1 ± ε).
+
+#### 2. FACT Cache (Python)
+
+**Problem**: LLM reasoning is non-deterministic — can't reproduce results.
+
+**Solution**: Deterministic prompt caching with SHA256 hashing.
+
+```python
+# Same input always produces same output
+cache_hash = hashlib.sha256(prompt.encode()).hexdigest()
+cached_result = fact_cache.get(cache_hash)
+
+if cached_result:
+    return cached_result  # 100% reproducible
+```
+
+**Benefit**: Every insight is reproducible, auditable, versioned.
+
+#### 3. SAFLA Reasoning (Python)
+
+**Problem**: Literal similarity misses creative reuse opportunities.
+
+**Solution**: Analogical reasoning across domains.
+
+```python
+# Detect domain overlap
+intent_concepts = ["performance", "search", "real-time"]
+repo_capabilities = ["O(log n)", "sublinear", "algorithms"]
+
+# Generate creative transfer
+insight = safla.generate_outside_box_reasoning(
+    query="speed up vector search",
+    repo="scientific-computing/sparse-solver"
+)
+# → "Use sparse matrix techniques for approximate NN"
+```
+
+**Benefit**: Finds solutions from completely different fields.
+
+#### 4. Concurrent Scanning (Go)
+
+**Problem**: GitHub has 100M+ repos — can't scan them all.
+
+**Solution**: Parallel workers with smart rate limiting.
+
+```go
+// 10 concurrent workers
+for _, repo := range repos {
+    go scanner.processRepo(repo)
+}
+
+// Auto rate-limit
+scanner.checkRateLimit()
+// Sleeps if < 100 requests remaining
+```
+
+**Benefit**: Scan 100s of repos/minute without hitting limits.
+
+---
+
+## 🏗️ Technical Architecture
+
+### Data Flow
+
+```
+┌─────────────┐
+│    User     │
+│   Query     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────────────────────┐
+│  Python MCP Server (FastAPI)    │
+│  ┌────────────┬────────────────┐│
+│  │ Generate   │ Check FACT     ││
+│  │ Embedding  │ Cache          ││
+│  └─────┬──────┴────────┬───────┘│
+└────────┼────────────────┼────────┘
+         │                │
+         ▼                ▼
+   ┌──────────┐    ┌──────────┐
+   │   Rust   │    │   Cache  │
+   │  Engine  │    │   Hit!   │
+   └─────┬────┘    └────┬─────┘
+         │              │
+         ▼              │
+   Compute O(log n)     │
+   Similarities         │
+         │              │
+         └──────┬───────┘
+                ▼
+         ┌─────────────┐
+         │   SAFLA     │
+         │  Reasoning  │
+         └──────┬──────┘
+                ▼
+         ┌─────────────┐
+         │  Leverage   │
+         │   Cards     │
+         └─────────────┘
+```
+
+### System Components
+
+| Component | Tech | Purpose | Complexity |
+|-----------|------|---------|------------|
+| MCP Server | Python 3.11 + FastAPI | API orchestration | O(1) |
+| FACT Cache | SQLite + SHA256 | Deterministic storage | O(1) lookup |
+| SAFLA Agent | Python + LLM | Analogical reasoning | O(k) prompts |
+| Sublinear Engine | Rust + gRPC | Semantic comparison | **O(log n)** |
+| Scanner | Go + goroutines | GitHub ingestion | O(n) parallel |
+
+### Performance Characteristics
+
+```
+Query Response Time:  <3 seconds
+Scan Throughput:      50+ repos/minute
+Memory Footprint:     <500MB
+CPU Usage:            <1 core
+Complexity:           TRUE O(log n)
+Determinism:          100% (FACT cache)
+```
+
+---
+
+## 🛠️ Building Systems With RuvScan
+
+### System 1: AI Code Assistant
+
+**Stack**: RuvScan + Claude + VS Code Extension
+
+```typescript
+// VS Code extension
+vscode.workspace.onDidChangeTextDocument(async (event) => {
+  const context = extractContext(event.document);
+
+  const suggestions = await ruvscan.query({
+    intent: `Optimize this code: ${context}`,
+    max_results: 3
+  });
+
+  showInlineSuggestions(suggestions);
+});
+```
+
+**Value**: Developer gets library suggestions as they code.
+
+### System 2: Autonomous Agent
+
+**Stack**: RuvScan + LangChain + OpenAI
+
+```python
+class BuilderAgent:
+    def __init__(self):
+        self.ruvscan = RuvScanClient()
+
+    async def optimize(self, codebase):
+        # Scan for bottlenecks
+        bottlenecks = await self.analyze(codebase)
+
+        # Find solutions
+        for issue in bottlenecks:
+            solutions = await self.ruvscan.query(
+                f"Solve: {issue.description}"
+            )
+
+            # Auto-apply best solution
+            await self.apply(solutions[0])
+```
+
+**Value**: Agent autonomously improves your code.
+
+### System 3: Research Platform
+
+**Stack**: RuvScan + Supabase + Next.js
+
+```javascript
+// Research dashboard
+async function discoverInnovations(techStack) {
+  // Scan your current stack
+  const current = await ruvscan.scan({
+    source_type: "org",
+    source_name: "your-company"
+  });
+
+  // Find improvements
+  const opportunities = await Promise.all(
+    current.map(repo =>
+      ruvscan.query(`Improve ${repo.name}`)
+    )
+  );
+
+  return rankByImpact(opportunities);
+}
+```
+
+**Value**: Continuous innovation discovery.
+
+---
+
+## 📊 API Reference
+
+### Core Endpoints
+
+#### POST `/query` - Find Leverage
+
+```bash
+curl -X POST http://localhost:8000/query \
+  -H "Content-Type: application/json" \
+  -d '{
+    "intent": "Your problem or goal",
+    "max_results": 10,
+    "min_score": 0.7
+  }'
+```
+
+**Response:**
+```json
+[{
+  "repo": "org/repo-name",
+  "capabilities": ["feature1", "feature2"],
+  "summary": "What this repo does",
+  "outside_box_reasoning": "Why this applies to your problem",
+  "integration_hint": "How to use it",
+  "relevance_score": 0.92,
+  "runtime_complexity": "O(log n)",
+  "cached": true
+}]
+```
+
+#### POST `/scan` - Scan Repositories
+
+```bash
+curl -X POST http://localhost:8000/scan \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_type": "org",
+    "source_name": "ruvnet",
+    "limit": 50
+  }'
+```
+
+#### POST `/compare` - Compare Repos
+
+```bash
+curl -X POST http://localhost:8000/compare \
+  -H "Content-Type: application/json" \
+  -d '{
+    "repo_a": "org/repo-1",
+    "repo_b": "org/repo-2"
+  }'
+```
+
+### MCP Integration
+
+RuvScan implements the Model Context Protocol for IDE/Agent integration:
+
+```json
+{
+  "mcpServers": {
+    "ruvscan": {
+      "command": "docker",
+      "args": ["run", "-p", "8000:8000", "ruvscan/mcp-server"]
+    }
+  }
+}
+```
+
+**Compatible with:**
+- Claude Desktop
+- Cursor
+- TabStax
+- Any MCP-compatible tool
+
+---
+
+## 🚀 Deployment
+
+### Development (Local)
+
+```bash
+# Using Docker
+docker compose up -d
+
+# Manual
+bash scripts/setup.sh
+make dev
+```
+
+### Production (Cloud)
+
+**Docker Compose:**
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+**Kubernetes:**
+```bash
+kubectl apply -f k8s/deployment.yaml
+```
+
+**Cloud Platforms:**
+- AWS: ECS, EKS
+- Google Cloud: Cloud Run, GKE
+- Azure: ACI, AKS
+
+See [DEPLOYMENT.md](docs/DEPLOYMENT.md) for full guide.
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+./scripts/run_tests.sh
+
+# Or specific suites
+pytest tests/test_server.py      # API tests
+pytest tests/test_embeddings.py  # Embedding tests
+pytest tests/test_fact_cache.py  # Cache tests
+pytest tests/test_integration.py # E2E tests
+```
+
+---
+
+## 📚 Documentation
+
+- **[Quick Start](docs/QUICK_START.md)** - Get running in 5 minutes
+- **[Architecture](docs/ARCHITECTURE.md)** - Deep technical dive
+- **[API Reference](docs/api/MCP_PROTOCOL.md)** - Complete API docs
+- **[Deployment](docs/DEPLOYMENT.md)** - Production deployment
+- **[Examples](examples/)** - Code examples
+
+---
+
+## 🎯 Roadmap
+
+### v0.5 (Current) ✅
+- MCP server with 5 endpoints
+- TRUE O(log n) algorithms
+- FACT deterministic caching
+- SAFLA analogical reasoning
+- Docker + Kubernetes deployment
+
+### v0.6 (Next)
+- [ ] Real-time streaming (MidStream)
+- [ ] Authentication & API keys
+- [ ] Rate limiting
+- [ ] Prometheus metrics
+- [ ] Enhanced LLM reasoning
+
+### v0.7
+- [ ] Advanced query DSL
+- [ ] Graph visualization
+- [ ] Multi-LLM support
+- [ ] WebSocket API
+- [ ] Plugin system
+
+### v1.0
+- [ ] Self-optimizing agent
+- [ ] Federated nodes
+- [ ] Community marketplace
+- [ ] Enterprise features
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+**Areas we need help:**
+- 🧪 Testing edge cases
+- 📚 Documentation improvements
+- 🌐 Language translations
+- 🔌 IDE integrations
+- 🎨 UI/Dashboard
+
+---
+
+## 📄 License
+
+MIT OR Apache-2.0 - Choose whichever works for you.
+
+---
+
+## 🙏 Built On
+
+RuvScan stands on the shoulders of giants:
+
+- **[sublinear-time-solver](https://github.com/ruvnet/sublinear-time-solver)** - TRUE O(log n) algorithms
+- **[FACT](https://github.com/ruvnet/FACT)** - Deterministic AI framework
+- **[MidStream](https://github.com/ruvnet/MidStream)** - Real-time streaming
+- **[FastAPI](https://fastapi.tiangolo.com/)** - Modern Python web
+- **[Rust](https://www.rust-lang.org/)** - Performance-critical code
+- **[Go](https://go.dev/)** - Concurrent systems
+
+---
+
+ 
+
+---
+
+## ✨ The Vision
+
+**RuvScan makes every developer 10× more productive by turning the entire open-source world into their personal innovation engine.**
+
+Instead of reinventing the wheel, developers discover existing solutions — even ones from completely different domains — and apply them creatively to their problems.
+
+**The result**: Faster builds, better architectures, and constant innovation.
+
+---
+
+ 
+
+---
+