PiQrypt MCP 서버

Model Context Protocol을 통한 AI 에이전트용 암호화 감사 추적

Related MCP server: DCL Evaluator

🚀 PiQrypt MCP란 무엇인가요?

PiQrypt MCP 서버는 AI 에이전트를 위한 양자 내성 암호화 감사 추적인 PiQrypt에 대한 Model Context Protocol 액세스를 제공합니다.

사용 사례:

• 🤖 AI 에이전트: 모든 의사결정에 암호화 증명 서명

• 📊 n8n 워크플로우: 자동화 워크플로우에 감사 추적 추가

• 🏦 트레이딩 봇: 자동 매매를 위한 SEC/FINRA 규정 준수

• 👥 HR 자동화: GDPR을 준수하는 AI 채용 결정

• 🏥 의료 AI: 의료 결정을 위한 HIPAA 감사 추적

📦 설치

사전 요구 사항

1. piqrypt 설치 (필수 — Python 3.8 이상)

pip install piqrypt

MCP 서버는 모든 암호화 작업을 piqrypt Python 패키지에 위임합니다. 설치되어 있지 않으면 서버는 모든 도구 호출 시 명확한 오류를 반환합니다.

2. MCP 서버 설치 (Node.js 18 이상)

npm install -g @piqrypt/mcp-server

npx를 통한 설치 (전역 설치 불필요)

npx @piqrypt/mcp-server

소스에서 빌드

git clone https://github.com/piqrypt/piqrypt-mcp-server
cd piqrypt-mcp-server
npm install
npm run build

PIQRYPT_PYTHON — 사용자 지정 Python 환경

기본적으로 서버는 python3(Linux/Mac) 또는 python(Windows)을 사용합니다. piqrypt가 가상 환경에 설치되어 있는 경우, 이 변수를 올바른 인터프리터를 가리키도록 설정하세요:

Windows

set PIQRYPT_PYTHON=C:\path\to\venv\Scripts\python.exe

Linux / Mac

export PIQRYPT_PYTHON=/path/to/venv/bin/python

지속적으로 사용하려면 MCP 클라이언트 구성에 추가하세요:

{
  "mcpServers": {
    "piqrypt": {
      "command": "piqrypt-mcp-server",
      "args": [],
      "env": {
        "PIQRYPT_PYTHON": "/path/to/venv/bin/python"
      }
    }
  }
}

⚙️ 구성

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "piqrypt": {
      "command": "piqrypt-mcp-server",
      "args": []
    }
  }
}

n8n (v1.88 이상)

1. n8n MCP 통합 설치

2. 구성에 PiQrypt MCP 서버 추가

3. MCP 노드를 통해 워크플로우에서 사용

호환성

MCP 클라이언트

자동화 플랫폼 (MCP 노드 경유)

PiQrypt MCP로 감사할 수 있는 항목

모든 도구 호출은 스탬프, 검증, 내보내기, 검색이라는 4가지 동일한 작업을 거칩니다. 상황에 따라 실질적으로 의미하는 바는 다음과 같습니다:

자동 매매 / 금융 주문을 제출하거나, 포트폴리오를 리밸런싱하거나, 거래를 트리거하는 모든 에이전트는 실행 전에 각 의사결정을 스탬프 처리할 수 있습니다. 서명된 체인은 추가 인프라 없이도 SEC/FINRA 감사를 위해 내보낼 수 있습니다.

HR 및 채용 자동화 후보자를 평가하거나, 이력서 점수를 매기거나, 지원자를 분류하는 모든 워크플로우는 각 의사결정을 스탬프 처리할 수 있습니다. AI 지원 채용을 위한 GDPR 제22조 준수 감사 추적을 제공합니다. 누가, 언제, 무엇을 결정했는지, 어떤 데이터가 사용되었는지(해시 처리됨, 원본은 절대 저장되지 않음)를 기록합니다.

