EasyPR

Your first PR starts here.

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 .

Why EasyPR

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.

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 Activity MCP Server

Quick start

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 --version

2. 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 ~/projects

Use 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 ~/projects

EasyPR has been tested with the official Python MCP SDK client over stdio. If a specific client misbehaves, please open an issue.

How it works

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"| You

The 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.

The first-contribution workflow

Evidence labels

EasyPR never presents a guess as a fact. Every finding says how much to trust it.

Setup commands are always reported as verified: false. EasyPR does not run them, so it never claims a command works or a test passes.

Tools

All three tools are read-only and are advertised to clients with MCP read-only hints.

What EasyPR reads

 

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" }
]

Use it as a Python library

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.

Safety model

Repositories can contain untrusted files and instructions, so EasyPR is conservative by design.

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.

Status and roadmap

FAQ

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.

Project layout

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
└── LICENSE

Contributing

Contributions 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]"
pytest

Before opening a pull request:

1. Open an issue first for anything larger than a small fix, so we can agree on the approach.

2. Add or update a test with every behaviour change. Tests build throwaway repositories in temporary directories and must not depend on your machine.

3. Keep repository.py independent of MCP, and keep server.py thin.

4. Never weaken a safety check without discussing it in an issue.

5. Make sure pytest passes.

Disclaimer

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.

License

Released under the MIT License. Copyright (c) 2026 Ankith.