PromptShield MCP

PromptShield MCP is a Model Context Protocol server that lets AI agents and runtime firewalls call PromptShield-style safety checks for text, chat messages, prompts, tool inputs, and generated outputs.

The server is a thin adapter over zero-harm-ai-detectors. It should not duplicate detector logic from the detector package or from the PromptShield GitHub Action.

Goals

• Expose PII, secret, and harmful-content detection through MCP tools.
• Return structured findings that agents and firewalls can enforce.
• Support local/self-hosted operation for sensitive data.
• Keep logs privacy-safe by default.
• Provide stable tool contracts that can be used by coding agents, chat agents, and firewall.

Non-Goals

• Reimplementing zero-harm-ai-detectors.
• Acting as a hosted service by default.
• Making policy enforcement decisions that belong to a firewall or calling agent.
• Replacing the PromptShield GitHub Action.

Relationship To Other Projects

zero-harm-ai-detectors
  Shared detector engine for PII, secrets, and harmful content.

promptshield
  GitHub Action and CI-oriented scanner for pull requests.

promptshield-mcp
  MCP server adapter that exposes detector functionality to AI agents.

promptshield-firewall (future)
  Runtime enforcement layer. It can call promptshield-mcp or use
  zero-harm-ai-detectors directly.

Proposed MCP Tools

promptshield.scan_text

Scan one text string for PII, secrets, and harmful content.

Use this for prompt inputs, generated outputs, tool arguments, logs, and arbitrary text.

promptshield.scan_messages

Scan chat-style messages while preserving message roles and indexes.

Use this when an agent wants to inspect a conversation before sending it to a model or tool.

promptshield.redact_text

Return a redacted version of text plus findings.

Use this when the caller wants to continue safely after removing sensitive spans.

promptshield.evaluate_policy

Map detector findings to an action recommendation.

Use this when a caller wants a normalized decision such as allow, warn, redact, or block.

Expected Finding Shape

{
  "type": "email",
  "category": "pii",
  "severity": "medium",
  "confidence": 0.98,
  "span": {
    "start": 18,
    "end": 35
  },
  "redacted": "[EMAIL]",
  "message_index": 0,
  "message_role": "user"
}

Expected Response Shape

{
  "schema_version": "1.0.0",
  "risk_level": "high",
  "recommended_action": "redact",
  "categories": ["pii", "secret"],
  "summary": {
    "total_findings": 2,
    "pii": 1,
    "secret": 1,
    "harmful": 0
  },
  "findings": [],
  "redacted_text": "Contact [EMAIL] with token [SECRET]."
}

Privacy Requirements

• Do not log raw input text by default.
• Do not log detected secret values by default.
• Include a config option for audit logs that stores only counts, categories, severities, and request metadata.
• Avoid sending data to external services unless explicitly configured.
• Keep the default transport local-first.

Suggested Implementation Stack

• Python 3.11+
• mcp Python SDK
• zero-harm-ai-detectors
• pydantic for tool input and output schemas
• pytest for tests
• ruff for linting and formatting

Development Setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

First Milestone

Build a local MCP server with:

• promptshield.scan_text
• promptshield.scan_messages
• unit tests with mocked detector results
• README quickstart
• example MCP client config

Do not add network transport, hosted deployment, auth, or database persistence in the first milestone.