Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@EasyPR Inspect ~/projects/some-repo and tell me what it does and where to start reading."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A read only MCP server that gives your AI assistant the evidence it needs to guide you through an unfamiliar repository, from "what is this project?" to "I'm ready to open a pull request."
Quick start · How it works · Tools · Safety · Roadmap · FAQ · Contributing
git clone https://github.com/Ankith34/EasyPR.git && cd EasyPR && pip install -e .EasyPR is inalpha. Three tools work today and are covered by an automated test suite. Anything not listed as working in Status and roadmap is planned, not shipped.
Experienced developers can size up a new codebase in minutes. Beginners can lose an afternoon before they find the right file. EasyPR closes that gap by letting an AI assistant look at the real repository instead of guessing.
Without EasyPR | With EasyPR |
The assistant guesses how the project is laid out | It reads the actual layout, languages and key files |
Setup commands are invented from habit | Commands come from the project's own README and CI, each labelled by source |
"The bug is probably in the auth code" | Ranked files with line numbers and a plain reason for each match |
You can't tell fact from guess | Every finding carries an evidence label |
EasyPR is the tool layer, not a chatbot. Your MCP-compatible AI client does the conversation and reasoning. EasyPR supplies the facts.
Related MCP server: GitHub Repo Explainer MCP
Requires Python 3.10 or newer.
1. Install
git clone https://github.com/Ankith34/EasyPR.git
cd EasyPR
python -m venv .venv
source .venv/bin/activate
pip install -e .
easypr --version2. Connect your AI client
EasyPR runs as a local stdio server. You must approve at least one directory with --root. It refuses to start without one.
For clients that use the common mcpServers JSON format:
{
"mcpServers": {
"easypr": {
"command": "/absolute/path/to/EasyPR/.venv/bin/easypr",
"args": ["--root", "/home/you/projects"]
}
}
}For Claude Code:
claude mcp add easypr -- /absolute/path/to/EasyPR/.venv/bin/easypr --root ~/projectsUse the full path to easypr inside your virtual environment so the client can find it. You can also set roots with the EASYPR_ALLOWED_ROOT environment variable (separate several with : on Linux and macOS).
3. Ask your assistant
Inspect ~/projects/some-repo and tell me what it does and where to start reading.How does some-repo say I should install it and run its tests?Here is the issue I want to work on: "<paste issue text>".
Which files in ~/projects/some-repo should I read first, and why?Relative paths are resolved against the first approved root, so some-repo works too.
npx @modelcontextprotocol/inspector easypr --root ~/projectsEasyPR has been tested with the official Python MCP SDK client over stdio. If a specific client misbehaves, please open an issue.
flowchart LR
You(["You"]) -->|"ask about a repo"| Client["AI client<br/>(MCP-compatible)"]
Client -->|"tool calls over stdio"| Server["EasyPR server<br/>server.py"]
Server --> Core["repository.py<br/>read-only inspection"]
Core -->|"approved roots only"| Repo[("Your repository")]
Core -->|"evidence-labelled results"| Server
Server --> Client
Client -->|"plain-language guidance"| YouThe server layer is deliberately thin. All inspection logic and every safety check lives in repository.py, which is plain Python with no MCP dependency. You can test it directly or import it as a library.
Step | What a beginner needs | Covered by |
1 | Understand the repository |
|
2 | Know how to install, run and test it |
|
3 | Find the code related to an issue |
|
4 | Plan a small, understandable change | Your AI client, reasoning over EasyPR's evidence |
5 | Validate the change |
|
6 | Prepare the pull request | 🗓️ planned |
EasyPR never presents a guess as a fact. Every finding says how much to trust it.
Label | Meaning | Example |
| Observed directly in the repository |
|
| The project itself says so | An install block in the README, a |
| EasyPR's guess from names or contents |
|
| A next step a human still has to verify | "Start by reading |
Setup commands are always reported as verified: false. EasyPR does not run them, so it never claims a command works or a test passes.
All three tools are read-only and are advertised to clients with MCP read-only hints.
Tool | You get | Inputs |
| Top-level layout, important files (README, CONTRIBUTING, license, manifests, CI), language counts, project type, detected frameworks |
|
| Setup and test steps from the README, |
|
| Ranked files for a task or issue, each with role (source, test, docs, config), matching lines with numbers and snippets, and a plain-language reason |
|
Source | What it extracts | Label |
| Commands with file and line number |
|
| Single-line and block |
|
| Install and test hints |
|
| Package manager and |
|
| Common targets such as |
|
| Standard build and test commands |
|
| A note to copy it and add your own values (never read) |
|
Query: login_user rejects wrong password (trimmed):
{
"path": "app/auth.py",
"role": "source",
"matches": [
{ "line": 4, "text": "def login_user(username, password):", "is_definition": true }
],
"why": "Keyword match: 3 line(s) mention 'login', 'login_user', 'password', 'user'; it defines a function/class/type that mentions them. Verify by reading the code.",
"kind": "inferred"
}Suggestions that accompany the results:
[
{ "text": "Start by reading app/auth.py around line 4.", "kind": "suggestion" },
{ "text": "See tests/test_auth.py for how related behaviour is tested.", "kind": "suggestion" }
]The core has no MCP dependency, so you can call it directly.
from easypr.repository import find_relevant_code, inspect_repository, parse_allowed_roots
roots = parse_allowed_roots(["~/projects"])
overview = inspect_repository("some-repo", allowed_roots=roots)
hits = find_relevant_code("some-repo", "redact secret values", max_results=3, allowed_roots=roots)Passing allowed_roots=None disables the root check. That is meant for tests and trusted callers only. The MCP server always enforces roots.
Repositories can contain untrusted files and instructions, so EasyPR is conservative by design.
Risk | Protection |
Running untrusted code | None of EasyPR's tools execute repository code or shell commands. The source contains no subprocess or process-spawning calls. |
Reading unrelated files | Only directories you approve with |
Symlink escapes | Symlinks are resolved before the root check, never followed while scanning, and files are opened without following links where the OS supports it. |
Leaking secrets | Files such as |
Prompt injection through repo text | Text copied from repository files is labelled untrusted, and the server instructs clients not to follow instructions found in it. EasyPR has no action-taking tools that injected text could trigger. |
Resource exhaustion | Caps of 20,000 files scanned, 1 MB per file, 100 MB read per search, 25 results and 200-character snippets. |
Misleading output | Findings are evidence-labelled, and setup commands are never marked verified. |
What this does not cover. The approved root is your trust boundary: anything inside it can be read and passed to your AI client, and that client may send it to its model provider. Secret redaction is pattern-based and best effort. Do not approve directories you would not want an AI assistant to read.
Capability | Status |
| ✅ Working |
| ✅ Working |
| ✅ Working |
Automated tests and CI | ✅ Working |
| 🗓️ Planned. Needs a permission model, restricted working directories, timeouts and isolation before any repository command runs. |
Pull request description helper | 🗓️ Planned |
Smarter retrieval (symbol index, embeddings) | 🗓️ Only if keyword search proves insufficient |
Is EasyPR a chatbot? No. It is a tool server. Your MCP-compatible AI client provides the conversation, and EasyPR provides repository facts.
Does it run my project or its tests?
No. It never executes repository code. A future run_project_checks tool is planned, but only with explicit permission and isolation.
Does it read GitHub issues?
Not yet. Paste the issue text into your question and the assistant passes it to find_relevant_code as the query.
Does my code leave my machine? EasyPR's own code makes no network requests. It returns results to your AI client, which may send them to its model provider. Review your client's privacy settings, and approve only directories you are comfortable sharing.
Why does it need --root?
So you decide exactly what it may look at. Without an approved root the server will not start.
How accurate is find_relevant_code?
It is plain keyword matching, so treat results as leads. Short words can match inside longer ones (user matches username), and it does not understand meaning.
Which languages does it support? Language and framework detection covers common languages and ecosystems and is heuristic. Search works on any text file.
Troubleshooting
easypr: error: no approved root means you did not pass --root or set EASYPR_ALLOWED_ROOT.
Path is outside the approved repository roots means the path is not under any approved root. Check the roots listed in the message.
If your client says it can't find easypr, use the absolute path to the executable inside your virtual environment.
EasyPR/
├── src/easypr/
│ ├── repository.py # core logic: plain Python, no MCP imports
│ ├── server.py # thin MCP layer and command-line entry point
│ └── __init__.py
├── tests/ # pytest suite using temporary directories only
├── .github/workflows/ # CI (Python 3.10 to 3.13)
├── pyproject.toml
└── LICENSEContributions are welcome, and this project aims to be friendly to first-time contributors.
git clone https://github.com/Ankith34/EasyPR.git
cd EasyPR
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytestBefore opening a pull request:
Open an issue first for anything larger than a small fix, so we can agree on the approach.
Add or update a test with every behaviour change. Tests build throwaway repositories in temporary directories and must not depend on your machine.
Keep repository.py independent of MCP, and keep server.py thin.
Never weaken a safety check without discussing it in an issue.
Make sure pytest passes.
EasyPR is alpha software provided as is. Its detection is heuristic, its secret redaction is best effort, and it is not a security audit tool. Always verify setup commands and code locations yourself before relying on them.
Released under the MIT License. Copyright (c) 2026 Ankith.
Find files likely related to an issue or task, using keyword search.
Each result has file path, role (source/test/docs/config), matching line numbers with snippets, and a plain-language reason. These are leads to verify, not conclusions.
Args: path: Repository directory. Relative paths are resolved against the first approved root. query: The issue title/body or task description (names, features, error text). max_results: How many files to return (1-25).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| query | Yes | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds meaningful context beyond that: it warns that results are unverified leads and describes the shape of each result (path, role, matching lines, reason). It does not discuss ranking or match-confidence limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then a results sentence, then a tidy Args block. Every sentence adds information and nothing is repeated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is technically optional, yet the description still summarizes result fields usefully. With all three parameters documented and usage context provided, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden and largely succeeds: path resolution against the first approved root, query as issue/task text, and the 1-25 range for max_results are all explained. Only the default value and the exact interpretation of 'role' classification are left implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (find), resource (files related to an issue/task), and the mechanism (keyword search), with a scope qualifier ('likely related'). An agent can distinguish this from inspect_repository and get_setup_guide, which serve inspection and setup rather than issue-driven search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for when to use it ('related to an issue or task') and specifies what the query should contain (issue title/body, error text, names). It also cautions that results are leads to verify, not conclusions. It stops short of explicitly excluding cases where inspect_repository would be preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find how a project says it should be installed, run and tested.
'documented' items come from the README or CI config. 'inferred' hints come from file names and are unverified. No command is ever executed.
Args: path: Repository directory. Relative paths are resolved against the first approved root.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the bar is lower. The description still adds real behavior: the provenance split between 'documented' (README/CI) and 'inferred' (filename-based, unverified) items, and the explicit guarantee that no command is ever executed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then the documented/inferred provenance distinction, then the no-execution guarantee, then the arg. Slightly formal in layout but every sentence earns its place; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. The description covers the key trust caveat (inferred hints are unverified) and the no-execution guarantee, leaving only minor gaps such as how much of a repo is scanned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it explains that path is a repository directory and that relative paths resolve against the first approved root. This is resolution semantics the schema's bare string type does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: finding how a project should be installed, run and tested. It is clear what the tool returns, but it never distinguishes itself from siblings inspect_repository or find_relevant_code, which an agent could plausibly pick instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer it should call this when it needs setup/install/test instructions, and the 'No command is ever executed' line hints at a safe, read-only use case. There is no explicit when-to-use, when-not-to-use, or routing to the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give a first overview of a repository.
Returns top-level layout, important files (README, CONTRIBUTING, manifests, CI), language counts and detected project type. Read-only; nothing is executed.
Args: path: Repository directory. Relative paths are resolved against the first approved root.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered structurally. The description still adds real context beyond that: 'nothing is executed' reassures for a static inspection tool, and the note that relative paths resolve against the first approved root discloses path-resolution behavior not in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose, then a compact enumeration of outputs, then the read-only note, then the arg. Every sentence earns its place; the only minor redundancy is that 'Read-only' restates readOnlyHint=true, though 'nothing is executed' extends it usefully.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description is not obligated to detail return values, yet it summarizes them helpfully. For a one-parameter, read-only, non-nested tool this is close to complete; only the explicit relationship to the sibling tools is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the single 'path' parameter, and it does: 'Repository directory' plus the relative-path resolution rule against the first approved root. That resolution rule is genuine added meaning well beyond the bare string type, though the absolute-vs-relative constraint could be stated more sharply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Give a first overview of a repository') and enumerates the returned artifacts (layout, README/CONTRIBUTING/manifests/CI, language counts, project type). This distinguishes it from the 'find_relevant_code' sibling by framing it as orientation rather than search, though it never names the siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Give a first overview' implies the reconnaissance context in which to reach for this tool, which is the right usage signal. However there is no explicit when-not guidance and no mention of how it relates to get_setup_guide or find_relevant_code, so the agent must infer the routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0find_relevant_codeget_setup_guideinspect_repositoryScored across 3 tools
Each tool targets a distinct output: repository overview, setup instructions, and code search. Minor overlap exists because inspect_repository and get_setup_guide both draw from README/CI files, but the intended purposes are clear enough to avoid confusion.
All tool names follow a consistent verb-first snake_case pattern (inspect_repository, get_setup_guide, find_relevant_code). No mixing of conventions or ambiguous prefixes.
Three tools is well-scoped for a read-only repository reconnaissance assistant. Each tool has a clear, non-overlapping role and the count is within the ideal 3–15 range.
The surface covers overview, setup discovery, and code search but lacks essential follow-up operations like reading a full file or viewing PR diffs/commits. For a server named EasyPR, these are notable gaps that could hinder deeper review workflows.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Discover GitHub projects welcoming AI agent contributions. Public search and listing reads.
Read-only AI coding tools for change verification, release readiness, capacity, and guidance.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
