flotilla-mcp
This server is Flotilla's Self-Dev MCP server: it lets an agent work on GitHub issues in isolated workspaces, edit code, run tests, and open PRs without merge or deploy authority.
start_issue— clone the repo into a fresh per-issue workspace and create/resume theselfdev/issue-Nbranchread_file— read files from the issue workspace (paths outside it, drive letters, or.gitare refused)write_file— write files in the workspace, checked against protected paths and a per-issue attempt caprun_tests— run the repo's pytest suite inside the workspace with a timeout and return resultssubmit_pr— commit workspace changes, push the branch, open or reuse a PR, then clean up the workspace; never merges or force-pusheslist_assigned_issues— list open issues carrying a given label (defaultself-dev), excluding PRscheck_pr_status— get combined CI status for a PR:pending,success, orfailure
Provides Docker Compose and per-service Dockerfiles to run the fleet, while the Deploy Watcher uses Docker to build, health-check, and blue/green deploy services.
Allows the MCP server to read GitHub issues, open and update pull requests, and check PR status, with changes merged through human review on GitHub.
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., "@flotilla-mcp tackle issue #17: implement fix, run tests, open PR"
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.
Flotilla MCP is a fleet of Model Context Protocol servers that can read GitHub issues, edit its own source, open pull requests, and — once a human merges the change — redeploy itself, without ever being able to take the fleet down or disarm its own safety controls. The parts of the system that could do real damage (the deploy pipeline, the permission layer, the rule that defines what's off-limits) are structurally walled off from the part that writes code, and enforced at more than one independent layer.
This repository is the foundation of that system: the protected-core enforcement engine, the Self-Dev MCP server, and the Deploy Watcher's blue/green deploy and rollback machinery. It is real, tested code, not a prototype — see Status below for exactly what's built and what isn't yet.
Install
Self-Dev MCP only:
pip install flotilla-mcpSelf-Dev MCP plus the Deploy Watcher (needs the Docker SDK):
pip install "flotilla-mcp[watcher]"Or run it without installing anything, via uvx:
uvx flotilla-mcpThis installs three console scripts:
flotilla-mcpandflotilla-self-dev(identical — two names for the same entry point) — the Self-Dev MCP server:flotilla-self-dev --transport stdio|http(defaultstdio;--transport httpserves/healthon port 8080 for container health checks);--versionprints the installed version.flotilla-watcher— the Deploy Watcher. Needspip install "flotilla-mcp[watcher]"; without thedockerpackage installed, it printsflotilla-watcher needs the Docker SDK. Install it with: pip install "flotilla-mcp[watcher]"and exits rather than crashing with an import traceback.
Self-Dev MCP reads its configuration from environment variables (see
.env.example and
flotilla_mcp/self_dev_mcp/config.py).
SELF_DEV_GITHUB_TOKEN is the only variable you have to set — run it from
inside a git checkout with a GitHub origin remote and everything else is
detected:
Variable | Required | Meaning |
| yes | fine-grained token (or bot token): contents, pull requests, and issues read/write on the target repo |
| no (auto-detected) | git remote URL used for the clone/branch/commit/push workflow. When unset, detected by running |
| no (auto-detected) |
|
| no | path to the fleet manifest. When unset, resolved in order: |
| no (default | per-issue write attempt cap |
| no (default |
|
An explicitly set environment variable always wins over auto-detection. If
SELF_DEV_REPO_REMOTE is unset and no origin remote can be detected, the
server exits with a one-line error naming both fixes: run it inside a git
repository with an origin remote, or set SELF_DEV_REPO_REMOTE.
Read SECURITY.md#preconditions-before-pointing-a-live-agent-at-a-repo before pointing this at a repository you care about.
Related MCP server: agentic-sdlc-mcp
Use with an MCP client
Both snippets below point uvx at the flotilla-mcp PyPI package and pass
configuration through environment variables — see
SECURITY.md#preconditions-before-pointing-a-live-agent-at-a-repo
first.
Claude Desktop
Add to your Claude Desktop config (claude_desktop_config.json). The token
is the only variable that's required — as long as the server's working
directory is inside a git checkout with a GitHub origin remote, the repo
remote and owner/repo are auto-detected (see Install above):
{
"mcpServers": {
"flotilla-mcp": {
"command": "uvx",
"args": ["flotilla-mcp"],
"env": {
"SELF_DEV_GITHUB_TOKEN": "<fine-grained token>"
}
}
}
}If your client doesn't run the server with a working directory inside the
target repo (or you want to be explicit), set SELF_DEV_REPO_REMOTE (and
optionally GITHUB_REPO_FULL_NAME, FLEET_MANIFEST_PATH) in env the same
way as before -- an explicit value always overrides auto-detection.
Claude Code
The claude CLI wasn't available in the environment this doc was written
in, so its exact claude mcp add ... -e KEY=VALUE flag syntax couldn't be
verified against a real claude mcp add --help; run that yourself before
scripting the command form. The JSON form above is not client-specific —
paste the same mcpServers block into whatever configuration surface your
claude CLI version reads for MCP servers.
Tools
Self-Dev MCP exposes these 7 tools. Each is documented (description and
per-parameter descriptions) so an MCP client can surface them to the model
without extra context; handlers return a string starting OK, REFUSED:,
EXHAUSTED:, or ERROR: instead of raising, so a caller can branch on the
prefix.
Tool | Summary |
| Clone the target repo into a fresh per-issue workspace and create/resume its |
| Read a file from the issue workspace; paths outside it, with a drive letter, or touching |
| Write a file in the issue workspace; also checked against the fleet manifest's protected paths and a per-issue attempt cap (default 5). |
| Run the repo's own pytest inside the workspace with a timeout and return the exit status and output; commits nothing. |
| Commit everything in the workspace, push the branch, open or reuse a PR, then destroy the workspace; never merges, never force-pushes. |
| List open issues carrying the given label, with pull requests excluded. |
| Get the combined CI state for a PR from the Checks API: |
Why Flotilla MCP
Most "self-modifying agent" demos either can't touch production or can touch too much of it. Flotilla MCP is built around one design principle: the agent reasons, MCP servers provide capabilities, and guardrails sit in between, independent of the agent's own judgment.
The agent (any LLM-backed orchestrator, via the MCP gateway) decides what to build or fix.
MCP servers like Self-Dev MCP expose narrow, auditable primitives — read a file, write a file, run tests, open a PR — not blanket shell access.
Guardrails (the fleet manifest, workspace containment, the attempt cap, GitHub branch protection, credential scoping) sit between the agent's intent and anything irreversible. They work in two layers:
the tool-level checks stop a cooperative agent, one that only edits through
write_file, from touching protected paths or.git/;GitHub branch protection plus a separate bot identity is the real backstop against a hostile (e.g. prompt-injected) agent.
run_testsexecutes code the agent wrote, with the self-dev token, so that code can write protected files into its PR branch or call the GitHub API directly. What stops it from reachingmainis a required CI check and a required human (code-owner) review that the bot identity can't give itself. In either case Self-Dev MCP never holds a Docker socket.
The result is an agent that can fix its own bugs and extend its own fleet, while every change that could take the system down or weaken its own oversight has to pass a human review on GitHub, provided the preconditions are in place.
Key features
Implemented today:
Protected-core enforcement (
flotilla_mcp/common/manifest.py): a fleet manifest defines which services and paths are off-limits. A hardcoded core is protected no matter what the manifest says: the manifest, its loader,flotilla_mcp/__init__.py,requirements.txt,requirements-dev.txt,docker-compose.yml,pyproject.toml,.gitattributes,.gitignore, and the wholeflotilla_mcp/common/and.github/trees. Path checks canonicalize separators,..segments, NTFS aliases and case, and are applied to the symlink-resolved target too.Self-Dev MCP server: a FastMCP server exposing
start_issue,read_file,write_file,run_tests,submit_pr,list_assigned_issues, andcheck_pr_status. Every write is checked against the fleet manifest and confined to an ephemeral, per-issue workspace before it touches disk. Absolute paths, drive letters, UNC paths,..escapes and any.gitpath are refused, and each refusal is audit-logged. Every git call runs with hooks and fsmonitor disabled and pushes with an explicit, non-forcing refspec. A per-issue attempt cap (default 5) stops runaway writes; a refused write never consumes an attempt. These checks bind a cooperative agent; see the safety model for what backs them up.Limited blast radius: the Self-Dev MCP has no Docker socket access, no deploy credentials, and no merge code path. It can open and update PRs. Making them live takes a human review enforced by GitHub branch protection, which is a precondition, not something this code can enforce.
Deploy Watcher — polls
mainfor new commits, builds each non-protected service that has acontainerentry in the manifest from a fresh checkout of that commit, and performs a blue/green deploy: the new container must pass 3 consecutive health checks before it's promoted, and then survives a 30-minute probation window during which a single failed check triggers an automatic rollback to the last proven image. An image is only recorded as known-good after it clears probation, so a rollback can never target a build that hasn't actually been proven to work.Resumable, non-destructive self-dev cycles — re-invoking
start_issuefor an issue that already has an open PR resumes the sameselfdev/issue-Nbranch instead of branching again, so follow-up commits land on the same PR. There is no force-push anywhere in the pipeline.Docker Compose + per-service Dockerfiles —
docker-compose.ymlbrings up the fixture service, Self-Dev MCP, and the Deploy Watcher on a dedicatedmcp-fleetnetwork, each with its own non-root Dockerfile and only the credentials/mounts it actually needs (see Quickstart).Self-Dev MCP HTTP transport:
--transport httpserves Self-Dev MCP over SSE (/sse,/messages/) plusGET /healthon port 8080, which the compose healthcheck probes. Tools run in worker threads, so a longrun_testsnever blocks/health.--transport stdio(the default) is unchanged for local/CLI use. For this release self-dev-mcp is compose-managed (docker compose up --build), not redeployed by the Deploy Watcher.
Roadmap (not built yet — see Status):
MCP gateway and permission manager (the layer that sits between an orchestrating agent and every capability server, including Self-Dev MCP)
model-adapters-mcpandcredentials-manager, and the chat-side "Model Manager" flow for adding support for a new LLM backend on request
How it fits together
flowchart TD
subgraph gh["GitHub (system of record)"]
issue["Issue labeled self-dev"]
pr["Pull Request"]
ci["CI status checks"]
branchprot["Branch protection + CODEOWNERS"]
main["main branch"]
end
subgraph host["Fleet host"]
selfdev["Self-Dev MCP<br/>(git/PR ops only —<br/>no Docker, no deploy creds)"]
watcher["Deploy Watcher<br/>(PROTECTED — Docker socket,<br/>blue/green, rollback)"]
gateway["MCP Gateway +<br/>Permission Manager<br/>(PROTECTED — planned)"]
registry["Service registry +<br/>known-good store"]
end
subgraph fleet["Watcher-deployed containers"]
svc1["fixture-hello-mcp"]
svcN["... other unprotected services<br/>with a container entry"]
end
issue -->|start_issue| selfdev
selfdev -->|read_file / write_file<br/>manifest-checked| selfdev
selfdev -->|run_tests, informational| selfdev
selfdev -->|submit_pr| pr
pr --> ci
ci --> branchprot
branchprot -->|human merge only| main
main -->|poll| watcher
watcher -->|build + health-check +<br/>blue/green swap| fleet
watcher --> registry
gateway -.orchestrates calls to.-> selfdev
gateway -.orchestrates calls to.-> svcNSee ARCHITECTURE.md for the full component breakdown, trust boundaries, and the rollback state machine.
The protected core and the safety model
A small set of things can never be edited by the Self-Dev MCP, no matter what an agent's reasoning concludes it should do:
The fleet manifest (
fleet_manifest.yaml), the manifest loader (flotilla_mcp/common/manifest.py) and everything else inflotilla_mcp/common/, plus the build/dependency files (flotilla_mcp/__init__.py,requirements.txt,requirements-dev.txt,docker-compose.yml,pyproject.toml,.gitattributes,.gitignore) and CI/CODEOWNERS (.github/). These are hardcoded-protected, sowrite_filerefuses them even if the manifest were rewritten to claim they're safe.Git metadata (
.git/): no tool can read or write it, and every git call runs with hooks and fsmonitor disabled and an explicit push refspec.The Deploy Watcher, permission manager (planned), and MCP gateway (planned) services — marked
protected: truein the manifest. These hold real authority (Docker socket access, routing, auth), so they are off-limits at the tool layer and would additionally require CODEOWNERS sign-off at the GitHub layer — the workflow and CODEOWNERS file exist; enforcement requires branch protection, which the repo admin enables — see CONTRIBUTING.md#enabling-branch-protection.
On top of that:
Workspace containment: every
read_file/write_file/run_testscall is resolved against the current issue's ephemeral workspace. Absolute paths, drive letters, UNC paths,..segments, and symlinks or junctions that lead to a protected or outside path are refused before anything touches disk.No merge code path: Self-Dev MCP can open and update a pull request, and nothing in this codebase calls a merge API. The self-dev token could merge through the API, though, so merge-by-a-human-only is enforced by GitHub branch protection and CODEOWNERS. The workflow and CODEOWNERS file exist; the repo admin enables branch protection (see CONTRIBUTING.md#enabling-branch-protection).
No deploy authority in Self-Dev MCP — it holds no Docker socket, no deploy credentials, and never imports
docker. Only the Deploy Watcher — a separate, protected service — can build an image or swap a container.Known-good floor — the Deploy Watcher only records an image as known-good after it survives a full probation window with zero failed checks. Rollback always targets that proven image, never a build that merely passed its first three health checks.
This is defense in depth, not a single check: even a bug in the manifest parser doesn't expose the manifest file or the parser itself, because those paths are hardcoded rather than manifest-driven.
What the tool checks do not stop. They bind a cooperative agent.
run_tests executes code the agent wrote, with the self-dev token. That
code can write any file (protected ones included), which submit_pr's
git add -A then commits to the PR branch, and it can call the GitHub API
directly. The backstop is GitHub branch protection (required test check,
required review, code-owner review, enforce_admins) plus a separate
bot identity for self-dev. With the owner's own PAT, self-dev PRs are
authored by the owner, and a sole owner can't approve their own PR under
enforce_admins. See SECURITY.md.
Quickstart
Run the test suite (works today)
git clone https://github.com/OmPrakashSingh1704/flotilla-mcp.git
cd flotilla-mcp
python -m venv .venv && source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -r requirements-dev.txt
python -m pytest tests -m "not docker" -v -W error::DeprecationWarning -W error::pytest.PytestUnhandledCoroutineWarningrequirements-dev.txt pulls in requirements.txt plus the packaging tools
(build, twine, hatchling, hatch-fancy-pypi-readme) that
tests/test_packaging.py needs to build a wheel as part of the suite.
(-m docker runs the Docker integration test separately; it needs a
reachable Docker daemon.)
This runs the full suite for the protection engine, the Self-Dev MCP tools, and the Deploy Watcher — including the adversarial tests that assert a protected-path write is refused and a probation failure triggers rollback.
Run the fleet locally
Precondition before pointing a live agent at a repo: enable branch protection on
main(requiredtestcheck, required review, code-owner review,enforce_admins) and give self-dev its own bot identity (a machine user or GitHub App), not your own PAT. On a private repo, branch protection needs GitHub Pro, Team or Enterprise. See SECURITY.md. Running the stack with placeholder values to look around is fine.
cp .env.example .env
# edit .env: set SELF_DEV_GITHUB_TOKEN, WATCHER_GITHUB_TOKEN,
# GITHUB_REPO_FULL_NAME, REPO_REMOTE, SELF_DEV_REPO_REMOTE
docker compose up --buildSELF_DEV_GITHUB_TOKEN (fine-grained: contents, pull requests and issues
read/write on this repo) and WATCHER_GITHUB_TOKEN (contents read-only) are
separate tokens. The old shared GITHUB_TOKEN variable is no longer read.
Git authenticates with them through a credential helper, so never put a
token in a remote URL.
This brings up three containers on the mcp-fleet network:
fixture-hello-mcp —
http://localhost:8081/health— a minimal Flask service used as the Deploy Watcher's local smoke-test target.self-dev-mcp —
http://127.0.0.1:8082/health(bound to loopback only, not published to other hosts — see SECURITY.md) — the Self-Dev MCP server over--transport http. Compose-managed: after merging a change to it, update it withdocker compose up --build self-dev-mcp. The Deploy Watcher does not redeploy it.deploy-watcher — no published port; it only talks outbound to GitHub and to the Docker daemon via the mounted
docker.sock.
With placeholder .env values (or real ones that just don't resolve),
fixture-hello-mcp and self-dev-mcp still start and their /health
checks still pass — GitHub credentials are only resolved lazily, on the
first tool call that actually needs them. Any Self-Dev MCP tool that talks
to GitHub (list_assigned_issues, submit_pr, check_pr_status, ...) will
return an "ERROR: ..." string until SELF_DEV_GITHUB_TOKEN and
GITHUB_REPO_FULL_NAME are set to real values.
Repo layout
flotilla_mcp/
common/manifest.py fleet manifest loader + protected-path engine
self_dev_mcp/ Self-Dev MCP: git ops, workspace, tools, server,
Dockerfile
deploy_watcher/ Deploy Watcher: checkout, build, health, blue/green,
rollback, service registry, known-good store,
Dockerfile, entrypoint.sh
fixture_hello_mcp/ fixture Flask service + Dockerfile, used as the
Deploy Watcher's local smoke-test target
tests/ unit tests, mirroring the flotilla_mcp/ layout
docs/design/ design documents (historical / planned; code and
ARCHITECTURE.md are authoritative)
fleet_manifest.yaml the fleet manifest (protected)
docker-compose.yml local fleet: mcp-fleet network + all three services (protected)
.env.example template for the .env docker-compose reads secrets fromStatus / Roadmap
Component | Status |
Fleet manifest + protected-path engine | Built |
Self-Dev MCP (7 tools, workspace containment, attempt cap) | Built |
Deploy Watcher (blue/green, probation, rollback, known-good floor) | Built |
Docker Compose + per-service Dockerfiles | Built |
Self-Dev MCP HTTP transport ( | Built |
CI workflow + CODEOWNERS | Built (CODEOWNERS names a real owner, |
MCP gateway | Planned |
Permission manager | Planned |
| Planned |
| Planned |
Model Manager chat flow | Planned |
Nothing in this table is aspirational marketing — if it says "Built," it has passing tests in this repository today. If it says "Planned" or "In progress," there is no working code for it yet.
The one thing "Built" doesn't cover automatically: a real run against your own GitHub repo (a live PR, CI, and merge). See docs/acceptance-checklist.md for that manual verification pass.
Documentation
ARCHITECTURE.md — components, trust boundaries, the self-dev cycle, and the rollback state machine
SECURITY.md — threat model, how to report a vulnerability, and known limitations
CONTRIBUTING.md — dev setup, PR flow, and how to add a new fleet service
GOVERNANCE.md — maintainers and decision-making
SUPPORT.md — where to ask for help
RELEASING.md — how a
flotilla-mcprelease is cut and published to PyPI
License
Available Tools
7 toolscheck_pr_statusA
Get the combined CI status for a pull request's head commit, from GitHub's Checks API. Returns exactly one of "pending" (no checks yet, or some still running), "success" (all checks completed without failure), or "failure" (at least one check reported a non-success conclusion: failed, cancelled, timed out, required action, or failed to start) -- or a string starting "ERROR:" if the status can't be retrieved (never raises).
Inputs: pr_number (required).
list_assigned_issuesA
List open GitHub issues carrying the given label; pull requests are excluded even though GitHub's issues API would otherwise include them. Use this to discover work before calling start_issue. Returns one "# " line per matching issue, a "No open issues labeled " message if none match, or a string starting "ERROR:" on failure -- never raises.
Inputs: label.
read_fileA
Read a file's contents from the workspace start_issue created for this
issue. relative_path is resolved relative to that workspace and is
refused if it is absolute, has a drive letter, is a UNC path, escapes
the workspace via '..', or touches '.git'. Returns the file contents as
a plain string on success, "REFUSED: ..." if the path is blocked, or
"ERROR: ..." for other failures (e.g. no active workspace, file not
found) -- never raises.
Inputs: issue_number (required), relative_path (required).
run_testsA
Run the target repository's own pytest suite for one service, inside the issue's workspace, subject to a timeout. This only executes tests and reports the result -- it never commits or modifies anything. Returns a string starting "OK" or "FAILED" followed by the exit code and captured stdout/stderr, "REFUSED: ..." if the path is option-like, escapes the workspace, or touches '.git', or "ERROR: ..." if the run times out or fails to start -- never raises.
Inputs: issue_number (required), service_relative_path (required).
start_issueA
Begin work on a GitHub issue: clone the target repository into a fresh,
isolated per-issue workspace and create (or, if one already exists,
resume) a selfdev/issue-<issue_number> branch there. Call this first,
before read_file, write_file, run_tests, or submit_pr -- those tools all
operate on the workspace this creates. Only one active workspace is
allowed per issue; calling this again for an issue that already has one
returns an error instead of clobbering it. Returns the branch name as a
plain string on success, or a string starting "ERROR:" on failure
(never raises).
Inputs: issue_number (required).
submit_prA
Finish work on an issue: commit everything currently in the workspace,
push the selfdev/issue-<issue_number> branch, and open a new pull
request or reuse an already-open one for that branch -- then destroy
the workspace. It can never merge a pull request and never
force-pushes. Requires a GitHub repository to be configured. Returns
"opened PR #" on success, or a string starting "ERROR:" on
failure (the workspace is kept on failure so a retry doesn't need
start_issue again) -- never raises.
Inputs: body (required), title (required), issue_number (required).
write_fileA
Create or overwrite a file inside the workspace start_issue created for
this issue. relative_path is checked the same way as read_file
(no absolute/drive/UNC/'..'/'.git' paths) and is additionally checked
against the fleet manifest's protected paths. Writes are capped per
issue (default 5 attempts, configurable via SELF_DEV_MAX_ATTEMPTS); a
refused write does not count against that cap. Returns "OK" on success,
"REFUSED: ..." for a blocked path, "EXHAUSTED: ..." once the attempt
cap is reached, or "ERROR: ..." for other failures -- never raises.
Inputs: content (required), issue_number (required), relative_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool owns a distinct stage of the issue-to-PR workflow: discovery, workspace setup, file read/write, test execution, PR submission, and CI status. There is no meaningful overlap between read_file and write_file or between run_tests and check_pr_status.
All seven tools follow a consistent snake_case verb_noun pattern: start_issue, read_file, write_file, run_tests, list_assigned_issues, submit_pr, check_pr_status. The naming is predictable and immediately signals what each tool does.
Seven tools is well-scoped for the server's stated purpose of working through GitHub issues from discovery to PR submission. Each tool earns its place and there are no redundant or filler entries.
The core workflow is covered: discover issues, start an isolated workspace, edit files, run tests, submit a PR, and check CI status. However, there is no way to read issue bodies/comments or list the workspace directory structure, which leaves notable gaps for agents that need to understand requirements or navigate an unfamiliar repository. There is also no explicit abort/discard tool for abandoning work.
Maintenance
Related MCP Connectors
Autonomous AI developers on your own infrastructure: assign a task, get a pull request.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Security reviews for coding agents: diffs checked against your org policy and live infrastructure.
Related MCP Servers
- AlicenseCqualityDmaintenanceAn autonomous agent that automates GitHub contributions end-to-end, from issue analysis and code changes to pull requests, conflict resolution, and review updates.172Apache 2.0
- AlicenseAqualityBmaintenanceEnables AI coding agents to orchestrate the full software development lifecycle on GitHub, including planning, issue creation, code review, security triage, and release readiness checks.1399 npm1MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to automate GitHub repository management, issue tracking, and commits using natural language.-
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to safely inspect, edit, and test code within a bounded repository environment to solve software engineering tasks and verify fixes.-