Sri Lanka PDPA Technical Readiness Audit (MCP Server)

An open-source technical hygiene, readiness indicator, and gap analysis toolkit aligned with Sri Lanka's Personal Data Protection Act, No. 9 of 2022 (PDPA).

pdpa-audit-mcp exposes 9 specialized tools through the Model Context Protocol (MCP) for AI coding assistants (such as Claude Desktop and Cursor), a local REST bridge, and a single-page interactive web dashboard.

Table of Contents

• Key Features

• Architecture Overview

• Installation

• Quick Start

  • 1. FastMCP Stdio Server (Claude Desktop)

  • 2. Interactive Web Dashboard

  • 3. Evaluation Sheet Generator CLI

  • 4. Offline Demonstration

• Claude Desktop Configuration

• Tool Reference

• Scoring & Heuristic Evaluation

• Safety & Security Architecture

• Validation & Empirical Evaluation

• Limitations

• Contributing

• License

Related MCP server: shipcheck-mcp

Key Features

• 9 Specialized MCP Audit Tools: Inspect privacy policies, cookie consent banners, personal data forms, source code schemas, breach readiness documentation, and cross-border vendor data flows.

• Trilingual Indicator Detection: Full text normalization and keyword indicator matching across English, Sinhala (සිංහල), and Tamil (தமிழ்).

• Comprehensive SSRF & DNS Rebinding Immunity: Socket-level IP address pinning disallows loopback, private RFC 1918, link-local, carrier-grade NAT, 6to4, NAT64, and cloud metadata (169.254.169.254) requests.

• Strict Path Boundary Guard: Enforces root containment against directory traversal (..), Windows UNC shares, alternate drive letters, and symlink/junction escapes outside configured directories.

• Zero Personal Data Storage: Audits structural attributes and parameter names only. Raw field values, passwords, form entries, and logging payloads are never recorded or emitted in reports.

• Self-Contained Web Dashboard: Modern vanilla HTML5/CSS3 interface running locally with zero external network requests, per-response Content Security Policy nonces, and zero vulnerable DOM sinks (innerHTML, eval).

• Standardized Reporting: Exports structured Markdown and JSON gap reports complete with prioritised findings, rule coverage metrics, and actionable remediation notes.

Architecture Overview

flowchart TD
    subgraph Clients["Clients & Interfaces"]
        Claude["Claude Desktop / Cursor<br/>(MCP Client over stdio)"]
        Browser["Local Web Browser<br/>(http://127.0.0.1:8765)"]
        CLI["Audit CLI Scripts<br/>(demo.py / evaluate.py)"]
    end

    subgraph ServerLayer["Server Layer"]
        FastMCP["FastMCP Stdio Server<br/>(pdpa_audit_mcp.server)"]
        Bridge["FastAPI REST Bridge<br/>(Host check + X-Bridge-Token)"]
        Dashboard["Static Dashboard<br/>(Vanilla JS, Strict CSP)"]
    end

    subgraph CoreEngine["Core Audit Engine"]
        Orchestrator["Full Audit Orchestrator<br/>(report.py)"]
        Scorer["Readiness Scorer<br/>(scoring.py)"]
        Checklist["Checklist Engine<br/>(pdpa_checklist.yaml)"]
    end

    subgraph SecurityGuards["Defensive Guards"]
        SSRF["SSRFProtectedTransport<br/>(DNS Pinning & IP Filter)"]
        PathGuard["Path Guard<br/>(Junction & Traversal Check)"]
        Sanitizer["Output Sanitizer<br/>(Markdown Injection Guard)"]
    end

    subgraph AuditTools["Specialized Tools"]
        T1["scan_privacy_policy"]
        T2["detect_cookie_consent"]
        T3["find_personal_data_forms"]
        T4["scan_project_files"]
        T5["check_breach_readiness"]
        T6["detect_third_party_transfers"]
    end

    Claude <--> FastMCP
    Browser <--> Dashboard
    Dashboard <--> Bridge
    CLI --> Orchestrator

    FastMCP --> Orchestrator
    Bridge --> Orchestrator

    Orchestrator --> AuditTools
    Orchestrator --> Scorer
    Orchestrator --> Checklist

    AuditTools --> SSRF
    AuditTools --> PathGuard
    Orchestrator --> Sanitizer

Installation

Prerequisites

• Python 3.11 or higher

• Recommended: uv (extremely fast Python package and environment manager)

Option 1: With uv (Recommended)

# Clone the repository
git clone https://github.com/Sadeep78/pdpa-audit-mcp.git
cd pdpa-audit-mcp

# Install dependencies and sync virtual environment
uv sync

Option 2: With standard pip and virtualenv

# Clone the repository
git clone https://github.com/Sadeep78/pdpa-audit-mcp.git
cd pdpa-audit-mcp

# Create and activate virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

# Install in editable mode
pip install -e .

Quick Start

1. FastMCP Stdio Server (Claude Desktop)

Start the FastMCP stdio server directly:

# Using uv
uv run pdpa-audit-mcp

