Skip to main content
Glama
deenesjakoruzh
thegeekybeng

pc2e-pii-shield

by thegeekybeng
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

pc2e-pii-shield

本番環境に対応したセキュアなModel Context Protocol（MCP）サーバーです。PostgreSQLへの読み取り専用クエリ実行を提供し、自動・クライアントサイド・エッジでの個人情報（PII）マスキングを実現します。LLMエージェント（Cursor、Cline、Claude Codeなど）がデータベースに対してSQLクエリを実行できるようにしながら、GDPR、PDPA、およびデータプライバシー原則への厳格な準拠を保証します。

再利用可能なセキュリティミドルウェア製品として設計・エンジニアリングされた本サーバーは、データベースのクエリ結果を傍受して、機密データの外部送信を防止します。

技術アーキテクチャ

flowchart TD
    Client["AI Agent / Client (Cursor/Cline)"]
    Proxy["Nginx Reverse Proxy"]
    App["pc2e-pii-shield (Express)"]
    DB["Postgres Database (Tailscale-Only)"]

    Client ==>|HTTPS / SSE Request| Proxy
    Proxy ==>|x-api-key Authentication| App
    App ==>|Regex Read-Only Validation| DB
    DB ==>|Raw SQL Results| App
    App ==>|PII Tokenization & Masking| Proxy
    Proxy ==>|Sanitized Event Stream| Client

中核コンポーネント

  1. 自動マスキングインターセプター（masking.ts）: SQL結果セットを動的にスキャンします。カラムスキーマの照合（name、email、phoneなどを含むフィールド）と正規表現ベースのコンテンツスキャンを組み合わせたハイブリッド方式を採用し、サーバーからデータが送信される前に機密識別子を検出してマスキングします。

  2. 仮名化キャッシュ（cache.ts）: インメモリのTTLベースのキャッシュ（デフォルト：30分）で、生の値を一時的なプレースホルダー（例：__PERSON_A__、__EMAIL_1__）にマッピングします。これにより、無制限のメモリ消費を防ぎながら、双方向の復元が可能になります。

  3. ASTレベルの変更ガード（db.ts）: 生のSQL入力を傍受する厳格な正規表現バリデータです。非SELECTコマンドをブロックし、DROP、ALTER、DELETE、TRUNCATE、CREATE、GRANTなどの禁止キーワードを含むクエリを拒否することで、アプリケーションレイヤーで厳格な読み取り専用境界を保証します。

  4. 同時セッションマネージャー（index.ts）: 基本的な単一接続テンプレートとは異なり、接続sessionIdをキーとするSSEServerTransportインスタンスのアクティブマップを維持し、複数のリモート開発者やエージェントが状態の衝突なしに同時に接続してストリーミングできるようにします。

  5. テレメトリ＆メトリクスエンドポイント（/stats）: 接続数、一意のクライアントIP追跡、集計クエリ実行統計を公開し、インストール状況とアクティブな使用状況をリアルタイムで監視します。

Related MCP server: PostgreSQL MCP Server

セキュリティモデルと脅威の軽減

  • ゼロトラストデータベース接続: 認証情報の漏洩を防ぐように設計されています。データベースは分離されたTailscale専用ネットワークインターフェース（例：100.92.174.76）上で実行され、データベースポートがパブリックインターネットに公開されることはありません。

  • 暗号化トランスポートとAPIキーセキュリティ: サーバーはNginxをフロントにワイルドカードSSL証明書を使用したHTTPS（ポート443）で保護され、リクエストを転送する前にセキュアなAPIキー認証ゲート（x-api-key）を適用します。

  • インメモリライフサイクル: 仮名化マッピングは厳格なTTL付きでメモリ内に保存され、マスキングされたPIIの永続的なディスクフットプリントを残しません。

インストールとデプロイ

1. 前提環境のセットアップ

環境テンプレートをコピーします：

cp .env.example .env

.env内でデータベースの認証情報を設定し、安全なAPIキーを生成します。

2. ネイティブビルド

Node.js（v18以降）がインストールされていることを確認します：

npm install
npm run build
npm start

3. コンテナ化されたデプロイ

Docker Composeを使用してデプロイします：

docker compose up -d --build

これにより、ホストのポート3088がコンテナの内部ポート3000にマッピングされ、SSEサーバーが自動的に実行されます。

4. 直接実行（NPX）

コードを手動でダウンロードせずに、Stdioトランスポート経由でサーバーを即座に実行できます：

npx -y mcp-pii-shield --db-uri "postgresql://username:password@localhost:5432/your_database"

または、SSEトランスポート経由でサーバーを実行します：

npx -y mcp-pii-shield --sse --port 3000 --db-uri "postgresql://username:password@localhost:5432/your_database" --api-key "your_secret_key"

クライアント統合

A. ローカルクライアント統合（NPX over Stdio経由）

