The AI Loop Library MCP server (ailooplibrary-mcp) version 2.1.0 is a read-only, local MCP server for the AI Loop Library and its 68 bounded work loops. The agent calling this server selects a loop based on its own knowledge of the operator's project; the server provides searchable specifications, runnable protocols, and design checks.
Purpose and form: The server is a single Python file and at runtime depends only on the Python 3.9+ standard library. It contains no write tools, credentials, or model calls, and requires no ops-hosted server. The single file can be downloaded for use with Cursor or other stdio clients; the standalone repository contains the same server. After installation, run it from the repository root, or from the mcp/ directory of the site repository. For installed copies, you must re-download the file or update the clone and reinstall, then restart the MCP connection; existing installations do not update themselves.
Core capabilities: Session protocols obey round and minute limits; scheduled-tick protocols use an experiment log, per-run/total spend guidance, and stop after two consecutive runs with no progress. max_rounds and max_minutes apply only to session protocols. Strict posture requires explicit approval for shared-surface actions, including in copied prompts. The lint tool can identify explicit gate language and flags common negating phrasings such as "without human approval" or "approval is optional." Missing key validation, stop, budget, or approval checks prevent a positive overall score. Text matching cannot establish safety or grant permission, regardless of score. Resources include ailooplibrary://catalog and ailooplibrary://loop/{id}. All tools declare readOnlyHint and idempotentHint.
Catalog loading and failure handling: Resolution order is: AI_LOOP_LIBRARY_CATALOG_PATH (authoritative local JSON file, using the catalog.json or data/loops.json structure; an invalid explicit path will fail); AI_LOOP_LIBRARY_CATALOG_URL (defaultpath will fail); AI_LOOP_LIBRARY_CATALOG_URL (default https://ailooplibrary.com/catalog.json）；本地回退：服务器旁的 catalog.json, then ../catalog.json, then ../data/loops.json. The server caches the validated catalog in memory for five minutes. Remote fetches have a 10-second timeout and a 4 MiB response limit. Validation and search indexing complete before replacing the snapshot.
If both refresh and local fallback fail, the server keeps the last validated snapshot and waits 60 seconds before retrying. Tool responses include a stale catalog warning, plus _meta["ai-loop-library/catalog"] (containing source, age, and stale status); catalog_stats also includes catalog_status. The cache is process-local and is not retained after restart. Changing the configured source invalidates the old snapshot. On initial failure with no valid local catalog, an error is returned, never sample data. The two embedded loop samples are retained only for offline testing.
Client compatibility: supported protocol versions are 2024-11-05, 2025-03-26, 2025-06-18. The transport is 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 parameters and tool arguments must be objects when provided; 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 an intentional tightening since 2.0.0.
For 2025-06-18, the six tools that return JSON declare output schemas and return structuredContent alongside the same JSON text. Earlier versions retain the text-only convention. Browse, design, and render tools continue to return Markdown.
Ranking and testing: ranking uses IDF-weighted keyword overlap, light stemming, synonyms, and category hints. It is a browsing aid, not model judgment or a constraint solver.
Validation and development: run from the directory containing server.py. There are no third-party runtime dependencies. The optional test dependency jsonschema independently validates the declared schemas and real tool results. The 43 offline self-checks and 20 golden ranking queries are separate from the regression suite; the regression suite covers request recovery, argument validation, older client compatibility, protocol fidelity, lint negation, domain routing, and cache failures. CI runs these gates on Python 3.9 and 3.13.
Release invariants: the site and the standalone repository must publish the same 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 and does not prove that a PyPI or registry release has occurred.
