@n50/alef-mcp

MCP server that exposes the ALEF Pattern Catalog as built-in tools for Claude, Cursor, or any MCP-compatible client.

The catalog is a public, CC-BY-4.0 corpus of named failure modes in agentic AI systems — 36+ patterns and 8 core architectural doctrines, each with an observable signature, fix archetypes, and falsification clock.

Install

npm install -g @n50/alef-mcp

Or use directly via npx (no install needed):

npx @n50/alef-mcp

Configure your MCP client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "alef": {
      "command": "npx",
      "args": ["-y", "@n50/alef-mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "alef": { "command": "npx", "args": ["-y", "@n50/alef-mcp"] }
  }
}

Claude Code CLI

claude mcp add alef --command "npx" --args "-y" "@n50/alef-mcp"

Tools exposed

After installing + restarting your MCP client, Claude/Cursor will have these tools available:

lookup_pattern(query)

Look up a single failure-mode pattern by @id (e.g. ALEF-PAT-039) or slug (e.g. safety-mechanism-without-unlock-criteria). Returns the full entry: observable signature, instances, fix archetypes, severity, confidence.

scan_code_for_patterns(code, window_lines?)

Scan a code snippet against all 36+ patterns. Returns patterns whose observable signature regex matches the code. Use when reviewing a PR or auditing for known agentic-AI failure modes.

cite_doctrine(query)

Retrieve one of the 8 core architectural doctrines (DOC-001 through DOC-008). Use to explain the structural principle behind a recommendation.

list_patterns()

List all patterns with @id, slug, one_liner, severity. Use to orient yourself to what's available.

Example session

User: I'm worried my agent has a permission-bypass bug. Can you check?

Claude (using scan_code_for_patterns): Found 1 matching pattern — ALEF-PAT-039: safety-mechanism-without-unlock-criteria. The pattern's observable_signature regex matched your file at the state_observer_no_auto_post hardcoded gate. Severity 6. The fix archetype retirement_clock_on_install is the immediate remediation — every safety mechanism ships with installed_at + retire_by metadata.

Environment variables

| Variable | Default | Purpose | |---|---|---| | ALEF_CATALOG_URL | https://n50.io/api/patterns | Override the catalog source (e.g. for self-hosting) |

How the catalog stays current

The catalog at https://n50.io/api/patterns is updated continuously by the ALEF autonomous research engine as new patterns are surfaced from real-world agentic-AI incidents. This MCP server fetches the latest version on startup (with 10-min in-memory cache).

To see the catalog directly in a browser: n50.io/patterns

To support the catalog's continued development: github.com/sponsors/Ilya0527

License

MIT