Use OGuardAI in your assistant (MCP)

npm install -g @oguardai/mcp-server
# or
pnpm add -g @oguardai/mcp-server

{
  "mcpServers": {
    "guardai": {
      "command": "npx",
      "args": ["@oguardai/mcp-server"],
      "env": {
        "GUARDAI_URL": "https://guardai.internal.example",
        "GUARDAI_API_KEY": "your-api-key"
      }
    }
  }
}

claude mcp add guardai \
  --env GUARDAI_URL=https://guardai.internal.example \
  --env GUARDAI_API_KEY=your-api-key \
  -- npx @oguardai/mcp-server

{
  "mcpServers": {
    "guardai": {
      "command": "npx",
      "args": ["@oguardai/mcp-server"],
      "env": {
        "GUARDAI_URL": "https://guardai.internal.example",
        "GUARDAI_API_KEY": "your-api-key"
      }
    }
  }
}

# Exactly one auth decision is required, or the transport refuses to start.
GUARDAI_MCP_HTTP_BEARER_TOKEN=$(openssl rand -base64 32) \
  guardai-mcp --transport http --host 0.0.0.0 --port 8090
# Env-selected transport, same bearer requirement:
# GUARDAI_MCP_TRANSPORT=http GUARDAI_MCP_HTTP_BEARER_TOKEN=... guardai-mcp
# Local loopback pilot only, opt out of auth explicitly instead of a bearer:
# GUARDAI_MCP_HTTP_ALLOW_UNAUTHENTICATED=true guardai-mcp --transport http

You have OGuardAI MCP tools available (guardai_rehydrate, guardai_rag_context, guardai_rag_answer). Always follow these rules:
1. Work only with the data you are given as {{type:id:cap}} tokens; treat every token as an opaque placeholder and never guess, expand, or reformat it.
2. Reference data by its token or handle; never paste raw sensitive values into your answers, and never invent a real value behind a token.
3. When producing the final answer, use guardai_rehydrate to confirm the tokens resolve; the real values are restored downstream, outside your context, for policy-allowed channels only.
4. This connector has no transform tool. If you are handed raw sensitive data, do not process it: say it must be tokenized upstream first.

You have OGuardAI MCP tools available (guardai_transform, guardai_rehydrate, guardai_detect). Always follow these rules:
1. Before reasoning over or sending onward any content that may contain personal or sensitive data (names, emails, IDs, IBANs, phone numbers, addresses, health or financial details), call guardai_transform first and work only with the returned tokens, never the raw values.
2. Reference data by its token or handle; never paste raw sensitive values back into your answers.
3. When producing the final answer, call guardai_rehydrate so only policy-allowed values are restored.
4. If a guardai tool is unavailable, say so and stop; do not fall back to handling raw sensitive data.

User: "Please draft a reply to this customer email:
  From: Erika Mustermann <erika.mustermann@example.com>
  Subject: Order complaint ORD-2026-4892"

Claude (inside the MCP tool loop):
  1. Calls guardai_transform with the email text
     -> Gets safe text with {{person:p_001:6a3e91f04d27}}, {{email:e_001:c85b2df1e963}}, {{order:o_001:41f7a9c0b3d5}}
  2. Drafts reply using the semantic tokens (no raw PII seen by the model)

Host application (AFTER the agent/model finishes):
  3. Calls guardai_rehydrate with the model's tokenized output
     and the session_state from step 1
     -> Restores real values server-side for delivery to the end user

NOTE: guardai_rehydrate is NOT called by the model as an MCP tool.
It is called by the host application code after the model loop ends.
The model never sees restored PII.

User: "Summarize this customer complaint. Make sure to protect
their personal data:

  My name is Max Mustermann, email max.mustermann@example.de.
  Order Q-2026-0847 was delivered damaged."

Claude will (inside the MCP tool loop):
1. Call guardai_transform to tokenize the PII
2. Process the safe text to generate a summary using tokens

Then the host application (AFTER the model loop ends):
3. Call guardai_rehydrate with the model's tokenized summary
   and the session_state, restoring real values for the end user.
   The model never calls guardai_rehydrate and never sees restored PII

User: "Check this document for any PII before I send it to the
external analytics team."

Claude will:
1. Call guardai_detect to find all entities
2. Report what was found (types, confidence scores)
3. Suggest which policy to apply

MODEL PLANE  (through the MCP server, JSON-RPC over stdio)
  detect ─▶ evaluate_policy ─▶ transform ─▶ [LLM draft on tokens] ─▶ rehydrate
  the model sees only tokens, entity types, and policy decisions; rehydrate
  confirms how many tokens resolved and returns NO restored text

HOST PLANE  (trusted claims backend, OGuardAI REST directly)
  materializes the real letter, the internal note, the reinsurer extract, and
  the audit line from the one tokenized draft, each on its own output channel

