mcp-guardrails-kit

A prompt-injection-aware tool gateway and MCP server, built as a reference implementation for a fictional internal ticket-triage assistant.

This is a portfolio project, not a real product. It exists to demonstrate a concrete, testable pattern for building guardrails around agentic tool use — permission tiers, untrusted-content quarantine, and heuristic injection detection — around a small but real MCP server. The domain (support ticket triage) is generic and interchangeable; the guardrail patterns are the point.

What it demonstrates

• Tool permission tiers with explicit confirmation. Every tool is registered as either read_only or sensitive. Sensitive tools (draft_reply, escalate_ticket) never execute a side effect until the caller passes confirmed=True — every caller in this codebase routes through the gateway's single invoke() entry point by construction (see docs/adr/0001-tool-permission-tiers.md for the honest caveat: this is a code-review convention, not a language-enforced boundary).
• Quarantine of untrusted external content. fetch_external_page returns content fetched from a URL linked inside a ticket — a realistic prompt-injection vector. That content is wrapped and clearly delimited as data, never treated as instructions, before it is handed back to any caller or model.
• Heuristic injection detection with a verdict. Quarantined (and other) text is scanned for injection patterns and returns one of ALLOW / FLAG / BLOCK. A BLOCK verdict replaces the payload with a safe refusal instead of the raw text (never a verbatim excerpt — even the scan's own matched_patterns are redacted to category labels before crossing a tool boundary). This is backed by a red-team test suite of known injection phrasings.
• Three independent scan gates, not just one. A Supervisor walks a triage → draft → review → escalate pipeline. A ticket's own subject/body — the most directly attacker-controlled input in the system — is scanned right after lookup; the drafted reply is re-scanned before escalation is considered; and the escalation reason a model proposes is scanned again before escalate_ticket is ever called. A BLOCK at any of the three halts the pipeline right there.

Install & run

pip install -e ".[dev]"
pytest
ruff check .

No external services or API keys are required to install, test, or lint. See Scope & non-goals below for what pip install -e ".[live]" adds.

Connecting the MCP server to a real client

After pip install -e . (or pip install mcp-guardrails-kit once published), the mcp-guardrails-kit command is registered as a console entry point (see [project.scripts] in pyproject.toml) and speaks the MCP stdio protocol. Point a real MCP client at it — for example, Claude Desktop or Claude Code — with a config block like:

{
  "mcpServers": {
    "guardrails-kit": {
      "command": "mcp-guardrails-kit"
    }
  }
}

For Claude Desktop, this goes in claude_desktop_config.json; for Claude Code, add it via claude mcp add or the equivalent project-level MCP config. No arguments or environment variables are required for the default (non-live) mode.

Scope & non-goals

• Heuristic injection detection is defense in depth, not a guarantee. It is a regex/keyword-based scanner, not a model-backed classifier. It will miss novel or sufficiently obfuscated phrasings — see docs/adr/0003-heuristic-injection-detection.md for the explicit tradeoff. The permission-tier and quarantine layers stay in effect even when detection fails; injection detection is one layer among three, not the only one.
• There is no real ticketing system behind this. search_knowledge_base and lookup_ticket read from small in-memory fixtures. There is no database, no external ticketing API integration, and no persistence.
• AnthropicModelClient is optional and live-only. It is gated behind the live extra (pip install -e ".[live]") and is never imported or exercised by the test suite or CI — tests and the default install path have zero dependency on any external LLM API or network access.
• All data is in-memory and resets on restart. Drafts, escalations, and fetched external content are not persisted anywhere; restarting the server clears all state.

More

• Architecture and data flow: docs/architecture.md
• Design decisions: docs/adr/