콘텐츠 및 게시 파이프라인 콘텐츠를 초안 작성, 승인 또는 게시하는 모든 에이전트는 각 단계를 스탬프 처리할 수 있습니다. 여러 AI 에이전트가 협업할 때 누가 무엇을 어떤 순서로 작성했는지 증명해야 할 때 유용합니다.

DevOps 및 CI/CD 배포를 트리거하거나, 브랜치를 병합하거나, 보안 비밀을 교체하는 모든 에이전트는 각 작업을 스탬프 처리할 수 있습니다. 자율 에이전트에 의해 수행된 인프라 변경 사항에 대한 변조 방지 기록을 제공합니다.

의료 및 의료 AI 모든 진단 또는 분류 에이전트는 각 권장 사항을 스탬프 처리할 수 있습니다. 각 AI 출력을 검증 가능한 에이전트 ID와 연결하는 HIPAA 준수 감사 추적을 제공합니다.

모든 경우의 공통 패턴:

[Agent makes decision]
↓
piqrypt_stamp_event    ← sign + chain
↓
[Agent executes action]
↓
piqrypt_export_audit   ← portable proof, verifiable
                          without PiQrypt installed

🛠️ 사용 가능한 도구

1. piqrypt_stamp_event

암호화 증명으로 AI 의사결정에 서명합니다.

매개변수:

• agent_id (문자열, 필수): 에이전트 식별자

• payload (객체, 필수): 의사결정 데이터

• previous_hash (문자열, 선택): 체인 연결을 위한 이전 이벤트 해시

예시:

const event = await mcp.call('piqrypt_stamp_event', {
  agent_id: 'trading_bot_v1',
  payload: {
    action: 'buy',
    symbol: 'AAPL',
    quantity: 100,
    price: 150.25
  }
});

반환값:

{
  "version": "AISS-1.0",
  "agent_id": "trading_bot_v1",
  "timestamp": 1739382400,
  "nonce": "uuid-...",
  "payload": { ... },
  "previous_hash": "sha256:...",
  "signature": "base64:..."
}

2. piqrypt_verify_chain

이벤트 체인의 무결성을 검증합니다.

매개변수:

• events (배열, 필수): 검증할 이벤트

예시:

const result = await mcp.call('piqrypt_verify_chain', {
  events: [event1, event2, event3]
});

반환값:

{
  "valid": true,
  "events_count": 3,
  "chain_hash": "sha256:...",
  "errors": []
}

3. piqrypt_export_audit

규정 준수를 위해 감사 추적을 내보냅니다.

매개변수:

• agent_id (문자열, 필수): 내보낼 에이전트

• certified (불리언): PiQrypt 인증 요청

• output_format (문자열): json 또는 pqz

예시:

const audit = await mcp.call('piqrypt_export_audit', {
  agent_id: 'trading_bot_v1',
  certified: true,
  output_format: 'json'
});

4. piqrypt_search_events

SQLite 인덱스를 통한 빠른 검색.

매개변수:

• event_type (문자열, 선택): 유형별 필터링

• from_timestamp (숫자, 선택): 시작 시간

• to_timestamp (숫자, 선택): 종료 시간

• limit (숫자): 최대 결과 수 (기본값: 100)

예시:

const trades = await mcp.call('piqrypt_search_events', {
  event_type: 'trade_executed',
  from_timestamp: 1739300000,
  limit: 50
});

📊 Vigil 대시보드 (선택 사항, 무료)

스탬프 처리된 모든 이벤트는 PiQrypt의 로컬 모니터링 대시보드인 Vigil에서 볼 수 있습니다.

참고: Vigil은 MCP 서버에 의해 자동으로 실행되지 않습니다. 대시보드를 열기 전에 별도로 시작해야 합니다.

piqrypt vigil
# → http://localhost:8421

무료 티어 포함 항목: 체인 상태, VRS 위험 점수, 7일 기록, 중요(CRITICAL) 알림. 90일 기록, TrustGate 거버넌스 및 양자 내성 서명을 원하시면 Pro로 업그레이드하세요.

🗑️ 에이전트 관리