# The bundled stack requires these four secrets, and its client key ships least-privilege (channel
# user_output only), so widen it to the insurance-de policy and the channels this example uses.
export GUARDAI_SESSION_SECRET=$(openssl rand -base64 32)
export GUARDAI_API_KEY_1=$(openssl rand -hex 32)
export GUARDAI_DETECTOR_API_KEY=$(openssl rand -hex 32)
export GUARDAI_REDIS_PASSWORD=$(openssl rand -hex 32)
export GUARDAI_API_KEY_1_ALLOWED_POLICIES=default,default-ner-required,german-support,insurance-de
export GUARDAI_API_KEY_1_ALLOWED_OUTPUT_CHANNELS=user_output,customer_email,internal_summary,reinsurer_export,log_safe
docker compose -f deploy/docker/docker-compose.yml up -d

pnpm install
pnpm --filter @oguardai/mcp-server build   # produces apps/mcp-server/dist/index.js

cd examples/mcp
pnpm install
export GUARDAI_API_KEY="$GUARDAI_API_KEY_1"   # the bundled stack runs api_key auth
pnpm demo

MCP server:  guardai-mcp v0.1.0 (protocol 2024-11-05)
Tools:       14 verfuegbar (host mode; admin and revoke tools stay off)
OGuardAI:    http://localhost:3000   Detector: builtin_and_ner (full entity detection)
Policy:      insurance-de   Sprache: de   LLM: offline

MODELL-EBENE 1/4 - guardai_detect (Triage)
Erkannte Entitaeten (9): address=2, claim_id=1, email=1, iban=1, license_plate=1, person=1, phone=1, policy_number=1

MODELL-EBENE 2/4 - guardai_evaluate_policy (Disposition)
  person   -> tokenize, restore=abstract
  iban     -> tokenize, restore=masked
  email    -> tokenize, restore=formatted
  ...

MODELL-EBENE 3/4 - guardai_transform (Schutz)
Was das LLM sieht (safe_text, nur Tokens):
  Guten Tag, mein Name ist {{person:p_001:...}}, ich bin die Versicherungsnehmerin zu
  Versicherungsschein {{custom:policy_number:x_001:...}}. ... amtliches Kennzeichen
  {{custom:license_plate:x_002:...}} ... Schadennummer {{custom:claim_id:x_003:...}}. ...
  Konto {{iban:ib_001:...}}. ... {{email:e_001:...}} oder telefonisch {{phone:ph_001:...}} ...

MODELL-EBENE 4/4 - LLM-Entwurf + guardai_rehydrate (Bestaetigung)
rehydrate ack -> resolved=5 unresolved=[]
Der wiederhergestellte Text (mit echten Daten) wird dem Modell NICHT zurueckgegeben.

HOST-EBENE - Materialisierung ueber OGuardAI REST (ausserhalb des Modells)
[customer_email]   -> ... Schadenmeldung SCH-2026-558310 zu Versicherungsschein VN-4471902 ...
                       Konto D*** **** **** **** **** *0 ... an k***********************e.
[reinsurer_export] -> ... Schadenmeldung S*************0 zu Versicherungsschein V********2 ...
                       Konto [REDACTED] ... an [REDACTED].
[log_safe]         -> Guten Tag [REDACTED], ... Schadenmeldung [REDACTED] ... Konto [REDACTED] ...

FAIL-CLOSED (ueber die MCP-Tools beobachtet)
1) Manipuliertes session_state -> abgelehnt: ToolError (isError)
2) Erfundener Token -> resolved=1 unresolved=[{{person:p_999:...}}]
3) Fehlendes Argument 'text' -> ProtocolError (-32602)

{
  "name": "guardai-mcp-example",
  "version": "1.0.0",
  "description": "MCP client that drives the OGuardAI MCP server for a German insurance claims desk",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "test": "tsx --test src/scenario.test.ts",
    "demo": "tsx src/demo.ts"
  },
  "devDependencies": {
    "@types/node": "^20",
    "tsx": "^4.0",
    "typescript": "^5.5"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

export OPENAI_API_KEY=sk-...        # optional; enables the real provider path
export OPENAI_MODEL=gpt-4o-mini     # optional; default gpt-4o-mini
pnpm demo

Guten Tag, mein Name ist Frau Dr. Erika Mustermann, ich bin die Versicherungsnehmerin zu Versicherungsschein VN-4471902. Am 3. Juli hatte ich mit meinem Fahrzeug, amtliches Kennzeichen M-KV 2847, einen Auffahrunfall auf der A9. Schadennummer SCH-2026-558310. Der Unfallgegner ist mir bekannt, verletzt wurde niemand. Bitte ueberweisen Sie die Erstattung auf mein Konto DE97 9900 0000 0123 4567 89. Sie erreichen mich unter erika.mustermann@example.de oder telefonisch +49 151 23456789. Meine Anschrift ist Musterstrasse 14, 80331 Muenchen. Ich bitte um eine kurze Eingangsbestaetigung und die naechsten Schritte zur Regulierung.

/**
 * Minimal MCP client over stdio, the same wire an AI client (Claude Desktop,
 * Cursor, Claude Code) uses to talk to `@oguardai/mcp-server`.
 *
 * It spawns the server as a subprocess, speaks JSON-RPC 2.0 line by line, and
 * correlates responses to requests by id. This is deliberately hand-rolled with
 * Node builtins so the example has no runtime dependency and mirrors exactly how
 * a host process drives the server: initialize, tools/list, tools/call.
 *
 * One subtlety that a naive `printf | server` misses: tool handlers are async
 * (they await an HTTP call to OGuardAI), so the caller must keep the pipe open
 * and read responses as they arrive. Closing stdin early exits the server before
 * an in-flight tool call flushes its result.
 */

import { spawn, type ChildProcess } from "node:child_process";
import { createInterface, type Interface } from "node:readline";

export interface ServerSpec {
  command: string;
  args: string[];
  env: NodeJS.ProcessEnv;
}

interface JsonRpcResponse {
  jsonrpc: "2.0";
  id: number | string | null;
  result?: unknown;
  error?: { code: number; message: string; data?: unknown };
}

interface ToolResult {
  content?: Array<{ type: string; text?: string }>;
  isError?: boolean;
}

/** A JSON-RPC protocol error (bad method, missing argument, malformed envelope). */
export class ProtocolError extends Error {
  constructor(
    message: string,
    readonly code: number,
  ) {
    super(message);
    this.name = "ProtocolError";
  }
}

/** A tool that ran but failed (isError result). The server surfaces this so the
 *  model sees the failure text instead of a silent success. */
export class ToolError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "ToolError";
  }
}

