zero-harm-ai-mcp 0.1.0

MCP server for PromptShield safety checks powered by zero-harm-ai-detectors.

Zero Harm AI MCP

Zero Harm AI MCP is a Model Context Protocol server that lets AI agents and runtime firewalls call Zero Harm AI 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.

zero-harm-ai-mcp
  MCP server adapter that exposes detector functionality to AI agents.

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

Installation

Install from PyPI:

pip install zero-harm-ai-mcp

For local development:

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

MCP Client Configuration

{
  "mcpServers": {
    "promptshield": {
      "command": "zero-harm-ai-mcp",
      "args": []
    }
  }
}

MCP Tools

zero_harm.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.

zero_harm.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.

zero_harm.redact_text

Return a redacted version of text plus findings.

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

zero_harm.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.

Working Examples

These examples are generated from the current local server implementation.

zero_harm.scan_text

Input:

{
  "text": "Contact [e-mail] before sharing the token.",
  "targets": ["pii", "secret", "harmful"],
  "redact": true
}

Output:

{
  "schema_version": "1.0.0",
  "risk_level": "medium",
  "recommended_action": "redact",
  "categories": [
    "pii"
  ],
  "summary": {
    "total_findings": 1,
    "pii": 1,
    "secret": 0,
    "harmful": 0
  },
  "findings": [
    {
      "type": "email",
      "category": "pii",
      "severity": "medium",
      "confidence": 0.99,
      "span": {
        "start": 8,
        "end": 25
      },
      "redacted": "[PII]",
      "message_index": null,
      "message_role": null,
      "evidence_available": false
    }
  ],
  "redacted_text": "Contact [PII] before sharing the token."
}

zero_harm.scan_messages

Input:

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "My email is [e-mail]."
    }
  ],
  "targets": ["pii", "secret", "harmful"],
  "redact": true
}

Output:

{
  "schema_version": "1.0.0",
  "risk_level": "medium",
  "recommended_action": "redact",
  "categories": [
    "pii"
  ],
  "summary": {
    "total_findings": 1,
    "pii": 1,
    "secret": 0,
    "harmful": 0
  },
  "findings": [
    {
      "type": "email",
      "category": "pii",
      "severity": "medium",
      "confidence": 0.99,
      "span": {
        "start": 12,
        "end": 29
      },
      "redacted": "[PII]",
      "message_index": 1,
      "message_role": "user",
      "evidence_available": false
    }
  ],
  "redacted_text": "[{\"role\": \"system\", \"content\": \"You are a helpful assistant.\"}, {\"role\": \"user\", \"content\": \"My email is [PII].\"}]"
}

zero_harm.redact_text

Input:

{
  "text": "aws_access_key_id = AKIAIOSFODNN7EXAMPLE",
  "targets": ["pii", "secret", "harmful"]
}

Output:

{
  "schema_version": "1.0.0",
  "risk_level": "high",
  "recommended_action": "block",
  "categories": [
    "secret"
  ],
  "summary": {
    "total_findings": 1,
    "pii": 0,
    "secret": 1,
    "harmful": 0
  },
  "findings": [
    {
      "type": "api_key",
      "category": "secret",
      "severity": "high",
      "confidence": 0.95,
      "span": {
        "start": 20,
        "end": 40
      },
      "redacted": "[SECRET]",
      "message_index": null,
      "message_role": null,
      "evidence_available": false
    }
  ],
  "redacted_text": "aws_access_key_id = [SECRET]"
}

zero_harm.evaluate_policy

Input:

{
  "text": "Contact [e-mail] before sharing the token.",
  "targets": ["pii", "secret", "harmful"],
  "redact": false
}

Output:

{
  "schema_version": "1.0.0",
  "risk_level": "medium",
  "recommended_action": "warn",
  "categories": [
    "pii"
  ],
  "summary": {
    "total_findings": 1,
    "pii": 1,
    "secret": 0,
    "harmful": 0
  }
}

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.

Development

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

Release

Build and validate distribution artifacts:

python -m build
twine check dist/*

See RELEASE.md for the full PyPI release flow.