에이전트는 첫 번째 스탬프 시 자동으로 생성됩니다. 에이전트를 보고 삭제하려면:

1. Vigil 시작: piqrypt vigil

2. http://localhost:8421 열기

3. All Agents 보기로 이동

4. 삭제할 에이전트 체크 → ✕ Delete selected 클릭

5. 확인 — 에이전트가 남아 있지 않으면 Vigil은 시작 화면으로 돌아갑니다.

에이전트는 컴퓨터의 ~/.piqrypt/agents/에 저장됩니다. 에이전트를 삭제하면 해당 키와 이벤트 기록이 영구적으로 제거됩니다.

🔒 보안 모델

프로세스 격리

┌─────────────────────────────────────┐
│  MCP Client (any MCP-compatible client)     │
│  ↓ JSON-RPC over stdio              │
├─────────────────────────────────────┤
│  MCP Server (TypeScript/Node.js)    │  ← No crypto here
│  ↓ subprocess call                  │
├─────────────────────────────────────┤
│  Python Bridge (bridge.py)          │
│  ↓ invokes CLI                      │
├─────────────────────────────────────┤
│  PiQrypt CLI (Python)               │
│  ↓ uses                             │
├─────────────────────────────────────┤
│  Core Crypto (aiss package)         │  ← All crypto here
│  • Ed25519 / Dilithium3             │
│  • RFC 8785 canonical JSON          │
│  • Hash chains                      │
└─────────────────────────────────────┘

보장

✅ 개인 키는 MCP 계층에 노출되지 않음 ✅ 모든 암호화는 Python에서 수행 (Ed25519, Dilithium3) ✅ CLI와 동일한 보안 (프로세스 격리) ✅ RFC AISS-1.1 준수 (동일한 출력) ✅ 하위 프로세스 호출 전 입력 유효성 검사

📚 예시

트레이딩 봇 (n8n)

[Webhook: price alert] 
    ↓
[AI Decision: buy/sell?]
    ↓
[PiQrypt MCP: stamp decision]  ← Audit trail
    ↓
[Execute trade API]
    ↓
[Database: store proof]

HR 자동화

[Upload CV]
    ↓
[AI Agent: evaluate candidate]
    ↓
[PiQrypt MCP: stamp evaluation]  ← GDPR compliance
    ↓
[Email HR team]

🧪 테스트

# Build
npm run build

# Test bridge
python3 src/python/bridge.py stamp '{"agent_id":"test","payload":{"action":"test"}}'

# Test MCP server (manual)
node dist/index.js
# Then send MCP request via stdin

🔧 문제 해결

Error: piqrypt is not installed in this Python environment

MCP 서버에서 사용하는 Python 인터프리터가 piqrypt 패키지를 찾을 수 없습니다.

해결 방법:

pip install piqrypt

piqrypt가 시스템 Python이 아닌 가상 환경에 설치된 경우, PIQRYPT_PYTHON을 올바른 인터프리터를 가리키도록 설정하세요:

# Linux / Mac
export PIQRYPT_PYTHON=/path/to/venv/bin/python

# Windows
set PIQRYPT_PYTHON=C:\path\to\venv\Scripts\python.exe

서버가 사용할 Python을 확인하려면:

# Linux / Mac
$PIQRYPT_PYTHON -c "import aiss; print('ok')"

# Windows
%PIQRYPT_PYTHON% -c "import aiss; print('ok')"

📖 문서

• MCP 설정 가이드

• 도구 참조

• n8n 통합

• 보안 모델

• RFC 준수

🤝 기여

기여를 환영합니다! CONTRIBUTING.md를 참조하세요.

📄 라이선스

MCP 서버 → MIT 라이선스 - LICENSE 참조 PiQrypt 코어 → 무료 티어 + 상업용 티어

🔗 링크

• PiQrypt 코어: https://github.com/piqrypt/piqrypt

• MCP 프로토콜: https://modelcontextprotocol.io

• n8n: https://n8n.io

• 문서: https://docs.piqrypt.com

PiQrypt Inc.에서 ❤️를 담아 제작함