export class McpClient {
  private child: ChildProcess | null = null;
  private reader: Interface | null = null;
  private nextId = 0;
  private readonly pending = new Map<
    number,
    { resolve: (r: JsonRpcResponse) => void; reject: (e: Error) => void }
  >();
  private exited = false;

  constructor(private readonly spec: ServerSpec) {}

  start(): void {
    const child = spawn(this.spec.command, this.spec.args, {
      env: this.spec.env,
      // stderr inherits only when debugging; the server logs a startup line there.
      stdio: ["pipe", "pipe", process.env.GUARDAI_MCP_DEBUG ? "inherit" : "ignore"],
    });
    this.child = child;

    if (!child.stdout || !child.stdin) {
      throw new Error("MCP server subprocess has no stdio pipes");
    }

    this.reader = createInterface({ input: child.stdout });
    this.reader.on("line", (line) => this.onLine(line));

    // If the server dies, fail every outstanding request rather than hang.
    child.on("exit", (code) => {
      this.exited = true;
      const err = new Error(`MCP server exited (code ${code ?? "unknown"})`);
      for (const { reject } of this.pending.values()) reject(err);
      this.pending.clear();
    });
  }

  private onLine(line: string): void {
    const trimmed = line.trim();
    if (!trimmed) return;
    let message: JsonRpcResponse;
    try {
      message = JSON.parse(trimmed) as JsonRpcResponse;
    } catch {
      return; // ignore non-JSON noise on stdout
    }
    if (typeof message.id !== "number") return; // no correlation handle
    const waiter = this.pending.get(message.id);
    if (!waiter) return;
    this.pending.delete(message.id);
    waiter.resolve(message);
  }

  private request(
    method: string,
    params?: Record<string, unknown>,
    timeoutMs = 15_000,
  ): Promise<JsonRpcResponse> {
    if (this.exited || !this.child?.stdin) {
      return Promise.reject(new Error("MCP server is not running"));
    }
    const id = ++this.nextId;
    const stdin = this.child.stdin;
    return new Promise<JsonRpcResponse>((resolve, reject) => {
      const timer = setTimeout(() => {
        this.pending.delete(id);
        reject(new Error(`MCP request '${method}' timed out after ${timeoutMs}ms`));
      }, timeoutMs);
      this.pending.set(id, {
        resolve: (r) => {
          clearTimeout(timer);
          resolve(r);
        },
        reject: (e) => {
          clearTimeout(timer);
          reject(e);
        },
      });
      stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
    });
  }

  async initialize(): Promise<{ name: string; version: string; protocolVersion: string }> {
    const res = await this.request("initialize", {});
    if (res.error) throw new ProtocolError(res.error.message, res.error.code);
    const r = res.result as {
      serverInfo: { name: string; version: string };
      protocolVersion: string;
    };
    return { ...r.serverInfo, protocolVersion: r.protocolVersion };
  }

  async listTools(): Promise<string[]> {
    const res = await this.request("tools/list");
    if (res.error) throw new ProtocolError(res.error.message, res.error.code);
    const r = res.result as { tools: Array<{ name: string }> };
    return r.tools.map((t) => t.name);
  }

  /** Calls a tool and returns the raw text payload. Throws ProtocolError for a
   *  JSON-RPC error (e.g. a missing argument) and ToolError for an isError result
   *  (a tool that ran but failed, e.g. a rejected session blob). */
  async callToolRaw(name: string, args: Record<string, unknown>): Promise<string> {
    const res = await this.request("tools/call", { name, arguments: args });
    if (res.error) throw new ProtocolError(res.error.message, res.error.code);
    const result = res.result as ToolResult;
    const text = result.content?.find((c) => c.type === "text")?.text ?? "";
    if (result.isError) throw new ToolError(text || "tool reported an error");
    return text;
  }

