{
  "markdown": "# SaferAgenticAI MCP Server\n\n<!-- mcp-name: io.github.NellInc/saferagenticai-mcp -->\n\nServes the SaferAgenticAI framework (canonical criteria + Implementation Patterns layer) to coding assistants via the Model Context Protocol.\n\n## Available in\n\nPublished to the canonical MCP catalogues — install from a registry-aware client or the CLI below:\n\n- **[PyPI](https://pypi.org/project/saferagenticai-mcp/)** — `saferagenticai-mcp`\n- **[Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.NellInc/saferagenticai-mcp)** — `io.github.NellInc/saferagenticai-mcp`\n\nAlso rolling out across the wider MCP ecosystem: [mcp.directory](https://mcp.directory), [mcpservers.org](https://mcpservers.org), [PulseMCP](https://www.pulsemcp.com) (via the registry ingest), and [mcp.so](https://mcp.so).\n\n## Install\n\nPick the path that matches your setup.\n\n### Option 1 — `uvx` (fastest, no manual venv)\n\nIf you have [uv](https://github.com/astral-sh/uv) installed, point your MCP\nclient at:\n\n```\nuvx --from git+https://github.com/NellInc/saferagenticai-mcp saferagenticai-mcp\n```\n\nuv handles isolation and caches the install. Works for single-command config\nlines in `~/.claude/mcp.json`.\n\n### Option 2 — `pipx` (isolated global install)\n\n```bash\npipx install \"git+https://github.com/NellInc/saferagenticai-mcp\"\n```\n\nExposes `saferagenticai-mcp` globally; updated with `pipx upgrade saferagenticai-mcp`.\n\n### Option 3 — manual venv (works offline from a checkout)\n\nHomebrew / system Python blocks direct `pip install` under PEP 668, so if\nyou've cloned the repo and want an editable install:\n\n```bash\npython3 -m venv research/mcp/.venv\nresearch/mcp/.venv/bin/pip install -e research/mcp/server\n```\n\nProduces `research/mcp/.venv/bin/saferagenticai-mcp`. Pattern YAML edits in\nthe repo are picked up live (editable mode).\n\n### Option 4 — from PyPI\n\n```bash\npipx install saferagenticai-mcp\n# or, with the modern uv toolchain:\nuv tool install saferagenticai-mcp\n# or plain pip:\npip install --user saferagenticai-mcp\n```\n\nFor audit-trail reproducibility, pin the version: `pipx install saferagenticai-mcp==0.3.6`.\nThe package bundles `criteria-v1.json` + 238 pattern YAMLs + 4 exemplars\n+ `operational_heuristics.yaml` inside `saferagenticai_mcp/_data/`, so a\nwheel install works without any repo checkout. (The 0.3.0 wheel predates the\ncorpus extension and bundles only 214 patterns, no heuristics; 0.3.1 is the\nfirst complete build.)\n\n## Configure (Claude Code)\n\nAdd to `~/.claude/mcp.json` (or your IDE's MCP config). Pick the variant that\nmatches your install option.\n\n### With `uvx`\n\n```json\n{\n  \"mcpServers\": {\n    \"saferagenticai\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/NellInc/saferagenticai-mcp\",\n        \"saferagenticai-mcp\"\n      ]\n    }\n  }\n}\n```\n\n### With `pipx` or manual venv\n\n```json\n{\n  \"mcpServers\": {\n    \"saferagenticai\": {\n      \"command\": \"/absolute/path/to/saferagenticai-mcp\"\n    }\n  }\n}\n```\n\nFor a manual venv checkout, the absolute path is\n`<repo>/research/mcp/.venv/bin/saferagenticai-mcp`.\n\nRestart Claude Code / your IDE after editing. The server will load on the\nfirst tool call from your assistant.\n\n## Tools (12 total)\n\n| Tool | Input | Returns |\n|---|---|---|\n| `list_suites` | — | 16 suites with titles and subgoal counts |\n| `get_requirement` | `id`, `include_pattern` | one subgoal + its Pattern layer; falls back to fuzzy candidates if no exact match |\n| `list_requirements` | suite/type/content_type/confidence filters | filtered subgoal list with reliability signals |\n| `search_patterns` | `query`, `limit`, `verbosity` | field-weighted ranked matches with `matched_in` and (in full mode) snippets + confidence flags. Field weights: title 10×, summary 4×, sfr 3×, description 2×, body 1× |\n| `get_cross_references` | `id`, `include_inferred` | outgoing adjacencies |\n| `get_reverse_references` | `id` | incoming adjacencies (who cites this pattern) |\n| `resolve_id` | `query` | canonicalise a partial id, slug fragment, or display_id; always returns candidates |\n| `find_patterns_for_task` | `task`, `limit`, `verbosity` | top patterns grouped by suite for a task description; defaults to compact mode for cheap triage |\n| `list_unreviewed` | `limit` | patterns without `reviewed_by`, sorted low-confidence first |\n| `review_stats` | — | coverage %, per-suite, per-confidence; plus validation issue count |\n| `list_operational_heuristics` | `suite_id`?, `query`? | operational heuristics distilled from production agentic AI deployment, optionally filtered by suite or keyword |\n| `get_operational_heuristic` | `id` | single operational heuristic by id (e.g. `OH::geoffrey-pattern`); returns full entry with principle, framework mapping, design patterns, and discovery narrative |\n\n## Data sources\n\n- **Normative framework**: `framework/catalog/`, loaded through the generated `assessor/src/data/criteria-v1.json` projection\n- **Pattern layer**: `research/mcp/suites/<SUITE>/<pattern_id>.yaml` (238 files)\n- **Exemplars**: `research/mcp/exemplars/*.yaml` (fallback for four anchor subgoals)\n- **Operational heuristics**: `research/mcp/operational_heuristics.yaml` (14 heuristics)\n\nAt 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).\n\n## Smoke test (without MCP installed)\n\n```bash\npython3 -c \"\nfrom saferagenticai_mcp.framework_loader import load_framework\nidx = load_framework()\nprint(f'{len(idx.subgoals)} subgoals, {sum(1 for s in idx.subgoals.values() if s.has_pattern)} with patterns')\n\"\n```\n\n## Versioning\n\n- Canonical framework: follows `criteria-v1.json`'s `version` field.\n- Pattern layer: `v1-draft` while this directory is being populated; `v1` once reviewed.\n- Server: semantic versioning. Current release is **0.3.6** (framework `1.3-draft`, full 238-pattern corpus, and operational heuristics bundled). Pin explicitly for audit reproducibility.\n\n## What's already built in\n\n- **Hot reload** — server stat-walks the source tree on each tool call; edits show up without restart.\n- **Load-time validation** — required fields, content_type enum, confidence enum. Invalid patterns log WARNINGs but don't fail the server.\n- **`find_patterns_for_task`** — natural-language task → top patterns grouped by suite. Replaces the need for a separate embedding index at current scale.\n- **Reverse xref index** — built at load, queried by `get_reverse_references`.\n\n## Not implemented\n\n- Auth / remote transport (stdio only).\n- Embedding-based semantic search — the field-weighted keyword scoring is sufficient at 238 patterns; embeddings would be worth it at 10× this scale.\n- `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.\n\nThe broader agent-native architecture proposes composite orientation, context-pack,\nworkspace, planning, action, and verification operations. They are explicitly not\npart of the current `0.3.6` interface. See\n[`../../architecture/README.md`](../../architecture/README.md) for the target and\ncompatibility plan.\n\nThe authoritative catalog maps current MCP identifiers and slugs to permanent\nrequirement IDs. Server `0.3.6` retains its twelve-tool interface, loads the\ngenerated packaged snapshot, validates `saai.catalog.v1`, and reports the shared\nsnapshot hash.\n\n## License\n\nThis server (the code in this directory) is licensed **MIT** — see [`LICENSE`](LICENSE).\n\nThe safety-framework *content* it serves (the patterns, canonical criteria, and operational heuristics bundled under `saferagenticai_mcp/_data/`) is part of the SaferAgenticAI framework, published under **CC-BY-4.0** at the repository root. Attribution: Nell Watson and the Agentic AI Safety Community of Practice.\n",
  "bytes": 7862,
  "sha": "045af6bfaecf175922adf38f0e665ac84840f67a46b71643cc44bb3ad579e399",
  "repo_slug": "nellinc/saferagenticai-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nellinc_saferagenticai_mcp_e8cc6e0f/readme"
}