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

CODEBLOCK0

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

3. Verify Connection

CODEBLOCK1

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):

CODEBLOCK2

Replace rrk_your_api_key_here with your actual API key.

MCP Tools

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

Tool	Description
INLINECODE6	Import a GitHub repo by URL
INLINECODE7

List imported repos |
| get_repository(repository_id) | Get repo details by ID |
| start_analysis(repository_id, analysis_type, branch?) | Queue an analysis job |
| list_analyses(page?, per_page?, repository_id?, status?, analysis_type?) | List jobs with filters |
| get_analysis(analysis_id) | Get full analysis results |
| get_analysis_status(analysis_id) | Lightweight status poll |
| get_token_balance() | Check available tokens and tier |

REST API Fallback

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

CODEBLOCK3

Or call the REST API directly:

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

Endpoint	Method	Description
INLINECODE16	INLINECODE17	Import repo INLINECODE18
INLINECODE19

GET | List repos ?page=1&per_page=20 |
| /repositories/{id} | GET | Get repo details |
| /analyses | POST | Start analysis {"repository_id": "...", "analysis_type": "..."} |
| /analyses | GET | List analyses ?repository_id=...&status=... |
| /analyses/{id} | GET | Get full results |
| /analyses/{id}/status | GET | Lightweight status check |
| /tokens/balance | GET | Check token balance |

---

Choosing an Analysis Type

Context	Type	What You Get
New to a codebase, need orientation	INLINECODE36	Architecture, patterns, key components
Need to create or update documentation

readme | Full README documentation |
| Pre-deploy, PR review, or security audit | security | Vulnerability analysis, risk assessment |
| Need visual architecture diagrams | mermaid | Workflow and system diagrams |
| Building AI tools that consume repo context | llmstxt | LLM-optimized summary |

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

---

Workflow

1. 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 INLINECODE49
4. Start analysis — start_analysis(repository_id, analysis_type) — save the returned INLINECODE51
5. Poll for completion — get_analysis_status(analysis_id) every 10 seconds until status is completed or INLINECODE55
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. 1. Import the repo
2. Run INLINECODE58
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. 1. Import the repo
2. Run both in parallel:

- start_analysis(repo_id, "readme") - start_analysis(repo_id, "mermaid")

1. 3. Poll both until completed
2. Combine the README content with the visual diagrams

Security Check Before Deploy

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

1. 1. Import the repo
2. Run INLINECODE61
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
• INLINECODE64 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 INLINECODE70
• 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
• INLINECODE76 must be one of: readme, technical, security, mermaid, INLINECODE81