  /** Convenience wrapper for tools that return a JSON document as text. */
  async callTool<T>(name: string, args: Record<string, unknown>): Promise<T> {
    return JSON.parse(await this.callToolRaw(name, args)) as T;
  }

  async stop(): Promise<void> {
    this.reader?.close();
    if (this.child && !this.exited) {
      this.child.stdin?.end();
    }
  }
}

/**
 * Scenario: Musterversicherung AG (fictional German motor/property
 * insurer). Its claims desk runs an AI client (Claude Desktop, Cursor, Claude
 * Code) wired to the OGuardAI MCP server. When an adjuster drops an inbound
 * claimant email into the assistant, the model must triage and draft an
 * acknowledgment without a single real name, IBAN, or email entering its context.
 *
 * Everything here is fictional; all PII in the fixture is invented.
 */

import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import type { ServerSpec } from "./mcp-client.js";

export const COMPANY = {
  name: "Musterversicherung AG",
  assistant: "Helva",
  // A shipped policy (policies/insurance-de/): formal German person restore,
  // masked payout IBAN, redacted regulatory IDs, custom policy/claim identifiers,
  // and per-channel tightening for the policyholder letter, reinsurer, and audit log.
  policy: "insurance-de",
  language: "de",
} as const;

/**
 * The four consumers of one restored draft, each an OGuardAI output channel with
 * a different visibility level defined by the insurance-de policy:
 *  - customer  -> the policyholder's letter (own case ids, IBAN masked)
 *  - adjuster  -> the internal case note
 *  - partner   -> a reinsurer extract (identifiers coarsened, bank data dropped)
 *  - audit     -> the SIEM line (nothing identifying)
 */
export const CHANNELS = {
  customer: "customer_email",
  adjuster: "internal_summary",
  partner: "reinsurer_export",
  audit: "log_safe",
} as const;

export const GUARDAI_URL =
  process.env.GUARDAI_URL ?? process.env.GUARDAI_BASE_URL ?? "http://localhost:3000";

export const GUARDAI_API_KEY = process.env.GUARDAI_API_KEY ?? "";

/**
 * Where to find the MCP server. By default the example spawns the built server
 * exactly as an AI client config would (`node apps/mcp-server/dist/index.js`),
 * resolved relative to this file so it works from any cwd. Override the command
 * or entrypoint to point at a source run (tsx) or an installed binary.
 */
export function resolveServerSpec(): ServerSpec {
  const defaultEntry = fileURLToPath(
    new URL("../../../apps/mcp-server/dist/index.js", import.meta.url),
  );
  const command = process.env.GUARDAI_MCP_COMMAND ?? "node";
  const entry = process.env.GUARDAI_MCP_SERVER ?? defaultEntry;
  return {
    command,
    args: [entry],
    // The server reads the OGuardAI URL and key from its own environment, so the
    // real PII stays server-side and never crosses this host process.
    env: {
      ...process.env,
      GUARDAI_URL,
      ...(GUARDAI_API_KEY ? { GUARDAI_API_KEY } : {}),
      // This process IS the trusted host: it drives guardai_detect / guardai_transform as
      // middleware BEFORE the model turn (see host.ts). Those raw-input tools are hidden and
      // rejected in the server's default `model` posture, so host mode is pinned here rather
      // than inherited: an ambient GUARDAI_MCP_MODE=model would break the demo silently.
      GUARDAI_MCP_MODE: "host",
    },
  };
}

export function loadClaimEmail(): string {
  const path = fileURLToPath(
    new URL("../fixtures/helvetia-schaden-erstmeldung.de.txt", import.meta.url),
  );
  return readFileSync(path, "utf8").trim();
}

/**
 * LLM adapter. Through the MCP `guardai_transform` tool the model receives only
 * `safe_text`: the message with every sensitive value already replaced by a
 * `{{type:id:hash}}` token. It never sees a real name, IBAN, or email. The
 * adapter drafts a formal German acknowledgment that reuses those exact tokens.
 *
 * When OPENAI_API_KEY is set it calls OpenAI Chat Completions over fetch, reading
 * the key from the environment exactly as a real integration would. When it is
 * unset it falls back to a deterministic offline draft so the example runs end to
 * end against OGuardAI alone with no provider account.
 */

import { COMPANY } from "./scenario.js";

const OPENAI_BASE_URL = process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
const OPENAI_MODEL = process.env.OPENAI_MODEL ?? "gpt-4o-mini";

export function llmMode(): "openai" | "offline" {
  return process.env.OPENAI_API_KEY ? "openai" : "offline";
}

/** First token of a given type inside the safe text, or undefined. `person`,
 *  `iban`, `email`, `phone`; custom identifiers use the `custom:<subtype>` form. */
function tokenOf(safeText: string, type: string): string | undefined {
  const escaped = type.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  return safeText.match(new RegExp(`\\{\\{${escaped}:[^}]+\\}\\}`))?.[0];
}

/**
 * The token contract is the load-bearing instruction: echo every placeholder
 * verbatim and never prepend a salutation to a person token, because OGuardAI's
 * restore injects the correct gendered form itself.
 */
