Skip to content
Back to search

RepoSafe-MCP

Privacy-first MCP server that scans repositories for exposed secrets, private references, and security risks before open-source publication. Local, read-only, and free. Copia descrizione

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vladtepes84--reposafe-mcp/badge.svg)](/listings/vladtepes84--reposafe-mcp)

HTML

<a href="/listings/vladtepes84--reposafe-mcp"><img src="/api/listings/vladtepes84--reposafe-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires **Node.js 22+, npm and Git** (Git is needed for history checks). The source is public; clone it directly from GitHub. An npm-compatible tarball and binaries are prepared and tested, but **no package has been published to the npm registry**.

git clone https://github.com/VladTepes84/RepoSafe-MCP.git
cd RepoSafe-MCP
npm ci
npm run check
npm run demo

The committed `package-lock.json` pins npm dependencies with integrity hashes; `npm ci` verifies them.

`npm run check` performs TypeScript typecheck, build, unit/security regression tests, an actual stdio MCP handshake with the official client SDK, and the synthetic Git-history scenario. `npm run demo` repeats the scenario independently and prints three expected stages. CI runs the same commands on **Ubuntu, Windows and macOS**. **CI is not a substitute for verifying the GUI client on your machine.**

Run the self-check and generate a verified client configuration

After `npm ci && npm run build`, run:

node dist/cli.js doctor --root "/absolute/path/to/project"
node dist/cli.js init --root "/absolute/path/to/project" --client cursor

`doctor` actually starts RepoSafe over stdio and discovers six MCP tools. `init` also prints the target client configuration but **does not overwrite** any user files or claim the GUI application itself was tested. The authorized directory must be a specific existing absolute path.

Generate a real MCP configuration for your computer

Instead of manually copying placeholders, let RepoSafe print the **actual absolute paths** for your Node executable, compiled server and approved target directory:

npm run config -- --client cursor --root "/absolute/path/to/your/project"

Supported `--client`: `cursor`, `claude`, `vscode`, `codex` (TOML). The configuration generator **prints only** and does **not** overwrite your client's configuration. Merge its `reposafe` entry with any existing servers. See the OS-specific guides:

- **[macOS: tested commands and client configuration](docs/INSTALL_MAC.md)** - **[Windows PowerShell: exact installation and client configuration](docs/INSTALL_WINDOWS.md)** - **[Current client support and authoritative documentation](docs/CLIENTS.md)**

Scan without any AI

node dist/cli.js scan --root "/absolute/path/to/your/project"
node dist/cli.js scan --root "/absolute/path/to/your/project" --json

Exit status: **0** = no findings *in the examined scope*, **1** = review required or incomplete coverage, **2** = invalid arguments or scan error. This allows adding RepoSafe to other workflows while keeping the server itself read-only.

Actionable CLI and SARIF

node dist/cli.js scan --root "/ABSOLUTE/PATH/TO/APP"
node dist/cli.js scan --root "/ABSOLUTE/PATH/TO/APP" --sarif > reposafe.sarif

**Careful:** writing `reposafe.sarif` inside the scanned repository is a user shell action, not a write performed by RepoSafe; for audits prefer a file outside the target repo. SARIF contains finding metadata, not credential values. It can be uploaded to GitHub Code Scanning only when that feature is enabled and the workflow is given the required rights. The repository's example action never uploads automatically.