npxを使用してサーバーを直接起動するようにローカルAIクライアントを設定します。

Claude Desktop（config.json）

以下のブロックを~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または%APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します：

{
  "mcpServers": {
    "pc2e-pii-shield": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-pii-shield",
        "--db-uri",
        "postgresql://username:password@localhost:5432/your_database"
      ]
    }
  }
}

Cursor（設定→機能→MCP）

  1. + 新しいMCPサーバーを追加をクリックします。

  2. 名前にpc2e-pii-shieldを設定します。

  3. タイプにcommandを設定します。

  4. コマンドに以下を設定します：

    npx -y mcp-pii-shield --db-uri "postgresql://username:password@localhost:5432/your_database"

VS Code（Cline / Roo Code）

クライアント設定JSONに以下を追加します：

{
  "mcpServers": {
    "pc2e-pii-shield": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-pii-shield",
        "--db-uri",
        "postgresql://username:password@localhost:5432/your_database"
      ]
    }
  }
}

B. リモートクライアント統合（HTTPS over SSE経由）

ホスト型サーバー（例：公開済みのNASインスタンス）に接続する場合は、SSEトランスポートURLを介して接続します。

VS Code（Cline / Roo Code）

{
  "mcpServers": {
    "pc2e-pii-shield": {
      "sseUrl": "https://pii-shield.thegeekybeng.com/sse?api_key=your_api_key_here"
    }
  }
}

Cursor

  1. + 新しいMCPサーバーを追加をクリックします。

  2. 名前にpc2e-pii-shieldを設定します。

  3. タイプにSSEを設定します。

  4. URLに以下を設定します：

    https://pii-shield.thegeekybeng.com/sse?api_key=your_api_key_here

プロジェクト概要とテクニカルリード

本プロジェクトは、Andrew Yeoによって設計・構築・オープンソース化されました。

リードアーキテクトについて

Andrewはシンガポールを拠点とするシニアシステムアーキテクト兼AIエンジニアであり、以下を提供しています：

  • APACでの25年のプロフェッショナル経験：プログラムデリバリー、クライアントオンボーディング、技術ベンダー管理を担当。

  • 16年以上のシステムアーキテクチャおよびテクノロジーリーダーシップ：堅牢なエンタープライズインフラストラクチャとマイクロサービスの設計・デプロイに従事。

  • 2年以上の実践的なAI/MLエンジニアリング：AI安全性、LLMメトリクス、セキュアなエージェントワークフローを専門とする。

実証済みの実績

  • セキュアな市民プラットフォーム： MPS-Connect（市民選挙区のケースワークプラットフォーム）と**Case-Writer-Intelligence（CWI）**を設計・デプロイし、7つのヒューマン・イン・ザ・ループ承認ゲートを備えた3段階の因果関係エンジンを統合して、文書トリアージ時間を40%削減。

  • AI計測とテスト： **Portable Continuous Context Engine（PC2E）**を設計し、6つのLLMプロバイダーにわたる50,000件のケースを体系的かつ実証的に評価して、モデルのアライメントとコンプライアンスをベンチマーク。

  • 技術的専門分野： CI/CDおよびDevSecOps（GitHub Actions、Docker）、コンテナ化されたデプロイ、ゼロトラストネットワークトポロジ、ローカル/エッジSLMオーケストレーションのエキスパート。

Available Tools

3 tools
add_to_rosterA

Register new names to the active regex scan roster for local name-matching detection.

ParametersJSON Schema
NameRequiredDescriptionDefault
namesYesAn array of names to be dynamically added to the scanner roster.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are not provided, so the description carries the burden, but it is minimal. It clarifies the scope (local name-matching detection) but does not disclose behavioral traits such as whether the roster is persistent, how additions affect existing entries, or any potential side effects (e.g., deduplication). It goes beyond a simple 'Add' but lacks substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that packs essential information: action, target, and purpose. It is front-loaded with the verb. No filler or redundant content. Five is appropriate for its brevity and efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and no output schema. The description covers the purpose and target, but lacks details about behavior (e.g., duplicates, confirmation) and does not mention return values. Given the low complexity, this is acceptable but not fully complete; a 3 is appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the parameter 'names' is documented as 'An array of names to be dynamically added to the scanner roster'). The description adds value by clarifying that the names are 'new' and for 'local name-matching detection', which enhances the schema's meaning. With full coverage, baseline is 3; the added specificity justifies a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Register new names to the active regex scan roster for local name-matching detection' clearly states the action (register names), the resource (active regex scan roster), and the purpose (local name-matching detection). It distinguishes from siblings (unmask_text, run_secure_query) by specifying the roster for name-matching, which is specific enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (for local name-matching detection) but does not explicitly specify when to use this tool versus alternatives, nor any exclusions (e.g., when to prefer unmask_text). Sibling tools exist but are not referenced or contrasted. Adequate but lacks explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_secure_queryA

