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.

Related MCP server: AI Knowledge Center MCP

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:

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.