function systemPrompt(): string {
  return [
    `Du bist ${COMPANY.assistant}, Schadenservice-Assistentin von ${COMPANY.name}.`,
    "Antworte auf Deutsch in der formellen Sie-Form: knappe Eingangsbestaetigung einer Kfz-Schadenmeldung.",
    "",
    "Die Nachricht enthaelt Platzhalter der Form {{typ:id:hash}} fuer echte Daten,",
    "die du nicht sehen darfst. Regeln:",
    "1. Uebernimm jeden Platzhalter Zeichen fuer Zeichen unveraendert. Erfinde,",
    "   vervollstaendige oder formatiere niemals einen Platzhalter und schreibe",
    "   niemals selbst einen Namen, eine Nummer, IBAN oder E-Mail.",
    "2. Schreibe KEIN 'Herr', 'Frau' oder 'Sehr geehrte' vor einen person-Platzhalter.",
    "   Die Laufzeit setzt die korrekte Anrede selbst ein. Eroeffne mit",
    "   'Guten Tag {{person:...}},'.",
    "3. Nenne Schaden- und Versicherungsscheinnummer, bestaetige den Eingang und",
    "   verweise auf die Pruefung. Erfinde keine Fristen oder Betraege.",
  ].join("\n");
}

export async function draftReply(safeText: string): Promise<string> {
  return llmMode() === "openai" ? draftWithOpenAI(safeText) : draftOffline(safeText);
}