# Using virtualenv
pdpa-audit-mcp

2. Interactive Web Dashboard

Launch the local REST bridge and web UI:

# Using uv
uv run pdpa-audit-bridge

# Custom port
uv run pdpa-audit-bridge --port 8765

Open http://127.0.0.1:8765/ in your browser to run audits and download Markdown gap analysis reports.

3. Evaluation Sheet Generator CLI

Generate a rule-by-rule human labeling sheet for an authorized target:

uv run python scripts/evaluate.py --url https://example.com --confirm-authorised --out docs/evaluation_sheet.md

4. Offline Demonstration

Run the automated offline demonstration against the bundled test fixtures:

uv run python scripts/demo.py

This spins up local test servers, executes the full audit against compliant and non-conforming fixtures, displays console tables with matched indicator terms, and writes example reports to docs/examples/.

Claude Desktop Configuration

To connect pdpa-audit-mcp to Claude Desktop, add the server to your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pdpa-audit": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\path\\to\\pdpa-audit-mcp",
        "pdpa-audit-mcp"
      ],
      "env": {
        "PDPA_AUDIT_ALLOWED_ROOTS": "C:\\path\\to\\your\\projects",
        "PDPA_AUDIT_ALLOW_PRIVATE": "false"
      }
    }
  }
}

Environment Configuration Variables

Tool Reference

All tools include the defensive use notice: "Use only on sites/projects you own or are authorised to audit."

Scoring & Heuristic Evaluation

Readiness scores are computed as a weighted percentage (0.0% – 100.0%) accompanied by explicit coverage metrics:

1. Heuristic Weights:

   • high severity: weight 3

   • medium severity: weight 2

   • low severity: weight 1

2. Evaluated vs Excluded Rules:

   • passed: earns 100% of rule weight.

   • failed: earns 0% of rule weight.

   • needs_review / not_evaluated: excluded from the scored denominator to prevent unassessed rules from skewing scores.

   • not_applicable: excluded from both score denominator and coverage numerator when target components are absent (e.g. no cookies set, no password fields, no external vendors).

3. Anti-False-Confidence Safeguards:

   • Scores always display coverage side-by-side (e.g., 100.0% (Mostly Ready | Coverage: 95.8%)).

   • If weight coverage is under 60%, the label is automatically suffixed with (partial assessment).

   • If no evaluable rules run, scores return None with label "Insufficient data", never an inaccurate 0% or 100%.

4. Multi-Source Merge Precedence: When multiple tools assess the same rule, findings are merged using a strict conservative hierarchy: $$\text{failed} > \text{needs_review} > \text{passed} > \text{not_evaluated} > \text{not_applicable}$$

Safety & Security Architecture

• SSRF Defense: The custom SSRFProtectedTransport resolves hostnames and executes DNS pinning before initiating the first network hop, preventing DNS rebinding.

• Decompression Bomb Guard: Streams decompressed HTTP responses with an enforced 1 MB threshold.

• Path Traversal Protection: Strictly blocks .. path segments, Windows UNC shares (\\host\share), alternate drive prefixes, and directory junctions pointing outside allowed paths.

• Privacy Assurance: Logging findings report file:line locations only. Log payloads and personal values are never extracted or stored.

• Content Security Policy: Dashboard uses a strict CSP with per-request cryptographic nonces, blocking unsafe inline scripts and cross-origin connections.

Validation & Empirical Evaluation

The automated test suite in tests/test_rule_matrix.py is a synthetic regression harness verifying keyword indicators, multilingual normalization (English, Sinhala, Tamil), and structural detectors.

Real-world precision, recall, and false-positive rates are measured through manual verification against production targets documented in docs/EVALUATION.md.

Limitations

1. Static HTML Only: Scans static HTML responses only; single-page applications (SPAs) that render dynamically via client-side JavaScript without server-side rendering will show little content and may omit unrendered elements.

2. Keyword Heuristics: Textual analysis relies on normalized keyword indicators across English, Sinhala, and Tamil. Complex legal drafting nuances require human expert verification.

3. No Proof of Runtime Behaviour: Static analysis does not monitor runtime network egress, live database write operations, or actual backend retention cron jobs.

4. Chunk-Level Decompression: Response decompression is capped at 1 MB after each chunk is received. While payloads exceeding 1 MB are truncated safely, an extreme compression ratio within a single chunk can cause a brief memory spike before truncation.

5. CDN & Font Domains: External CDN and web font domains are reported as third-party processors with unverified locations, which may produce false fails for cross-border transfer disclosures when such assets do not process personal data.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.

2. Create a feature branch: git checkout -b feature/my-feature.

3. Ensure formatting and tests pass:

   uv run ruff check .
   uv run ruff format .
   uv run pytest -W error::ResourceWarning

4. Commit your changes and open a Pull Request.

License

This project is open-source software licensed under the MIT License:

Copyright (c) 2026 Sadeep Sasanka (Sadeep78) and pdpa-audit-mcp contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
...

For full license details, see the LICENSE file.