Reporead

RepoRead — AI Repository Analysis

RepoRead is an AI-powered platform that analyzes GitHub repositories and generates documentation, technical architecture breakdowns, security audits, visual diagrams, and LLM-optimized summaries. Connect via the MCP server (preferred) or REST API to analyze any public GitHub repository.

Quick Start

1. Get an API Key

Sign up at reporead.com and create an API key at reporead.com/settings. Keys use the rrk_ prefix.

2. Set the Environment Variable

export REPOREAD_API_KEY="rrk_your_api_key_here"

Add to your shell profile (~/.zshrc, ~/.bashrc) to persist across sessions.

3. Verify Connection

bash {baseDir}/scripts/check-connection.sh

This confirms your API key is valid and shows your current token balance.

4. Connect the MCP Server (Recommended)

Add to your MCP configuration (e.g. claude_desktop_config.json, .mcp.json):

{
  "mcpServers": {
    "reporead": {
      "type": "streamable-http",
      "url": "https://api.reporead.com/mcp",
      "headers": {
        "Authorization": "Bearer rrk_your_api_key_here"
      }
    }
  }
}

Replace rrk_your_api_key_here with your actual API key.

MCP Tools

When the MCP server is connected, these tools are available:

REST API Fallback

If the MCP server is not configured, use the REST API helper script:

# Check token balance
bash {baseDir}/scripts/reporead-api.sh balance

# Import a repository
bash {baseDir}/scripts/reporead-api.sh import https://github.com/owner/repo

# Start an analysis
bash {baseDir}/scripts/reporead-api.sh analyze <repository_id> technical

# Check analysis status
bash {baseDir}/scripts/reporead-api.sh status <analysis_id>

# Get full analysis results
bash {baseDir}/scripts/reporead-api.sh results <analysis_id>

# List repositories
bash {baseDir}/scripts/reporead-api.sh repos

Or call the REST API directly:

Base URL: https://api.reporead.com/public/v1 Auth: Authorization: Bearer $REPOREAD_API_KEY

Choosing an Analysis Type

Default: Use technical if unsure. Full docs: Combine readme + mermaid. Free tier: readme and llmstxt only. Paid tiers unlock all types.

Workflow

1. Check balance — get_token_balance() to verify sufficient tokens
2. Check if already imported — list_repositories() to avoid duplicates
3. Import the repo — import_repository(github_url) — save the returned id
4. Start analysis — start_analysis(repository_id, analysis_type) — save the returned id
5. Poll for completion — get_analysis_status(analysis_id) every 10 seconds until status is completed or failed
6. Fetch results — get_analysis(analysis_id) — the results field contains the full output
7. Use the results as context for the user's task

Common Patterns

Understand a Codebase Before Working on It

When the user says "explain this repo" or you need context before coding:

1. Import the repo
2. Run start_analysis(repo_id, "technical")
3. Poll until completed
4. Use the architecture breakdown, key patterns, and component descriptions as working context

Generate Documentation

When the user wants a README, docs, or visual diagrams:

1. Import the repo
2. Run both in parallel:
   • start_analysis(repo_id, "readme")
   • start_analysis(repo_id, "mermaid")
3. Poll both until completed
4. Combine the README content with the visual diagrams

Security Check Before Deploy

When reviewing a repo for vulnerabilities or doing a PR audit:

1. Import the repo
2. Run start_analysis(repo_id, "security")
3. Poll until completed
4. Review findings and flag critical issues to the user

Token Awareness

• Always call get_token_balance() before starting an analysis
• If available_tokens is low, tell the user — they can purchase more at reporead.com/settings
• Monthly allowances: Free 100K, Starter 500K, Growth 1M
• Larger repos consume more tokens
• reserved_tokens shows tokens held for in-progress analyses

Tips

• Poll get_analysis_status, not get_analysis — much lighter payload
• Poll every 10 seconds. Analysis takes 1-5 minutes depending on repo size
• Status values: queued → processing → completed or failed
• If status is failed, show the error field to the user — do not retry automatically
• Use list_repositories before import_repository to avoid "already imported" errors
• The branch parameter is optional — defaults to the repo's default branch
• Rate limit: 60 requests/minute burst
• analysis_type must be one of: readme, technical, security, mermaid, llmstxt