For a read-only pull-request check, see [GitHub Actions setup](docs/ACTIONS.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 190 lines
  1. # RepoSafe MCP
  2. **Before you publish, discover what your source code and Git history could expose.**
  3. RepoSafe is a privacy-first, read-only repository scanner available as a **local Model Context Protocol (MCP) server** and **standalone CLI**. It flags possible secrets, private infrastructure references, Git-tracked credential files, ineffective `.gitignore` rules, and secrets left in *recent Git commits*. It returns **metadata only**: never source snippets or matched secret values.
  4. **Release status: v0.5.0 beta source (pre-release). Not a security certification.** A clean scan is *not* evidence that a repository is safe to publish.
  5. [![Support RepoSafe MCP on GitHub Sponsors](https://img.shields.io/badge/Support%20RepoSafe%20MCP-GitHub%20Sponsors-EA4AAA?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/VladTepes84)
  6. **Support this open-source project:** RepoSafe MCP is free and MIT-licensed. If it helps you audit repositories, you can [sponsor the maintainer on GitHub](https://github.com/sponsors/VladTepes84) to support maintenance, security testing, and documentation. Contributions are **entirely optional** and do not unlock extra features, hosted services, or privileged access.
  7. ## Important: Cursor and Claude Desktop are NOT yet manually verified
  8. > **Integration validation pending.** RepoSafe's installation, TypeScript build, scanner tests, actual MCP `stdio` handshake using the official MCP SDK, and synthetic Git-repository demo have passed automated CI on **Windows, macOS and Ubuntu**.
  9. >
  10. > **Cursor and Claude Desktop have NOT yet been manually tested end-to-end in their actual application interfaces.** The configuration examples below are documented and configuration generation is unit-tested, but **successful GUI integration, permissions, prompts and user experience remain UNVERIFIED**. Do not interpret protocol-level MCP testing as proof that these apps work out of the box. Other client GUI integrations are also not verified.
  11. >
  12. > This is **beta software**. Do not assume it detects all secrets, guarantees privacy in the AI host, or certifies a repository as safe to publish.
  13. ### Help validate real AI clients
  14. 1. Follow the exact [macOS](docs/INSTALL_MAC.md) or [Windows](docs/INSTALL_WINDOWS.md) installation guide with **Node.js 22+, npm and Git**.
  15. 2. Run `npm ci && npm run check && npm run demo` (in PowerShell, invoke the commands separately if needed). All must pass before connecting a client.
  16. 3. Generate the client configuration using `npm run config -- --client cursor --root ABSOLUTE_PROJECT_PATH` or replace `cursor` with `claude`; use a small **synthetic test repository**, never real credentials.
  17. 4. Add the generated entry to the client's MCP configuration, restart/reload the client as documented, and ask it to list RepoSafe tools and call `generate_report`.
  18. 5. Verify all six tools are visible, the report is returned, the dummy secret is never disclosed and out-of-scope paths are inaccessible. Report the operating system and client version plus **redacted** logs in a GitHub issue. Do not upload private code, credentials, or unredacted configuration.
  19. See [client compatibility and explicit verification status](docs/CLIENTS.md) and [security limitations](docs/SECURITY.md).
  20. ## A 60-second real use case
  21. You created a web app and want to publish its GitHub repository. You connect RepoSafe to Cursor / Claude Desktop / VS Code / Codex, then ask:
  22. > Use RepoSafe `generate_report` on the pre-authorized project. Explain critical findings first, and never request or print token values.
  23. RepoSafe checks the working tree, validates Git ignore rules, inspects tracked credential-file names and bounded local Git history. Imagine that you deleted a token from today's code, but it is still in a commit from yesterday. RepoSafe flags the **historic exposure**, even when the working tree is clean. You rotate the token, address the exposure, and scan again. The demo script reproduces this workflow with a **synthetic** token—no cloud keys or real projects needed.
  24. ```text
  25. You / AI client (Cursor, Claude, Copilot, Codex)
  26. | local stdio / MCP
  27. v
  28. RepoSafe MCP (local Node.js process; read-only tools)
  29. | scoped to REPOSAFE_ROOT
  30. v
  31. Current files + local Git metadata / bounded history
  32. | no cloud upload, no shell, no repository modification
  33. v
  34. JSON report: severity, relative file, rule, action, coverage
  35. ```
  36. ## Features
  37. | Tool | Purpose |
  38. | --- | --- |
  39. | `scan_secrets` | Flag recognizable API token patterns, private keys and suspicious assignments in local files |
  40. | `scan_private_refs` | Detect internal hostnames, local user paths and GitHub links requiring verification |
  41. | `check_repo_readiness` | Check README, license, `.gitignore` and real Git ignore behavior |
  42. | `check_git_exposure` | Identify tracked sensitive filenames and ineffective `.env` ignore rules |
  43. | `scan_git_history` | Scan up to 100 local commits / 4 MiB of diffs for possible lingering credentials; show a safe 12-character introducing commit ID |
  44. | `generate_report` | Consolidate all findings, scope, coverage and warnings |
  45. Additional CLI: `node dist/cli.js scan --root ABSOLUTE_PATH [--json|--sarif] [--no-history] [--no-git]`. The default view is a severity-sorted actionable human report.
  46. **No edits, auto-fixes, Git checkout, push, remote API calls or background processes.** The AI client cannot pass an arbitrary filesystem path to tools. All operations are restricted to the operator-defined absolute `REPOSAFE_ROOT` set when the server starts.
  47. ### v0.5 usability and GitHub integration
  48. - Human-friendly CLI report sorted by severity, with a recommended action for each finding; use `--json` for structured data.
  49. - Redacted **SARIF 2.1.0** via `scan --sarif`, including an explicit `incomplete_scan` result when coverage fails closed.
  50. - npm packaging is **prepared, not published**: `bin` exposes `reposafe` and `reposafe-mcp`, restricted `files` whitelist and `prepack` build; `private: true` remains. CI checks `npm pack --dry-run`.
  51. - A local **composite GitHub Action** (`action.yml`) scans pull-request checkouts with read-only content permissions and writes SARIF to the runner's temporary folder. Automatic upload is **not** enabled. See [GitHub Action guide](docs/ACTIONS.md).
  52. **Remaining steps:** manual Cursor/Claude Desktop GUI validation and a separately approved npm registry publication. Source-only CI cannot prove either.
  53. ### v0.4 coverage and onboarding improvements
  54. - Expanded database/broker URL credential detection for **MySQL, MariaDB, MongoDB/SRV, Redis/TLS and AMQP/TLS**, retaining the existing PostgreSQL rule.
  55. - Added heuristic indicators for **GitLab, Hugging Face, DigitalOcean, Twilio API key IDs, Slack/Discord webhook URLs, Azure Storage account keys and GCP service-account key material**.
  56. - Git-tracked files under excluded dependency/cache directories are now **read directly within strict file/byte/path budgets**, with a review warning. Unsafe links, binary files, and unreadable content fail closed.
  57. - Strict `.reposafe.json` exact-path/exact-rule exceptions with mandatory explanation, optional expiration and suppression counts. High/critical exceptions never yield a clean verdict; malformed policies fail closed.
  58. - `reposafe doctor` validates Node, Git, the authorized folder and actually connects to the local server via the official MCP client to discover all six tools.
  59. - `reposafe init` performs the same handshake and **prints** an exact client configuration without writing or changing any host files.
  60. **Neither `doctor` nor `init` proves Cursor/Claude Desktop GUI functionality.** Those app tests remain pending. See [the v0.4 user guide](docs/QUICKSTART.md) and [baseline security rules](docs/BASELINE.md).
  61. ### v0.3 detection improvements
  62. - Heuristic coverage now includes **JWT, SendGrid, npm tokens (including `.npmrc` auth entries), PostgreSQL connection URI passwords**, and high-entropy bearer credentials, in addition to existing providers.
  63. - **Provider-specific findings are deduplicated** against generic assignments (including Anthropic vs. OpenAI `sk-` patterns).
  64. - `dist/`, `build/`, and `vendor/` **are scanned**, because generated or vendored content can be committed and published.
  65. - If Git tracks content in omitted dependency/cache directories (e.g. `node_modules/`), RepoSafe reports **incomplete coverage**, not a clean bill of health.
  66. - Local Git operations ignore host Git config injections, disable filesystem-monitor hooks and automatic lazy fetches, and associate history findings with the introducing commit.
  67. **Coverage is intentionally incomplete:** not every secret syntax or binary format is recognized; entropy detection is conservative. See [detection matrix and false-negative policy](docs/DETECTION.md). A beta scan never certifies that a repository is safe.
  68. ## Install and verify
  69. Requires **Node.js 22+, npm and Git** (Git is needed for history checks). The source is public; clone it directly from GitHub. An npm-compatible tarball and binaries are prepared and tested, but **no package has been published to the npm registry**.
  70. ```bash
  71. git clone https://github.com/VladTepes84/RepoSafe-MCP.git
  72. cd RepoSafe-MCP
  73. npm ci
  74. npm run check
  75. npm run demo
  76. ```
  77. The committed `package-lock.json` pins npm dependencies with integrity hashes; `npm ci` verifies them.
  78. `npm run check` performs TypeScript typecheck, build, unit/security regression tests, an actual stdio MCP handshake with the official client SDK, and the synthetic Git-history scenario. `npm run demo` repeats the scenario independently and prints three expected stages. CI runs the same commands on **Ubuntu, Windows and macOS**. **CI is not a substitute for verifying the GUI client on your machine.**
  79. ### Run the self-check and generate a verified client configuration
  80. After `npm ci && npm run build`, run:
  81. ```bash
  82. node dist/cli.js doctor --root "/absolute/path/to/project"
  83. node dist/cli.js init --root "/absolute/path/to/project" --client cursor
  84. ```
  85. `doctor` actually starts RepoSafe over stdio and discovers six MCP tools. `init` also prints the target client configuration but **does not overwrite** any user files or claim the GUI application itself was tested. The authorized directory must be a specific existing absolute path.
  86. ### Generate a real MCP configuration for your computer
  87. Instead of manually copying placeholders, let RepoSafe print the **actual absolute paths** for your Node executable, compiled server and approved target directory:
  88. ```bash
  89. npm run config -- --client cursor --root "/absolute/path/to/your/project"
  90. ```
  91. Supported `--client`: `cursor`, `claude`, `vscode`, `codex` (TOML). The configuration generator **prints only** and does **not** overwrite your client's configuration. Merge its `reposafe` entry with any existing servers. See the OS-specific guides:
  92. - **[macOS: tested commands and client configuration](docs/INSTALL_MAC.md)**
  93. - **[Windows PowerShell: exact installation and client configuration](docs/INSTALL_WINDOWS.md)**
  94. - **[Current client support and authoritative documentation](docs/CLIENTS.md)**
  95. ### Scan without any AI
  96. ```bash
  97. node dist/cli.js scan --root "/absolute/path/to/your/project"
  98. node dist/cli.js scan --root "/absolute/path/to/your/project" --json
  99. ```
  100. Exit status: **0** = no findings *in the examined scope*, **1** = review required or incomplete coverage, **2** = invalid arguments or scan error. This allows adding RepoSafe to other workflows while keeping the server itself read-only.
  101. ### Actionable CLI and SARIF
  102. ```sh
  103. node dist/cli.js scan --root "/ABSOLUTE/PATH/TO/APP"
  104. node dist/cli.js scan --root "/ABSOLUTE/PATH/TO/APP" --sarif > reposafe.sarif
  105. ```
  106. **Careful:** writing `reposafe.sarif` inside the scanned repository is a user shell action, not a write performed by RepoSafe; for audits prefer a file outside the target repo. SARIF contains finding metadata, not credential values. It can be uploaded to GitHub Code Scanning only when that feature is enabled and the workflow is given the required rights. The repository's example action never uploads automatically.
  107. For a read-only pull-request check, see [GitHub Actions setup](docs/ACTIONS.md).
  108. ## Real proof, not screenshots
  109. ```bash
  110. npm run demo
  111. ```
  112. The demo **actually** (1) initializes a temporary Git repository with no findings; (2) commits a synthetic token and detects it; (3) removes the token from current files but finds it in Git history. It asserts the expected exit statuses and checks that the token never appears in output, then cleans up the disposable repo. See [TESTING](docs/TESTING.md) for the executable tests and honest coverage limits.
  113. ## Security design and boundaries
  114. - Local-only, no authentication secret, no listening port, no telemetry, no runtime network calls.
  115. - Git is invoked **only for read-only local operations** (`rev-parse`, `ls-files`, `check-ignore`, `log`), with `execFile` (not a shell), timeout, bounded output, an isolated global/system Git configuration, disabled fsmonitor/textconv/external diffs and lazy fetches, no fetch, and no checkout.
  116. - The filesystem scope is explicitly approved; root-of-drive scans are refused. Symlinks are skipped; hard-linked files are skipped as incomplete. File and output budgets limit resource use.
  117. - Tools never return matching token values or source snippets; suspected secret-containing filenames are redacted. Errors do not expose absolute paths or file contents.
  118. - Incomplete scans are **not** classified as clean. Repositories with inaccessible Git history or too much data require manual review.
  119. **Limitations are important:** this is *not an OS sandbox*; a malicious local process can race filesystem changes; Git history coverage is bounded (100 recent commits across refs, 4 MiB of patch output), not every blob or dangling object. Detection is heuristic and can miss encoded/binary values and credential formats. Running Git reads repository metadata; use only projects you trust. The AI host may have *other* tools with broader permissions. Do not use RepoSafe as a substitute for manual review and established Git secret scanners.
  120. Read the complete [security model, threat scenarios and safe operations](docs/SECURITY.md), [use cases](docs/USE_CASES.md), [changelog](CHANGELOG.md), and [contributing guidelines](CONTRIBUTING.md).
  121. ## Test scope and disclosure
  122. The automated v0.4 corpus covers at least 30 synthetic positive credential cases and 20 benign examples, alongside baseline, tracked-file and CLI handshake tests. These are fixtures, **not a measured accuracy rate on real-world repositories**. Live tokens are never required.
  123. `npm ci`, `npm run check`, `npm run audit:deps` and the GitHub Actions matrix must all pass for release readiness. GUI apps still require separate verification and must not be marked as validated on that basis.
  124. ## Licensing and costs
  125. MIT License. No database, hosting or paid API is required; Node.js and Git are free. The AI client may have its own plan or usage costs. Running GitHub Actions on private repositories uses the account's applicable minutes quota; verify your plan before large CI usage.
  126. ## Project scope
  127. RepoSafe is **independent of any other private software repository**. The project does not include third-party credentials or reference code from other user projects. Report issues using **synthetic test data only**.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.