Skip to content
Back to search

foreman-mcp

Least-privilege MCP server for coding agents: sandboxed repo access, named checks, CI, human-approved writes, audit + budgets, and a 62-scenario eval suite.

Safety scan

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

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/willwid3n--foreman-mcp"><img src="/api/listings/willwid3n--foreman-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.

uv venv --python 3.12 .venv && uv pip install --python .venv/Scripts/python.exe -e ".[dev]"
cp foreman.example.toml foreman.toml        # edit repos, checks, limits
.venv/Scripts/python.exe -m foreman check-policy

**Claude Code:** `claude mcp add foreman -- <path>/.venv/Scripts/python.exe -m foreman --policy <path>/foreman.toml serve` (or for a one-off session: `claude -p "..." --mcp-config examples/claude-code.mcp.json --strict-mcp-config`)

**Codex** (`~/.codex/config.toml`):

[mcp_servers.foreman]
command = "C:/path/to/foreman-mcp/.venv/Scripts/python.exe"
args = ["-m", "foreman", "--policy", "C:/path/to/foreman-mcp/foreman.toml", "serve"]

**The human side:**

foreman pending                 # what agents are asking to do
foreman approve 3f9a1c2e        # or: foreman deny 3f9a1c2e --note "not on main"
foreman audit --tail 20         # every call, allowed or refused
foreman report                  # usage across sessions: calls, errors, p50/p95, denials by code

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 · 166 lines
  1. # Foreman
  2. **A least-privilege MCP server that gives coding agents audited, budgeted access to your repositories, tests and CI, with a human approval step for anything that writes.**
  3. Coding agents such as Claude Code, Codex and Hermes are most useful when they can read the code, run the tests and check CI. They are most dangerous when that access is a raw shell. Foreman sits between the two.
  4. - Through MCP the agent gets eleven narrow tools.
  5. - The *policy* decides which repositories exist, which commands count as "the tests", what the agent may never read, and how much it may do in a session.
  6. - Every call lands in an audit log, whether it was allowed or refused.
  7. ```
  8. agent ──MCP/stdio──▶ Foreman ──▶ policy check ──▶ sandboxed path / named command / gh (read-only)
  9. │ │
  10. ├── redaction of every result ◀┘
  11. ├── audit.jsonl + usage telemetry + budgets
  12. └── approvals.json ◀── human: `foreman approve <id>`
  13. ```
  14. ## Tools
  15. | Tool | What it does | MCP annotations |
  16. |---|---|---|
  17. | `list_repos` | Lists the repositories in policy, their approved checks, and whether writes are enabled | read-only |
  18. | `repo_status` | Reports the branch, HEAD, ahead/behind, uncommitted files, local branches and last 5 commits | read-only |
  19. | `list_files` | Lists tracked and untracked (non-ignored) files, with an optional sub-folder or glob | read-only |
  20. | `read_file` | Returns line-numbered text, with an optional line range | read-only |
  21. | `search_code` | Searches with ripgrep, falling back to pure Python. Supports literal or regex queries, a glob filter and a time budget | read-only |
  22. | `run_check` | Runs a **named** check from policy (tests, lint, build) and returns the exit code and the tail of the output | not read-only, idempotent |
  23. | `ci_runs` | Lists recent GitHub Actions runs via `gh` | read-only, open-world |
  24. | `request_action` | Asks for a write: `git_branch` or `github_issue` | not idempotent |
  25. | `action_status` | Reports whether an action is pending, approved, denied or executed | read-only |
  26. | `execute_action` | Runs a human-approved action exactly once | open-world |
  27. | `usage_report` | Reports calls, errors, denials by code, p50/p95 latency, redactions and remaining budget | read-only |
  28. Resource: `foreman://repos/{name}/agents` serves the repo's `AGENTS.md` (or `CLAUDE.md`), so the agent can read the house rules before it touches anything.
  29. ## Security model
  30. 1. **Allow-listed execution, no shell.** A check is a fixed argv list in policy, for example `test = [".venv/Scripts/python.exe", "-m", "pytest", "-q"]`. The agent picks a check *by name*, so `"test; curl evil"` is just an unknown name.
  31. 2. **Path sandbox.** Every path is resolved, symlinks included, and must stay inside the repo root.
  32. - Protected files are refused by name *and* by resolved target: `.env*`, keys and certificates, `.git/`, `.npmrc`, `.pypirc`, `.netrc`, `*.tfstate` and `credentials*`, plus any globs you add.
  33. - Absolute paths, `~` and `..` escapes are refused.
  34. 3. **Redaction everywhere.** Results, the audit log and the approval queue are scrubbed of credential formats:
  35. - private keys
  36. - AWS keys
  37. - GitHub tokens
  38. - Stripe keys and webhook secrets
  39. - Anthropic, OpenAI and Google keys
  40. - Slack tokens
  41. - JWTs
  42. - generic `password=` / `api_key:` assignments
  43. 4. **Clean child processes.**
  44. - Checks run with credential-looking environment variables removed.
  45. - If the client launched Foreman with a stripped environment, a standard non-secret OS baseline (such as `ProgramFiles`) is restored.
  46. - `stdin` is null, so a child process can never read the MCP protocol stream.
  47. 5. **Budgets.**
  48. - Calls and output are limited per session.
  49. - Each check has a timeout.
  50. - Search has a time budget and returns partial results instead of hanging.
  51. 6. **Human-in-the-loop writes.**
  52. - The agent can only *request* a write. A human approves it from the CLI.
  53. - Parameters are SHA-256 digested at request time, so editing the queue after approval is detected (`TAMPERED`).
  54. - An approved action runs only once (`ALREADY_EXECUTED`).
  55. - A read-only policy (`allow_writes = false`) refuses requests outright.
  56. 7. **Stable error codes.** Every refusal starts with a code such as `SECRET_PATH`, `OUTSIDE_REPO`, `UNKNOWN_CHECK`, `NOT_APPROVED` or `BUDGET_EXCEEDED`. The server instructions tell the agent these are final.
  57. ## Evaluation
  58. `evals/run_evals.py` builds a throwaway workspace of fixture repos. The workspace contains:
  59. - planted fake credentials, a `.env` and a private key
  60. - a symlink to the secret
  61. - binary and oversized files
  62. - vendored noise
  63. - a fake `gh`
  64. It then drives the real server **over stdio, the same way an agent connects**. The 62 scenarios fall into six categories: capability, secrets, sandbox, execution, approvals and telemetry. Multi-step flows cover:
  65. - the approval lifecycle, queue tampering and replay
  66. - a read-only policy and call budgets
  67. - scanning the audit log for secrets
  68. - launching Foreman with the MCP SDK's minimal client environment
  69. The fake secrets are assembled at runtime, so no scanner-tripping literal exists in the source.
  70. ```
  71. $ python evals/run_evals.py
  72. ...
  73. approvals 13 passed, 0 failed, 0 skipped
  74. capability 13 passed, 0 failed, 0 skipped
  75. execution 8 passed, 0 failed, 0 skipped
  76. sandbox 11 passed, 0 failed, 0 skipped
  77. secrets 13 passed, 0 failed, 0 skipped
  78. telemetry 4 passed, 0 failed, 0 skipped
  79. 62/62 scenarios passed (100%), 0 skipped, 12.2s on win32
  80. ```
  81. There are also 67 unit tests (`pytest -q`). The CI workflow runs lint, the unit tests and the eval suite on Ubuntu and Windows. Ubuntu exercises the ripgrep engine; Windows exercises the Python fallback and Windows path handling. Each run uploads the JSON scorecard as an artifact, and a guardrail regression fails the build.
  82. ### Bugs the evals and live runs caught during development
  83. | Finding | Fix |
  84. |---|---|
  85. | The pure-Python search fallback followed a symlink to `.env` and returned its contents | Skip symlinks; re-check every hit against its *resolved* target |
  86. | Child processes inherited the server's stdin, which is the JSON-RPC pipe | `stdin=DEVNULL` for every subprocess, plus the `exec.stdin-isolated-from-protocol` eval |
  87. | `dotnet build` failed only when an MCP client launched it, with NuGet reporting `Value cannot be null (path1)`. The cause: clients pass a minimal environment that lacks `ProgramFiles` | Restore a non-secret OS baseline for checks. An eval now launches Foreman with the SDK's default client environment |
  88. | Searching a game repo with ~100k files on disk timed out at 60 s | Stream results under a time budget, return partial results flagged `timed_out`, and add per-repo `exclude` globs. The same search now takes about 2.5 s |
  89. ## Live run against real repositories (19 Nov 2026, Windows 11)
  90. `scripts/live_smoke.py`, over stdio:
  91. | Call | Result |
  92. |---|---|
  93. | `repo_status` on a Godot game repo (13,404 tracked files) | Branch, HEAD, 192 uncommitted files and last commit, in 0.44 s |
  94. | `search_code` on the same repo | 5 hits in 2.5 s with `exclude = ["tmp/**", ...]` |
  95. | `run_check granite-rag test` / `lint` | 22 tests passed; ruff clean |
  96. | `run_check james-brandel build` | The .NET 10 solution built through the stdio server in 4.1 s |
  97. | `ci_runs granite-rag` | The last runs on `main` succeeded |
  98. | `read_file granite-rag .env` | Refused with `SECRET_PATH`; 0 characters returned |
  99. **With a real agent:** a headless Claude Code 2.1.318 session verified the Granite RAG repo end to end. The session used `--strict-mcp-config` and was restricted to `mcp__foreman__*` tools. It:
  100. 1. read the agent rules
  101. 2. reported the branch and HEAD
  102. 3. ran the tests (22 passed) and lint
  103. 4. read the last 2 CI runs
  104. 5. was refused `.env` with `SECRET_PATH`, and did not retry
  105. 6. reported its own usage: 7 tool calls, 1 denial and 293 calls remaining
  106. The audit log shows the same calls plus the resource read.
  107. ## Quick start
  108. ```bash
  109. uv venv --python 3.12 .venv && uv pip install --python .venv/Scripts/python.exe -e ".[dev]"
  110. cp foreman.example.toml foreman.toml # edit repos, checks, limits
  111. .venv/Scripts/python.exe -m foreman check-policy
  112. ```
  113. **Claude Code:** `claude mcp add foreman -- <path>/.venv/Scripts/python.exe -m foreman --policy <path>/foreman.toml serve`
  114. (or for a one-off session: `claude -p "..." --mcp-config examples/claude-code.mcp.json --strict-mcp-config`)
  115. **Codex** (`~/.codex/config.toml`):
  116. ```toml
  117. [mcp_servers.foreman]
  118. command = "C:/path/to/foreman-mcp/.venv/Scripts/python.exe"
  119. args = ["-m", "foreman", "--policy", "C:/path/to/foreman-mcp/foreman.toml", "serve"]
  120. ```
  121. **The human side:**
  122. ```bash
  123. foreman pending # what agents are asking to do
  124. foreman approve 3f9a1c2e # or: foreman deny 3f9a1c2e --note "not on main"
  125. foreman audit --tail 20 # every call, allowed or refused
  126. foreman report # usage across sessions: calls, errors, p50/p95, denials by code
  127. ```
  128. ## Limits (by design, for now)
  129. - Checks run as your user, so the allow-list *is* the control. For untrusted repos, run Foreman inside a container or VM.
  130. - Redaction is pattern-based defence in depth, not a data-loss-prevention guarantee. The real protection is that protected files are never read.
  131. - The approval queue is a local file, so it supports a single host and a single human.
  132. - A timed-out check kills its direct child process. Build servers that detach can outlive it.
  133. ## Development
  134. See `AGENTS.md`. The definition of done is that `ruff check .`, `pytest -q` and `python evals/run_evals.py` all pass.
  135. ## License
  136. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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