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.

Related MCP server: AIM-Guard-MCP

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.