Ailooplibrary MCP

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.py

For 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-mcp

Already installed? Download the file again or update your clone and reinstall, then restart the MCP connection. Existing installations do not update themselves.

Tools

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:

1. AI_LOOP_LIBRARY_CATALOG_PATH: an authoritative local JSON file, using either the catalog.json or data/loops.json shape. An invalid explicit path fails.
2. AI_LOOP_LIBRARY_CATALOG_URL, defaulting to https://ailooplibrary.com/catalog.json.
3. Local fallback: catalog.json beside 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 --eval

The 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.