async function draftWithOpenAI(safeText: string): Promise<string> {
  const res = await fetch(`${OPENAI_BASE_URL}/chat/completions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    },
    body: JSON.stringify({
      model: OPENAI_MODEL,
      temperature: 0.2,
      messages: [
        { role: "system", content: systemPrompt() },
        { role: "user", content: safeText },
      ],
    }),
  });
  if (!res.ok) {
    throw new Error(`OpenAI request failed: ${res.status} ${res.statusText}`);
  }
  const data = (await res.json()) as { choices?: Array<{ message?: { content?: string } }> };
  const content = data.choices?.[0]?.message?.content?.trim();
  if (!content) throw new Error("OpenAI returned an empty completion");
  return content;
}

/**
 * Deterministic stand-in for the model. Composes a formal German acknowledgment
 * reusing the exact tokens from the transformed message, so the example produces
 * the same protection trace with or without a provider key.
 */
function draftOffline(safeText: string): string {
  const person = tokenOf(safeText, "person");
  const claim = tokenOf(safeText, "custom:claim_id");
  const policy = tokenOf(safeText, "custom:policy_number");
  const iban = tokenOf(safeText, "iban");
  const email = tokenOf(safeText, "email");

  const lines: string[] = [];
  lines.push(person ? `Guten Tag ${person},` : "Guten Tag,");
  lines.push("");
  lines.push(
    claim && policy
      ? `vielen Dank fuer Ihre Schadenmeldung ${claim} zu Versicherungsschein ${policy}. Wir haben Ihre Erstmeldung aufgenommen und pruefen den Vorgang umgehend.`
      : "vielen Dank fuer Ihre Schadenmeldung. Wir haben Ihre Erstmeldung aufgenommen und pruefen den Vorgang umgehend.",
  );
  if (iban) {
    lines.push(
      `Eine etwaige Erstattung veranlassen wir nach Abschluss der Pruefung auf das angegebene Konto ${iban}.`,
    );
  }
  if (email) {
    lines.push(`Eine schriftliche Eingangsbestaetigung senden wir an ${email}.`);
  }
  lines.push("");
  lines.push("Mit freundlichen Gruessen");
  lines.push(`${COMPANY.assistant}, Schadenservice ${COMPANY.name}`);
  return lines.join("\n");
}

/**
 * The trusted host plane.
 *
 * The MCP `guardai_rehydrate` tool deliberately does NOT return restored text: it
 * confirms how many tokens resolved and keeps the real values out of the model's
 * context. So the model can drive the whole workflow safely, but it can never pull
 * PII back through a tool call.
 *
 * A real deployment still needs the finished letter and the audit line. Those are
 * produced here, by the trusted claims backend, calling the OGuardAI REST API
 * directly, outside the model's tool surface. Different channels yield different
 * visibility from the same tokenized draft, and `restore_overrides` can only
 * tighten a channel, never loosen it, so this path cannot escalate beyond what the
 * policy and the caller's auth already permit.
 */

import { GUARDAI_URL, GUARDAI_API_KEY } from "./scenario.js";

export interface Materialized {
  channel: string;
  restoredText: string;
  tokensResolved: number;
  tokensUnresolved: string[];
}

interface RehydrateResponse {
  restored_text?: string;
  tokens_resolved?: number;
  tokens_unresolved?: string[];
}

/** Any `{{...}}` still present after restore. On a customer channel a residual
 *  token means an unresolved value, so the letter must be withheld, not sent. */
export function residualTokens(text: string): string[] {
  return text.match(/\{\{[^}]+\}\}/g) ?? [];
}

export async function materialize(
  draft: string,
  sessionState: string,
  channel: string,
  restoreOverrides?: Record<string, string>,
): Promise<Materialized> {
  const res = await fetch(`${GUARDAI_URL}/v1/rehydrate`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      ...(GUARDAI_API_KEY ? { "X-API-Key": GUARDAI_API_KEY } : {}),
    },
    body: JSON.stringify({
      output: draft,
      session_state: sessionState,
      output_channel: channel,
      ...(restoreOverrides ? { restore_overrides: restoreOverrides } : {}),
    }),
  });
  if (!res.ok) {
    // Fail closed: a rejected session (tampered or expired) never yields raw text.
    throw new Error(`Rehydrate failed on channel '${channel}': ${res.status}`);
  }
  const data = (await res.json()) as RehydrateResponse;
  return {
    channel,
    restoredText: data.restored_text ?? "",
    tokensResolved: data.tokens_resolved ?? 0,
    tokensUnresolved: data.tokens_unresolved ?? [],
  };
}

/**
 * Guided end-to-end trace of the Musterversicherung claims desk over MCP.
 *
 * Two planes run against one live OGuardAI server:
 *
 *   MODEL PLANE  (through the MCP server, JSON-RPC over stdio)
 *     detect -> evaluate_policy -> transform -> [LLM draft on tokens] -> rehydrate
 *     Everything the AI client does. The model only ever sees tokens, entity
 *     types, and policy decisions. rehydrate confirms resolution but returns no
 *     restored text.
 *
 *   HOST PLANE  (trusted claims backend, OGuardAI REST directly)
 *     Materializes the real letter, the internal note, the reinsurer extract, and
 *     the audit line from the one tokenized draft, each on its own channel.
 *
 * Run:  GUARDAI_API_KEY=... pnpm demo
 */

import { McpClient, ProtocolError, ToolError } from "./mcp-client.js";
import { CHANNELS, COMPANY, GUARDAI_URL, loadClaimEmail, resolveServerSpec } from "./scenario.js";
import { draftReply, llmMode } from "./llm.js";
import { materialize, residualTokens } from "./host.js";

interface TransformResult {
  safe_text: string;
  session_state: string;
  entities_count: number;
}
interface DetectResult {
  entities: Array<{ type: string | { custom: string }; confidence: number }>;
  count: number;
}
interface PolicyDecision {
  entity_type: string;
  action: string;
  restore_mode?: string;
}
interface EvaluateResult {
  decisions: PolicyDecision[];
  policy_version?: string;
  warnings?: string[];
}
interface HealthResult {
  status: string;
  components?: Record<string, { message?: string }>;
}
interface RehydrateAck {
  tokens_resolved: number;
  tokens_unresolved: string[];
}

// The claimant's identity and payment block, builtin entity types only. We preview
// the policy disposition of these (person, IBAN, email, phone); the custom policy
// and claim identifiers are governed by their own always-on rules in insurance-de.
const CONTACT_BLOCK =
  "Frau Dr. Erika Mustermann, Konto DE97 9900 0000 0123 4567 89, " +
  "E-Mail erika.mustermann@example.de, Telefon +49 151 23456789.";

function rule(label: string): void {
  console.log(`\n${"=".repeat(74)}\n${label}\n${"=".repeat(74)}`);
}

function indent(text: string, spaces = 2): string {
  const pad = " ".repeat(spaces);
  return text
    .split("\n")
    .map((line) => pad + line)
    .join("\n");
}

function typeName(t: string | { custom: string }): string {
  return typeof t === "string" ? t : t.custom;
}

function entitySummary(entities: DetectResult["entities"]): string {
  const counts = new Map<string, number>();
  for (const e of entities) {
    const name = typeName(e.type);
    counts.set(name, (counts.get(name) ?? 0) + 1);
  }
  return [...counts.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join(", ");
}

// The invented PII in the claim fixture, split by detector. STRUCTURED values are
// builtin-regex-detectable and must never cross to the model on any lane. The claim
// and policy identifiers are custom types governed by their own always-on rules, so
// they stay out of this hard set. A NER name may cross only when the runtime runs
// without NER, and then only as a reported degradation.
const STRUCTURED_PII = [
  "DE97 9900 0000 0123 4567 89",
  "erika.mustermann@example.de",
  "+49 151 23456789",
] as const;
const NER_PII = ["Erika Mustermann"] as const;

/**
 * Check one string that crosses to the model. A STRUCTURED value crossing is a hard
 * failure on every lane. A name crossing fails only when NER is active; without NER
 * the runtime has no name detector, so the name is a reported degradation, never a
 * silent leak. The one signal is ner_active from guardai_capabilities.
 */
function assertBoundary(text: string, nerActive: boolean, nameNotes: string[]): void {
  const structured = STRUCTURED_PII.filter((value) => text.includes(value));
  if (structured.length > 0) {
    throw new Error(`boundary check failed: structured PII crossed to the model: ${structured.join(", ")}`);
  }
  for (const name of NER_PII.filter((value) => text.includes(value))) {
    if (nerActive) {
      throw new Error(`boundary check failed: the name ${name} crossed to the model while NER is active`);
    }
    console.log(`\n  ! HINWEIS: Der Name ${name} erreichte das Modell, weil dieser Runtime ohne NER laeuft.`);
    if (!nameNotes.includes(name)) nameNotes.push(name);
  }
}

async function main(): Promise<void> {
  const client = new McpClient(resolveServerSpec());
  client.start();

  try {
    const info = await client.initialize();
    const tools = await client.listTools();

    // Preflight through the MCP health tool: the same check an AI client runs.
    let health: HealthResult;
    try {
      health = await client.callTool<HealthResult>("guardai_health", {});
    } catch {
      console.error(`OGuardAI is not reachable at ${GUARDAI_URL}.`);
      console.error("Start it first:  docker compose -f deploy/docker/docker-compose.yml up -d   (from the repo root; see this example's README)");
      process.exit(1);
      return;
    }
    if (health.status === "unhealthy") throw new Error("OGuardAI reports unhealthy");

    let nerActive = true;
    try {
      const caps = await client.callTool<{ ner_active?: unknown }>("guardai_capabilities", {});
      nerActive = caps.ner_active !== false;
    } catch {
      nerActive = true;
    }
    const nameNotes: string[] = [];

    rule(`${COMPANY.name} - Schadenservice-Assistentin "${COMPANY.assistant}" (MCP)`);
    console.log(`MCP server:  ${info.name} v${info.version} (protocol ${info.protocolVersion})`);
    console.log(`Tools:       ${tools.length} verfuegbar`);
    console.log(`OGuardAI:    ${GUARDAI_URL}   Detector: ${health.components?.detector?.message ?? "?"}`);
    console.log(
      `Policy:      ${COMPANY.policy}   Sprache: ${COMPANY.language}   LLM: ${llmMode()}   NER: ${nerActive ? "aktiv" : "aus"}`,
    );

    const email = loadClaimEmail();

    rule("EINGANG (RAW, innerhalb der Vertrauensgrenze)");
    console.log("Der Sachbearbeiter fuegt die Schadenmeldung in den Assistenten ein:");
    console.log(indent(email));

    // 1) TRIAGE. The model asks which entity types are present. No values cross
    //    into its context; detect returns type, span, confidence only.
    rule("MODELL-EBENE 1/4 - guardai_detect (Triage)");
    const detected = await client.callTool<DetectResult>("guardai_detect", {
      text: email,
      language: COMPANY.language,
      policy: COMPANY.policy,
    });
    console.log(`Erkannte Entitaeten (${detected.count}): ${entitySummary(detected.entities)}`);

    // 2) POLICY PREVIEW. How would the policy treat the claimant's identity and
    //    payment data, and does a claimed role change anything?
    rule("MODELL-EBENE 2/4 - guardai_evaluate_policy (Disposition)");
    const asAdjuster = await client.callTool<EvaluateResult>("guardai_evaluate_policy", {
      text: CONTACT_BLOCK,
      policy: COMPANY.policy,
      caller_role: "claims_adjuster",
      output_channel: CHANNELS.adjuster,
    });
    for (const d of asAdjuster.decisions) {
      console.log(`  ${d.entity_type.padEnd(8)} -> ${d.action}, restore=${d.restore_mode ?? "-"}`);
    }
    console.log(
      "\nHinweis: caller_role ist ein Vorschau-Parameter. Der Server bindet die echte",
    );
    console.log(
      "Rolle an die Authentifizierung, nicht an das Feld. Unter dem Dev-Key aendert",
    );
    console.log("kein uebergebener caller_role die Entscheidung: eine Anfrage kann nicht eskalieren.");

    // 3) PROTECT. The model transforms the message. From here it works only on
    //    safe_text; the raw values are sealed in session_state (opaque blob).
    rule("MODELL-EBENE 3/4 - guardai_transform (Schutz)");
    const tf = await client.callTool<TransformResult>("guardai_transform", {
      text: email,
      policy: COMPANY.policy,
      language: COMPANY.language,
    });
    console.log(`entities_count: ${tf.entities_count}   session_state: ${tf.session_state.length} Zeichen`);
    console.log("\nWas das LLM sieht (safe_text, nur Tokens):");
    console.log(indent(tf.safe_text));
    assertBoundary(tf.safe_text, nerActive, nameNotes);

    // 4) DRAFT then CONFIRM. The model drafts on tokens, then calls rehydrate.
    //    The tool returns a resolution count, never the restored text.
    rule("MODELL-EBENE 4/4 - LLM-Entwurf + guardai_rehydrate (Bestaetigung)");
    const draft = await draftReply(tf.safe_text);
    console.log("LLM-Entwurf (noch tokenisiert):");
    console.log(indent(draft));
    assertBoundary(draft, nerActive, nameNotes);

    const ack = await client.callTool<RehydrateAck>("guardai_rehydrate", {
      text: draft,
      session_state: tf.session_state,
      output_channel: CHANNELS.customer,
    });
    console.log(
      `\nrehydrate ack -> resolved=${ack.tokens_resolved} unresolved=[${ack.tokens_unresolved.join(", ")}]`,
    );
    console.log("Der wiederhergestellte Text (mit echten Daten) wird dem Modell NICHT zurueckgegeben.");

    // HOST PLANE. The trusted backend materializes the real outputs out-of-band.
    rule("HOST-EBENE - Materialisierung ueber OGuardAI REST (ausserhalb des Modells)");
    const customer = await materialize(draft, tf.session_state, CHANNELS.customer);
    const adjuster = await materialize(draft, tf.session_state, CHANNELS.adjuster);
    const partner = await materialize(draft, tf.session_state, CHANNELS.partner);
    const audit = await materialize(draft, tf.session_state, CHANNELS.audit);

    console.log(`[customer_email]   -> Brief an die Versicherungsnehmerin:`);
    console.log(indent(customer.restoredText, 4));
    console.log(`\n[internal_summary] -> interne Fallnotiz:`);
    console.log(indent(adjuster.restoredText, 4));
    console.log(`\n[reinsurer_export] -> Extrakt fuer den Rueckversicherer:`);
    console.log(indent(partner.restoredText, 4));
    console.log(`\n[log_safe]         -> SIEM-/Audit-Zeile:`);
    console.log(indent(audit.restoredText, 4));

    // Residual-token guard: never send a customer letter with a dangling token.
    const residual = residualTokens(customer.restoredText);
    if (residual.length > 0) {
      console.log(
        `\n! Kundenbrief zurueckgehalten (unaufgeloeste Tokens: ${residual.join(", ")})`,
      );
    }

    await failClosed(client, tf.session_state);

    rule("FERTIG");
    if (nameNotes.length > 0) {
      console.log(
        "Strukturierte Daten (IBAN, E-Mail, Telefon) blieben in der Vertrauensgrenze. Der Name " +
          `${[...new Set(nameNotes)].join(", ")} erreichte das Modell, weil dieser Runtime ohne NER laeuft.`,
      );
    } else {
      console.log("Das LLM hat zu keinem Zeitpunkt einen echten Namen, eine IBAN oder eine E-Mail gesehen.");
    }
    console.log("Der Kundenbrief und die Fallnotiz entstanden erst auf der Host-Ebene, ausserhalb des Modells.");
  } finally {
    await client.stop();
  }
}

/** Three safety properties, all observed through the MCP tools. */
async function failClosed(client: McpClient, sessionState: string): Promise<void> {
  rule("FAIL-CLOSED (ueber die MCP-Tools beobachtet)");

  // A person token that exists in this session, plus one the model invented.
  const t = await client.callTool<TransformResult>("guardai_transform", {
    text: "Guten Tag, ich bin Frau Erika Mustermann.",
    policy: COMPANY.policy,
    language: COMPANY.language,
  });
  const realToken = t.safe_text.match(/\{\{person:[^}]+\}\}/)?.[0] ?? "{{person:p_001:0000}}";
  const invented = "{{person:p_999:deadbeef0000}}";

  // 1) A tampered session blob: the tool runs but fails, surfaced as isError.
  const tampered = `${sessionState.slice(0, -40)}${"A".repeat(40)}`;
  let tamperAccepted = false;
  try {
    await client.callToolRaw("guardai_rehydrate", {
      text: `Guten Tag ${realToken}.`,
      session_state: tampered,
      output_channel: CHANNELS.customer,
    });
    tamperAccepted = true;
  } catch (err) {
    const label = err instanceof ToolError ? "ToolError (isError)" : String(err);
    console.log(`1) Manipuliertes session_state -> abgelehnt: ${label}`);
  }
  if (tamperAccepted) {
    throw new Error("fail-closed check failed: a tampered session was accepted");
  }

  // 2) An invented token is reported as unresolved, never guessed.
  const ack = await client.callTool<RehydrateAck>("guardai_rehydrate", {
    text: `${realToken} und ${invented} melden sich.`,
    session_state: t.session_state,
    output_channel: CHANNELS.customer,
  });
  console.log(
    `2) Erfundener Token -> resolved=${ack.tokens_resolved} unresolved=[${ack.tokens_unresolved.join(", ")}]`,
  );
  if (!ack.tokens_unresolved.some((t) => t.includes("p_999"))) {
    throw new Error("fail-closed check failed: a forged token was resolved instead of left unresolved");
  }

  // 3) A missing required argument is a protocol-level error (-32602).
  let missingArgAccepted = false;
  try {
    await client.callToolRaw("guardai_transform", {});
    missingArgAccepted = true;
  } catch (err) {
    const label = err instanceof ProtocolError ? `ProtocolError (${err.code})` : String(err);
    console.log(`3) Fehlendes Argument 'text' -> ${label}`);
  }
  if (missingArgAccepted) {
    throw new Error("fail-closed check failed: a tool call missing a required argument was accepted");
  }
}

main().catch((err) => {
  console.error("Demo failed:", err);
  process.exit(1);
});

{
  "mcpServers": {
    "guardai": {
      "command": "node",
      "args": ["/absolute/path/to/apps/mcp-server/dist/index.js"],
      "env": {
        "GUARDAI_URL": "http://localhost:3000",
        "GUARDAI_API_KEY": ""
      }
    }
  }
}