Metadata-Version: 2.4
Name: repiscope
Version: 0.2.1
Summary: A periscope for your repos - read-only MCP server for sibling repository context
Author: 3xpr1ment
License-Expression: MIT
Project-URL: Homepage, https://github.com/3xpr1ment/repiscope
Project-URL: Repository, https://github.com/3xpr1ment/repiscope
Project-URL: Issues, https://github.com/3xpr1ment/repiscope/issues
Keywords: mcp,mcp-server,llm,agent,read-only,repositories
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Repiscope

**A periscope for your repos — see everything, touch nothing.**

Repiscope is a read-only MCP server that gives your coding agent (Claude Code,
Cursor, or any MCP client) awareness of the *sibling repositories* next to the
one it's working in — without ever letting it modify them.

## Why

When you run a coding agent inside project A, sometimes it needs to know how
you solved something in project B. Opening project B to the agent is scary:
it might start editing files there. Telling it "don't touch anything" is a
request. Repiscope makes it a **guarantee**: the server exposes zero write
tools, so the agent structurally *cannot* modify your other repos.

## See it in action

You're working in `project-a` and your agent needs to know how you handled
auth in another project. Instead of you copy-pasting files, the agent asks
Repiscope directly:

```
You:    How did I do JWT refresh in my other API project?

Agent:  (calls list_projects → sees "billing-api")
        (calls search "refresh_token" project="billing-api")
        (calls read_file "billing-api" "src/auth/tokens.py")

        In billing-api you rotate the refresh token on every use and
        store the previous hash for a 60s grace window — here's the
        pattern, adapted for project-a:
        ...
```

The agent read three files in a repo it has **no ability to write to**. No
copy-paste, no "please don't edit anything," no risk.

## Tools

| Tool | Input | Returns |
|------|-------|---------|
| `list_projects()` | — | every sibling repo + one-line description |
| `project_overview(project)` | repo name | full overview: purpose, stack, structure, recent commits |
| `search(query, project?)` | text, optional repo | files & lines matching the query |
| `read_file(project, path)` | repo + file path | full file contents (size-capped) |
| `store_summary(project, summary)` | repo + your text | caches an agent-written summary (see below) |

## How it stays fresh

Overviews are cached as markdown and refreshed lazily: on each call Repiscope
compares the repo's current git commit hash against the one recorded when the
overview was built. Same hash → serve the cache. Different → rebuild just that
repo's overview. No cron, no daemons.

## Borrowed intelligence

Repiscope has no LLM of its own — no API key, no model calls, zero cost. But
it talks to LLMs all day, so it borrows them: when an overview has no fresh
agent-written summary, it ends with a note asking the *calling* agent to
write one and hand it back via `store_summary`. The summary then opens every
future overview of that project — written by one agent, read by all the
next — until the repo's next commit marks it outdated and the cycle repeats.

## Security by architecture

Repiscope is built so that the safe behaviour is not a promise — it's the
only behaviour possible:

- **Zero repo-write tools.** The server exposes no tool that can create,
  edit or delete anything inside your repositories. The one tool that
  accepts data, `store_summary`, can only write to Repiscope's own cache in
  `~/.cache/repiscope`. An agent cannot misuse a capability that doesn't
  exist.
- **Secrets are invisible.** A single filter (`privacy.py`) is enforced by
  every tool: private keys, certificates (`.pem`, `.pfx`, `.p12`, …),
  `.env*` files, keystores, and anything named like a credential never
  appear in overviews, trees, search results or file reads.
  *Honest limit:* the filter hides sensitive **files** — it does not scrub
  mentions of e.g. a password pasted inside an ordinary text file.
- **You define the perimeter.** Repiscope only sees the folder you
  explicitly pass (`--root`), and `--exclude` makes chosen repos fully
  invisible — they can't even be resolved by name.
- **It leaves no trace.** Overview caches live in `~/.cache/repiscope`,
  never inside your repositories.

## Quick start

```bash
git clone https://github.com/3xpr1ment/repiscope.git
cd repiscope
python -m venv .venv && .venv/bin/pip install -e .
```

Register it with your MCP client — for Claude Code:

```bash
claude mcp add repiscope --scope user -- \
  /path/to/repiscope/.venv/bin/repiscope --root ~/your/projects/folder
```

Optionally hide repos with `--exclude repo-a --exclude repo-b`.

## Status

v1.5 — working and dogfooded daily. Four read-only tools plus borrowed-LLM
summaries, lazy cache refresh, sensitive-file filtering. No tests yet; API
may still change.

## License

[MIT](LICENSE)
