saferagenticai-mcp 0.3.0

MCP server exposing the SaferAgenticAI safety framework (canonical criteria + Implementation Patterns layer) to coding assistants.

SaferAgenticAI MCP Server

Serves the SaferAgenticAI framework (canonical criteria + Implementation Patterns layer) to coding assistants via the Model Context Protocol.

Install

Pick the path that matches your setup.

Option 1 — uvx (fastest, no manual venv)

If you have uv installed, point your MCP client at:

uvx --from git+https://github.com/NellInc/SaferAgenticAI#subdirectory=research/mcp/server saferagenticai-mcp

uv handles isolation and caches the install. Works for single-command config lines in ~/.claude/mcp.json.

Option 2 — pipx (isolated global install)

pipx install "git+https://github.com/NellInc/SaferAgenticAI#subdirectory=research/mcp/server"

Exposes saferagenticai-mcp globally; updated with pipx upgrade saferagenticai-mcp.

Option 3 — manual venv (works offline from a checkout)

Homebrew / system Python blocks direct pip install under PEP 668, so if you've cloned the repo and want an editable install:

python3 -m venv research/mcp/.venv
research/mcp/.venv/bin/pip install -e research/mcp/server

Produces research/mcp/.venv/bin/saferagenticai-mcp. Pattern YAML edits in the repo are picked up live (editable mode).

Option 4 — from PyPI (once published)

pipx install saferagenticai-mcp
# or
pip install --user saferagenticai-mcp

The package bundles criteria-v1.json + 214 pattern YAMLs + 4 exemplars inside saferagenticai_mcp/_data/, so a wheel install works without any repo checkout (verified: 891 KB wheel, 219 data entries).

Configure (Claude Code)

Add to ~/.claude/mcp.json (or your IDE's MCP config). Pick the variant that matches your install option.

With uvx

{
  "mcpServers": {
    "saferagenticai": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NellInc/SaferAgenticAI#subdirectory=research/mcp/server",
        "saferagenticai-mcp"
      ]
    }
  }
}

With pipx or manual venv

{
  "mcpServers": {
    "saferagenticai": {
      "command": "/absolute/path/to/saferagenticai-mcp"
    }
  }
}

For a manual venv checkout, the absolute path is <repo>/research/mcp/.venv/bin/saferagenticai-mcp.

Restart Claude Code / your IDE after editing. The server will load on the first tool call from your assistant.

Tools (10 total)

Tool	Input	Returns
list_suites	—	16 suites with titles and subgoal counts
get_requirement	id, include_pattern	one subgoal + its Pattern layer; falls back to fuzzy candidates if no exact match
list_requirements	suite/type/content_type/confidence filters	filtered subgoal list with reliability signals
search_patterns	query, limit	field-weighted ranked matches with matched_in and snippets
get_cross_references	id, include_inferred	outgoing adjacencies
get_reverse_references	id	incoming adjacencies (who cites this pattern)
resolve_id	query	canonicalise a partial id, slug fragment, or display_id; always returns candidates
find_patterns_for_task	task (natural language)	top patterns grouped by suite for a task description
list_unreviewed	limit	patterns without reviewed_by, sorted low-confidence first
review_stats	—	coverage %, per-suite, per-confidence; plus validation issue count

Data sources

• Canonical framework: assessor/src/data/criteria-v1.json (extracted from framework.html)
• Pattern layer: research/mcp/suites/<SUITE>/<pattern_id>.yaml
• Exemplars: research/mcp/exemplars/*.yaml (fallback for four anchor subgoals)

At startup the server loads both and builds an in-memory index keyed by pattern_id. display_id lookups are also supported but may resolve to multiple subgoals (underlined variants).

Smoke test (without MCP installed)

python3 -c "
from saferagenticai_mcp.framework_loader import load_framework
idx = load_framework()
print(f'{len(idx.subgoals)} subgoals, {sum(1 for s in idx.subgoals.values() if s.has_pattern)} with patterns')
"

Versioning

• Canonical framework: follows criteria-v1.json's version field.
• Pattern layer: v1-draft while this directory is being populated; v1 once reviewed.

What's already built in

• Hot reload — server stat-walks the source tree on each tool call; edits show up without restart.
• Load-time validation — required fields, content_type enum, confidence enum. Invalid patterns log WARNINGs but don't fail the server.
• find_patterns_for_task — natural-language task → top patterns grouped by suite. Replaces the need for a separate embedding index at current scale.
• Reverse xref index — built at load, queried by get_reverse_references.

Not implemented

• Auth / remote transport (stdio only).
• Embedding-based semantic search — the field-weighted keyword scoring is sufficient at 214 patterns; embeddings would be worth it at 10× this scale.
• mark_reviewed write tool — deliberately not added. Phase 3 review edits go through the YAML directly (editor + git diff = auditable); the MCP stays read-only.