<!-- Last modified: 2026-08-09T17:35:00.000Z -->

# loop-improver-mcp

MCP server for modernizing agent guidance across repositories.

`loop-improver-mcp` inspects a repository, establishes its product mission in `.github/objectives.md`, and activates a managed Copilot team that continues into useful product work.

It handles repos that already have mature `.github` files and repos that have no `.github` folder at all. The MCP call owns the architecture pass; generated agents are only for recurring domain work that needs a dedicated instruction surface.

## Tools

- `compare_loops` inspects README, `.github/copilot-instructions.md`, `.github/objectives.md`, specialist agents, insights, and inferred repo profile.
- `improve_loop` creates missing `.github` structure and installs a coordinator-worker loop. A `loop-director` routes bounded research to folder experts, a file-practices specialist, and a repository-cleanup expert. Folder and cleanup experts first propose a bounded edit, then implement only after the director approves the paths, actions, and checks. It also refreshes objectives, profile-specific implementation guidance, and current insight files while preserving durable user-authored instructions and agents. Its response always includes a required `continuation` plan that tells the calling agent to dispatch `loop-director` and continue into repository work.
- `record_loop_insight` overwrites the current architecture learning in `.github/insights/loop-improver-mcp.md`.

`improve_loop` also installs a `/goal` prompt. Run it with a specific outcome or with no argument for a general improvement pass. The director uses the canonical product mission, gathers bounded evidence, and completes safe local work autonomously. It asks only when destructive, external, publishing, secret-handling, materially ambiguous, or substantially expanded work needs a decision.

Every tool response includes `serverInfo.version` and `serverInfo.sourcePath` so clients can identify stale installations or confirm that a workspace checkout is loaded.

`improve_loop` also returns a `report` with a short outcome summary, one row per added, updated, or pruned managed file, the reason pruning was limited, Mermaid source for the installed agent flow, and a recommended presentation format. The separate `continuation` object sets `workflowComplete` to `false`, sets `dispatchNow` to `true`, names the director and available experts, and leads with the canonical `productMission`, its source, a product-first priority policy, the next prompt, risk policy, and completion criteria. An empty `changed` list means the architecture is ready. It does not mean the repository improvement pass is complete.

## Repository Benefits

- Predictable expertise: every repository gets the same director and `.github`, `src`, and `tests` experts, with optional profile guidance for its technology.
- Better decisions: experts connect recommendations to controlling code, tests, user outcomes, and repository evidence before changes begin.
- Product-first autonomy: the director completes safe local improvements and interrupts only for material risk or ambiguity.
- Smaller codebases: cleanup is part of the normal loop, so dead code, duplication, generated output, stale guidance, and failed approaches become routine review targets.
- Durable improvement: objectives and current insights preserve what worked, what was removed, and what the next pass should examine.

## Outcome Rubric

The server evaluates canonical files against a desired shape:

- `README.md`: names the repo, audience, capabilities, and durable entry points without becoming an operational runbook.
- `.github/copilot-instructions.md`: holds durable rules, validation expectations, safety boundaries, and canonical file ownership.
- `.github/objectives.md`: owns the canonical product mission, names repo-specific outcomes, maps active loops to those outcomes, and defines evidence for improvement.
- Last modified hygiene: surfaces text files missing a `Last modified` timestamp and files whose timestamp is older than 30 days by default, then suggests objective and folder focus for the next session.
- `.github/agents/`: contains specialist guidance only for recurring domain work.
- `.github/insights/`: records one current insight per MCP or specialist surface with verified improvements, prune candidates, reusable learnings, and self-improvement notes.

Generated specialists also audit changed and nearby symbols for duplicate helpers and unused code. In this repository, Ruff enforces source orientation and code-quality rules, the readability test checks every production module and symbol for concise descriptions, and Vulture reports high-confidence dead-code candidates for reference verification.

## Usage Shape

Call `compare_loops` against older repos, then call `improve_loop` on repos missing the foundation or carrying stale guidance. Managed files are marked with `<!-- Managed by loop-improver-mcp -->` so later refreshes can update the loop without overwriting unrelated repo guidance.

Call `improve_loop` with its default refresh behavior. The calling Copilot agent should dispatch the generated `loop-director` immediately from the returned `continuation` plan and should not ask the user to choose preserve or overwrite mode unless the user explicitly requested preservation. In clients that cannot dispatch custom agents from an MCP response, select `loop-director` and run `/goal` as the compatibility path.

The director uses VS Code's coordinator-worker subagent pattern: folder and file specialists return independent evidence and a bounded edit plan, the director ties that evidence to controlling functions and tests, and the owning expert implements the approved scope. Every repository receives the same `.github`, `src`, and `tests` folder experts. When a standard folder is absent, its expert reports whether the repository needs that scope instead of creating the folder. Existing domain agents join the director's allowlist, while profile-specific fallback guidance is created only when the repository has no matching specialist.

The generated specialist guidance adapts to portable repository signals such as Python, Rust, TypeScript, content, documentation, or infrastructure files. Domain-specific context comes from the target repository's objectives and existing guidance, so the server can create useful loops without carrying assumptions from another project or machine.

## Use With GitHub Copilot

Paste this into GitHub Copilot Chat after opening the repository:

```text
Install and configure this repository's loop-improver MCP server for my VS Code GitHub Copilot environment. Follow .github/mcp-install.md, verify that the server starts, and keep the configuration portable for future updates.
```