AI Loop Library MCP
Read-only MCP server that lets your agent find, run, and design bounded verifiable work loops from the AI Loop Library (68 loops) — no writes, no credentials, no third-party runtime deps.
Survey the library —
browse_catalogreturns the whole catalog as a ~2k-token digest (id, category, use_when, verifier strength);list_categoriesandcatalog_statsgive counts, featured loops, and load source.Find loops —
search_loopsranks matches by keyword/job-to-be-done with why-matched explanations;pick_loop_for_goalreturns a 5-candidate shortlist with a confidence signal (you make the final call).Inspect a loop —
get_loopfetches the full spec: objective, trigger, allowed actions, verification, stop condition, budget, approval boundary, copyable prompt, canonical URL.Run a loop —
render_run_protocolproduces an executable markdown protocol with one-change-per-round discipline, durable state skeleton, stop conditions, budgets, risk-colored approvals, and a paste-ready prompt; session loops getmax_rounds/max_minutes, scheduled-tick loops get experiment logs and no-progress stops.Lint and create loops —
critique_loopscores any loop design 0–10 against the anti-pattern rubric with per-check fixes;design_loopscaffolds a new spec with a domain verifier and TODOs.Browse resources —
ailooplibrary://catalogandailooplibrary://loop/{id}.Operate offline/degraded — loads from a local JSON path, remote URL, or bundled fallback; caches for 5 min, warns and retains the last good snapshot on outages, and never serves sample data as real.
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., "@AI Loop Library MCP pick a loop for refactoring"
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.
AI Loop Library MCP server
Version 2.1.0. A read-only, local MCP server for the AI Loop Library and its 68 bounded work loops. The calling agent uses its knowledge of the operator's project to choose a loop; the server supplies searchable specs, runnable protocols, and design checks.
One Python file, Python 3.9+, standard library only at runtime. No write tools, credentials, model calls, or hosted server to operate.
Install
Download the single file:
mkdir -p ~/.ai-loop-library
curl -fsSL https://ailooplibrary.com/mcp/server.py -o ~/.ai-loop-library/server.py
python3 ~/.ai-loop-library/server.py --self-test
claude mcp add ai-loop-library -- python3 ~/.ai-loop-library/server.pyFor Cursor or another stdio client:
{
"mcpServers": {
"ai-loop-library": {
"command": "python3",
"args": ["/absolute/path/to/server.py"]
}
}
}The standalone repository
contains the same server. Run the following from its root, or from mcp/ in
the site repository:
python3 server.py --self-test
python3 server.py --eval
pip install -e .
claude mcp add ai-loop-library -- ai-loop-library-mcpAlready installed? Download the file again or update your clone and reinstall, then restart the MCP connection. Existing installations do not update themselves.
Related MCP server: nc-tools-mcp
Tools
Tool | Result |
| Compact catalog digest for the calling agent to judge |
| Ranked matches with why-matched explanations |
| Full spec, canonical URL, verifier classification, loop kind |
| Lexical shortlist and confidence signal; the calling agent chooses |
| Markdown protocol and copyable prompt sharing the same stop conditions and approval boundaries |
| Text-based lint, per-check findings, critical missing checks, and related loops |
| New loop scaffold with a suggested domain verifier and explicit TODOs |
| Category counts and library links |
| Counts, catalog source, update metadata, and cache status |
Session protocols honor round and minute caps. Scheduled-tick protocols use
experiment logs, per-tick/total spend guidance, and a two-tick no-progress stop.
max_rounds and max_minutes apply only to session protocols. Strict posture
requires explicit approval for shared-surface actions, including in copied prompts.
The linter recognizes explicit gate language and flags common negations such as "without human approval" or "approval is optional". Critical missing verification, stop, budget, or approval checks prevent a positive overall grade. Text matching cannot establish safety or grant permission, regardless of the numeric score.
Resources: ailooplibrary://catalog and ailooplibrary://loop/{id}.
All tools declare readOnlyHint and idempotentHint.
Catalog loading and outages
Resolution order:
AI_LOOP_LIBRARY_CATALOG_PATH: an authoritative local JSON file, using either thecatalog.jsonordata/loops.jsonshape. An invalid explicit path fails.AI_LOOP_LIBRARY_CATALOG_URL, defaulting tohttps://ailooplibrary.com/catalog.json.Local fallback:
catalog.jsonbeside the server, then../catalog.json, then../data/loops.json.
The server caches a validated catalog in memory for five minutes. Remote fetches have a ten-second timeout and a 4 MiB response limit. Validation and search indexing finish before a new snapshot replaces the current one.
If refresh and local fallback fail, the server retains its last validated snapshot
and waits 60 seconds before retrying. Tool responses include a stale-catalog warning
and _meta["ai-loop-library/catalog"] with source, age, and stale status;
catalog_stats also includes catalog_status. The cache is process-local and does
not survive restart. Changing the configured source invalidates the old snapshot.
An initial outage without a valid local catalog returns an error, never sample data.
The two-loop embedded sample is reserved for offline tests.
Client compatibility
Supported protocol revisions: 2024-11-05, 2025-03-26, 2025-06-18.
Transport: newline-delimited JSON-RPC 2.0 over stdio. Diagnostics go to stderr.
Malformed requests and invalid tool arguments return protocol errors without
terminating the server. Execution failures return isError: true.
Request params and tool arguments must be objects when supplied; omit them for
no-argument calls. Explicit null for these objects is intentionally rejected,
including for older clients. Nullable individual fields remain supported as declared
in each input schema. This validation is a deliberate tightening from 2.0.0.
With 2025-06-18, the six JSON-returning tools advertise output schemas and return
structuredContent alongside identical JSON text. Earlier revisions retain the
text-only contract. Browse, design, and render tools continue to return Markdown.
Ranking uses IDF-weighted keyword overlap, light stemming, synonyms, and category hints. It is a browsing aid, not a model judgment or constraint solver.
Verification and development
From the directory containing server.py:
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
python -m unittest -v test_server
python server.py --self-test
python server.py --evalThe runtime has no third-party dependencies. The optional test dependency,
jsonschema, independently validates advertised schemas and real tool results.
The 43 offline self-checks and 20 golden ranking queries remain separate from the
regression suite, which covers request recovery, argument validation, old-client
compatibility, protocol fidelity, lint negation, domain routing, and cache outages.
CI runs these gates on Python 3.9 and 3.13.
Release invariant: the site and standalone repositories must ship identical
server.py, README.md, pyproject.toml, and test_server.py files. Version metadata
must match SERVER_VERSION; the standalone server.json is a registry submission
manifest, not proof that a PyPI or registry publication has occurred.
Available Tools
9 toolsbrowse_catalogARead-onlyIdempotent
The entire AI Loop Library as a compact digest (~2k tokens): every loop's id, category, one-line use_when, and verifier strength. This is the highest-signal single call here — you know the operator's repo, data, and recurring pain, so scan the digest against that context and make the pick yourself. Follow with get_loop for depth or render_run_protocol to run one.
Inputs: category.
catalog_statsARead-onlyIdempotent
Catalog overview: loop count, categories, featured loops, last_updated, and where the catalog was loaded from.
Inputs: no named parameters. Returns: loop_count, catalog_source, catalog_status, category_count
critique_loopARead-onlyIdempotent
Lint any loop design — the operator's own, or one you drafted — against the AI Loop Library anti-pattern rubric: verifier present and objective, stop condition, budget, one-change-per-round, durable state, same-check-every-round, micro-metric objective (MVL), human gates on risky surfaces, defined trigger. Returns a 0–10 score, per-check fixes, and related catalog loops. Deterministic text lint, not a model — 'missing' means 'not stated'.
Inputs: loop_description (required). Returns: grade, score, findings, critical_missing
design_loopARead-onlyIdempotent
Scaffold a NEW loop spec from a stated bottleneck when no catalog loop fits: returns a draft with every required field (trigger, scope, one-round action, suggested verifier for the domain, state files, stop conditions, budget, risk colors), an MVL sanity check on the objective, and the nearest existing loops to steal structure from. Follow with critique_loop on the completed draft.
Inputs: goal (required), cadence, context, constraints.
get_loopARead-onlyIdempotent
Fetch one loop's full spec by id or slug: objective, trigger, allowed actions, verification (+ verifier strength), stop condition, budget, approval boundary, copyable prompt, and canonical URL. Use after browse_catalog or search_loops.
Inputs: id_or_slug (required). Returns: id, url, title, summary, +1 more
list_categoriesBRead-onlyIdempotent
List loop categories with live counts and library filter URLs.
Inputs: no named parameters. Returns: categories
pick_loop_for_goalARead-onlyIdempotent
Shortlist the best-matching loops for a stated goal (lexical ranking with an honest confidence signal) — you make the final call. Returns 5 candidates with use_when, verification, and why-matched so you can judge against operator context the server can't see. When confidence is low, trust your own read of browse_catalog over this ranking. Follow with render_run_protocol for the executable version.
Inputs: goal (required), limit, constraints. Returns: goal, shortlist, confidence
render_run_protocolARead-onlyIdempotent
Render a loop as an executable markdown run protocol an agent can follow directly: objective/done contract, allowed actions, one-change-per-round rule, the same verification every round, a durable state-file skeleton, stop conditions, budget, risk-colored approval boundary, proof format, and a paste-ready Claude Code prompt. Session loops get bounded rounds; scheduled-tick business loops (SEO, ads, product metrics) get experiment logs, undo-losers discipline, and notify-the-human ticks.
Inputs: id_or_slug (required), goal, kind, max_rounds, +2 more.
search_loopsARead-onlyIdempotent
Search AI Loop Library's bounded, verifiable work loops by job-to-be-done, keyword, or category. Each loop ships with a trigger, one-change-per-round discipline, a verification check, a stop condition, a budget, and a human approval boundary — so an agent can run it without thrashing. Returns ranked matches with a one-line why-matched.
Inputs: query (required), limit, category. Returns: results
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have distinct roles (get_loop vs render_run_protocol, critique_loop vs design_loop). However, browse_catalog, search_loops, and pick_loop_for_goal all help discover loops, and their boundaries—especially between search and pick—require reading descriptions to avoid misselection.
Most names follow a clear verb_noun snake_case pattern (browse_catalog, search_loops, get_loop, critique_loop, design_loop, list_categories). Minor deviation: catalog_stats is a noun phrase rather than verb-led, inconsistent with the rest.
Nine tools are well-scoped for a library browse/curate/design server. Each tool earns its place across discovery, inspection, rendering, critique, design, and metadata.
The surface covers discovery (browse/search/pick), depth (get_loop), execution (render_run_protocol), quality (critique_loop), creation (design_loop), and metadata (list_categories/catalog_stats). A gap remains for updating or managing existing loop entries, but that may be out of scope.
Maintenance
Related MCP Connectors
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
Atomadic MCP: 68 deterministic tools for agent identity, escrow, SLA, EU AI Act compliance.
AI-native programming language and toolchain for accountable, verifiable agent-driven development.
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables multi-model leader-worker agent orchestration, workflow execution, and deterministic validation via structured MCP tools.8 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to perform file, search, patch, git, process, test, package, network, and system operations through 60 typed MCP tools with structured inputs/outputs, structured errors, and a full event journal, replacing terminal use with a typed machine API.MIT
- AlicenseNot gradedqualityCmaintenanceProvides coding agents with structured planning, persistent project memory, automated verification, and safety permission controls through MCP tools, enabling better planning, context retention, self-checking, and guarded execution.1 npmMIT
- AlicenseAqualityBmaintenanceEnables coding agents to make offline, zero-cost decisions using schema-safe Choice/Score/Noul primitives, a confidence gatekeeper, planning, adversarial red-teaming, research, and RLVR-based self-improvement via 21 MCP tools.247MIT