Execute a read-only SELECT database query. All PII values (names, emails, phones, NRIC/IDs) in the results will be automatically masked before being returned.

ParametersJSON Schema
NameRequiredDescriptionDefault
sql_queryYesThe read-only SQL SELECT query to run (e.g. SELECT name, email FROM contacts LIMIT 5)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden, and it does so well by disclosing: (1) the operation is read-only, and (2) all PII values in results will be automatically masked. This gives the agent critical behavioral expectations (e.g., don't expect unmasked PII in results). It does not cover edge cases like error handling or large result pagination, but for the information provided, this is a strong disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences (33 words) with a clear action-first structure. Front-loads the primary purpose ('Execute a read-only SELECT database query') and follows with the key behavioral differentiator (PII masking). Every word contributes meaning; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 1-parameter tool with no output schema, the description covers all essential aspects: the operation, the constraint on input, and a key output transformation (masking). Additional details like error messages for invalid queries or rate limiting would be nice but are not critical for this complexity, and the behavioral notes alone elevate it above the norm.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by qualifying the query as 'read-only' and emphasizing the PII masking behavior, which affects result processing semantics beyond what the schema example shows. It could have gone further by specifying what happens with non-SELECT input (error vs. rejection).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Execute a read-only SELECT database query') with a specific verb and resource, and the PII masking note explains what makes it 'secure.' This effectively differentiates it from sibling tools (unmask_text, add_to__roster) by making clear this is the querying tool that returns masked data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (read-only data retrieval) but does not explicitly state alternatives or exclusions (e.g., 'for write operations use X'). The sibling tools could offer more context, but no explicit comparison is provided. The read-only and SELECT constraints give some usage guardrails.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unmask_textA

Restore the original raw PII values in a text payload by replacing placeholders (e.g. PERSON_A, EMAIL_1) with their original values cached during this session.

ParametersJSON Schema
NameRequiredDescriptionDefault
masked_textYesThe text containing placeholders to be restored.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description must convey behavior. It mentions the session-cached values but does not disclose what happens if the cache is missing, whether the operation is reversible, or any side effects (e.g., does it mutate input or return a new string?). It provides some context but lacks critical behavioral details for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action and provides examples. It contains no redundant or tangential information, making it optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter and no output schema, the description covers the main mechanism but omits the return value and potential error conditions (e.g., missing cache entries). While the session dependency is mentioned, a mention of expected output or failure handling would enhance completeness. Still, it is adequate for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides a basic description of 'masked_text.' The tool description adds value by giving concrete examples of placeholder formats and explaining that they are replaced with original values. This goes beyond the schema's simple definition, enriching parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: restoring original PII values by replacing placeholders like __PERSON_A__ and __EMAIL_1__ with cached values. It uses a specific verb and resource, making it unmistakable. Although siblings are unrelated, the purpose is distinct and well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies usage context by mentioning 'cached during this session,' which tells the agent when the tool is applicable (after a prior masking operation). It does not explicitly list alternatives or exclusions, but given the unrelated siblings, this is not a significant gap. The context is clear enough for selecting this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedadd_to_roster
    • First observedrun_secure_query
    • First observedunmask_text
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation5/5

Each tool addresses a distinct concern: one unmask text, one manage the name roster, and one execute queries with automatic masking. There is no overlap that would cause an agent to misselect.

Naming Consistency4/5

Most tools follow a verb_noun pattern (unmask_text, run_secure_query), but add_to_roster breaks the pattern with an intervening preposition. This is a minor deviation and the intent remains clear.

Tool Count4/5

Three tools is a reasonable, focused set for a PII-shielding server. It is slightly lean but each tool serves a clear purpose without unnecessary bloat.

Completeness3/5

The core masking lifecycle is covered—query masking, unmasking, and roster management—but obvious gaps exist: no tool for masking non-query text, no roster removal or listing, and no way to manage the cached placeholders beyond unmasking. These gaps could force workarounds.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • PostgreSQL Read-Only MCP

    currentspace
    F
    license
    Not graded
    quality
    D
    maintenance
    A secure MCP server that enables querying PostgreSQL databases through an SSH tunnel with enforced read-only access, connection pooling, and comprehensive data exploration tools.
    -

  • PostgreSQL MCP Server

    datdeboer
    A
    license
    Not graded
    quality
    D
    maintenance
    A production-ready MCP server that enables safe, read-only SQL SELECT queries against PostgreSQL databases with built-in security validation. It features connection pooling, automatic row limits, and structured logging to ensure secure and reliable database interactions.
    31 npm
    ISC

  • mcp-postgres

    gbfeliped
    A
    license
    Not graded
    quality
    D
    maintenance
    Read-only PostgreSQL MCP server that enables running SELECT queries, listing tables and schemas, and describing columns, with built-in protection against writes and malicious SQL attacks.
    476 npm
    MIT