Ailooplibrary MCP

What paultaki/ailooplibrary-mcp MCP server does

The paultaki/ailooplibrary-mcp MCP server gives an MCP client read-only access to the AI Loop Library and its catalog of 68 bounded work loops. It supplies searchable loop specifications, canonical links, verifier classifications, loop kinds, and runnable protocol text. The calling agent remains responsible for applying its knowledge of the project and choosing the most suitable loop.

This is a local Python server rather than a hosted API. It runs as a single file on Python 3.9 or newer and uses only the standard library at runtime. It does not provide write tools, credentials, or model calls.

How it works

The server communicates through newline-delimited JSON-RPC 2.0 over stdio and supports protocol revisions 2024-11-05, 2025-03-26, and 2025-06-18. With the newest supported revision, six JSON-returning tools also advertise output schemas and provide structured content alongside the same JSON text. Diagnostics are written to stderr, while malformed requests and invalid arguments produce protocol errors without stopping the process.

Catalog data is loaded from an explicit local file when configured, then from a configured URL, and finally from nearby catalog files. The validated catalog is cached in memory for five minutes. Remote requests have a ten-second timeout and a 4 MiB response limit. If refresh fails, the server can continue using its last validated snapshot and reports source, age, and stale status in responses.

Setup and configuration

To install the paultaki/ailooplibrary-mcp MCP server, download server.py, run its self-test, and register the file as a stdio command in an MCP client. A repository checkout can also be installed in editable mode and launched through the ai-loop-library-mcp command. Cursor configuration uses a command of python3 and an absolute path in args; Claude can register the same Python command through its MCP command setup.

AI_LOOP_LIBRARY_CATALOG_PATH selects an authoritative local JSON catalog. AI_LOOP_LIBRARY_CATALOG_URL selects the remote catalog source and otherwise defaults to the AI Loop Library catalog URL. Neither setting is required for a normal installation. An invalid explicit path fails rather than silently falling back. The process does not update installed files automatically, so changes require downloading or updating the checkout and restarting the MCP connection.

Tools and capabilities

Available tools include:

• browse_catalog for a compact catalog digest.
• search_loops for ranked matches with match explanations.
• get_loop for a complete loop specification and metadata.
• pick_loop_for_goal for a lexical shortlist and confidence signal.
• render_run_protocol for Markdown instructions and a reusable prompt.
• critique_loop for text-based checks and related-loop suggestions.
• design_loop for a new scaffold with a suggested verifier and TODOs.
• list_categories and catalog_stats for category and catalog information.

Rendered protocols can include round and time limits, budgets, stop conditions, experiment-log guidance, and approval requirements. Session limits apply only to session protocols. Scheduled-tick protocols include per-tick and total-spend guidance plus a two-tick no-progress stop. Ranking uses keyword overlap, light stemming, synonyms, and category hints; it is a browsing aid, not a constraint solver or model judgment.

Resources are available at ailooplibrary://catalog and ailooplibrary://loop/{id}. Tools declare read-only and idempotent hints.

Limitations and notes

The paultaki/ailooplibrary-mcp MCP server does not establish that a proposed loop is safe or grant permission to act. Its linter checks text for verification, stop, budget, and approval language, including some negated approval phrases, but text matching cannot prove safety. Missing critical checks can prevent a positive overall grade.

A first startup during an outage requires a valid local catalog; it returns an error instead of sample data. The embedded two-loop sample is reserved for offline tests. The in-memory cache is process-local and disappears when the server restarts. Individual tool fields can be nullable as declared, but request params and tool arguments must be objects when supplied; explicit null is rejected.