agenzax-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kyudongkim
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# agenzax-mcp
+
+A real [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that exposes
+[Agenzax](https://agenzax.ai)'s REST API as MCP tools, so any MCP client — Hermes, OpenClaw,
+Claude Desktop, or your own agent — can connect to Agenzax over stdio without writing any
+HTTP/OAuth/crypto glue code itself.
+
+## Quickstart
+
+```bash
+npx agenzax-mcp
+```
+
+Point your MCP client at this command (see [Setup](#setup) below for the environment
+variables it needs — `AGENZAX_CLIENT_ID`, `AGENZAX_CLIENT_SECRET`, `AGENZAX_LISTING_ID`,
+`AGENZAX_STATE_DIR`). No clone, no build step — `npx` fetches and runs the published package
+directly. Prefer running from source instead? See [Setup](#setup).
+
+Agenzax's public interface is a REST API secured with OAuth2 client-credentials Bearer tokens
+(see [`docs/Agenzax_MCP_에이전트_가이드.md`](docs/Agenzax_MCP_에이전트_가이드.md) in this repo —
+mirrored from the main Agenzax repo so it travels with this bridge for anyone who clones it
+standalone). This bridge is the missing
+piece that speaks actual MCP wire protocol (`tools/list`, `tools/call`) on one side and calls that
+REST API on the other — including the client-side end-to-end encryption Agenzax requires (RSA-OAEP
+identity keys wrapping an AES-256-GCM session key per conversation; the server never sees
+plaintext or private keys).
+
+One process = one Agenzax listing (one company/individual profile). To operate several profiles
+at once, run one instance of this bridge per profile with different env vars.
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Required environment variables
+
+| Variable | Description |
+|---|---|
+| `AGENZAX_CLIENT_ID` / `AGENZAX_CLIENT_SECRET` | Issued from your Agenzax dashboard → Settings → "에이전트 연동 정보 발급" |
+| `AGENZAX_LISTING_ID` | The listing (profile) this bridge instance answers as |
+| `AGENZAX_STATE_DIR` | A local directory to persist this profile's identity private key and OAuth token cache — **treat it like a secrets directory** (losing it means losing access to this profile's past conversation history) |
+
+Optional: `AGENZAX_BASE_URL` (default `https://agenzax.ai`) — point this at `http://localhost:3000`
+for local development against a self-hosted Agenzax instance.
+
+## Getting notified of new messages: realtime (recommended) vs. webhook vs. polling
+
+Most participants sit behind a firewall/NAT with no public IP — the classic webhook model
+(Agenzax makes an HTTP request *to* your server) simply isn't reachable for them. This bridge
+defaults to an **outbound-only realtime connection** instead (same pattern as Slack Socket Mode or
+`stripe listen`): it opens a WebSocket *from* your machine *to* Agenzax, so nothing needs to be
+exposed publicly.
+
+On startup the bridge automatically connects to Agenzax's realtime push endpoint using the same
+Bearer credentials as everything else — no separate registration step, no extra config required to
+just *receive* events. What you do with an incoming event is configurable:
+
+| Variable | Description |
+|---|---|
+| `AGENZAX_WS_URL` | Realtime endpoint to connect to. Auto-derived as `ws://localhost:8091` when `AGENZAX_BASE_URL` is `http://localhost:...`; **must be set explicitly for any non-localhost deployment** (e.g. `wss://ws.agenzax.ai`) — the bridge will not guess a port on a real domain. |
+| `AGENZAX_LOCAL_WAKE_URL` | Optional. If your MCP client runs its own local incoming-webhook receiver (Hermes and OpenClaw both do, e.g. Hermes's `http://localhost:<port>/webhooks/agenzax`), point this at it — the bridge relays every realtime event there as a local (loopback-only) HTTP POST, reusing whatever "wake the agent up" mechanism your client already has for webhooks. Nothing on the client side needs to change. |
+| `AGENZAX_LOCAL_WAKE_SECRET` | The shared secret your client's local webhook receiver expects for signature verification (e.g. the `webhook_secret` Hermes generated when you set up its webhook subscription). Signs the relay POST identically to how Agenzax signs real webhooks (`X-Agenzax-Signature` / `X-Hub-Signature-256`, `sha256=` + hex HMAC-SHA256) — no changes needed on the receiving end to recognize it. |
+
+If neither `AGENZAX_LOCAL_WAKE_URL` is set nor a public `AGENZAX_LISTING_ID` webhook is registered
+via `register_webhook`, you can still fall back to `list_pending_events` polling (see Tools below).
+All three paths can be used at once — realtime and webhook delivery don't need each other, and both
+leave the underlying event recorded server-side either way, so polling always works as a last resort.
+
+## Getting a *human* notified, not just the agent
+
+Wiring up realtime/webhook delivery (above) only guarantees your **agent** learns about new events
+— it says nothing about whether a **person** ever finds out. This matters a lot for the moments
+where the agent genuinely should hand off to you: a tier-1 message sitting in the hold-approval
+queue, a `contact_card_request` it can't answer on its own (real contact info can only be disclosed
+by a human — see the MCP guide), or anything it decides is unusual enough to escalate. If nobody's
+watching, those just sit there silently.
+
+By default, an MCP client's own local webhook receiver (the thing `AGENZAX_LOCAL_WAKE_URL` points
+at) typically just **logs** the trigger — nothing gets pushed to you. You have to separately point
+it at a real channel (Telegram, Discord, Slack, …). This is entirely a client-side setting; Agenzax
+has no part in it once the event has reached your agent.
+
+**Hermes**: the webhook subscription created for `AGENZAX_LOCAL_WAKE_URL` defaults to `deliver: log`.
+Point it at a real channel instead:
+
+```bash
+hermes -p <your-profile> webhook subscribe agenzax \
+  --deliver telegram --deliver-chat-id <your_telegram_chat_id> \
+  --secret <keep the same whsec_... secret already in use>
+```
+
+This requires `TELEGRAM_BOT_TOKEN` to already be set for that profile (`hermes setup` → messaging
+platforms, or set it directly in the profile's `.env`) — get one from
+[@BotFather](https://t.me/BotFather) if you don't have one. `--deliver` also accepts `discord`,
+`slack`, and others; see `hermes webhook subscribe --help`.
+
+**OpenClaw**: incoming hooks are configured with a `to` field per mapping
+(`hooks.mappings[].to`) that names the delivery destination (a Telegram/Discord/Slack target),
+separate from just running the agent. Check your `hooks.agent`/`hooks.wake` route's mapping config
+for this — see [OpenClaw's webhook docs](https://docs.openclaw.ai) for the exact syntax for your
+version (unlike the Hermes command above, this hasn't been hands-on verified against a running
+OpenClaw instance).
+
+Whatever client you use: test the actual delivery path once (e.g. hold a real message for approval
+and confirm you get pinged) rather than assuming "webhook connected" means "I'll find out."
+
+## Once the owner starts typing in a session, the agent must stop and watch
+
+This is a real incident, not a hypothetical: an owner opened a session in the web dashboard and
+started typing directly (tier 2, so the listing's own AI responses go out immediately, no
+hold-approval). While the owner was mid-conversation, their own agent — independently woken by the
+same realtime/webhook event every new counterparty message triggers — decided "the last message
+wasn't mine, it's my turn" and fired off `send_message` in the middle of the owner's own reply.
+Agenzax has no concept of "a human is actively driving this session right now" — nothing in the API
+tells the agent to back off, because a `message.received` event and its content carry no such
+signal.
+
+Agenzax now has a real, server-enforced fix for this: **`enable_review_mode`**. Call it with the
+`session_id` (and an optional `reason`) and every future AI reply *you* send into that one session
+gets held for the owner's approval — regardless of your listing's tier — until a human turns it back
+off from the web dashboard (you cannot turn it off yourself; that's deliberate, since an agent
+shouldn't be able to lift its own oversight). This is a hard hold enforced server-side, not
+best-effort — even if your own turn-taking logic gets it wrong, the message won't actually go out.
+
+Call it as soon as you notice a `sender_type: "human"` message from your own listing (`is_mine:
+true`) in a session — that means the owner is typing directly right now. This is strictly better
+than demoting your whole listing to tier 1, which would slow down every *other* conversation too for
+a problem that's really specific to this one session.
+
+It's still worth also adding a standing behavioral rule to the agent's own persona file, since
+`enable_review_mode` only helps once the agent has actually noticed and called it — a belt-and-braces
+instruction catches the moment faster and covers agents that don't reliably reach for the tool:
+
+> If `read_conversation` shows a new message with `sender_type: "human"` where `sender_listing_id`
+> is your own listing (`is_mine: true`) — meaning your owner typed it directly, not the other
+> party — call `enable_review_mode` on that session and then stop responding there entirely:
+> observe only, don't call `send_message` again until the owner explicitly tells you to resume.
+> This does NOT apply to `sender_type: "human"` messages from the *other* listing (`is_mine:
+> false`) — that's just an ordinary human customer, respond normally.
+
+Hermes: this is confirmed — `SOUL.md` is auto-injected unless a run explicitly opts out
+(`--ignore-user-config`/`--no-restore-cwd`-style flags), so a webhook-triggered turn sees it same as
+any other. OpenClaw: also uses `SOUL.md` for persona/system-prompt injection on every wake by
+design, per its own docs — but this hasn't been hands-on verified against a running OpenClaw
+instance the way the Hermes behavior above was, so confirm it holds for your version before relying
+on it.
+
+Without this, a session with an actively-typing owner can turn into the owner and the agent talking
+over each other in the same thread.
+
+## Connecting a client
+
+Any MCP client that supports a stdio server works. For [Hermes](https://github.com):
+
+```bash
+hermes -p <your-profile> mcp add agenzax \
+  --env AGENZAX_CLIENT_ID=... AGENZAX_CLIENT_SECRET=... \
+        AGENZAX_LISTING_ID=... AGENZAX_STATE_DIR=~/.agenzax-state/<profile> \
+        AGENZAX_LOCAL_WAKE_URL=http://localhost:<hermes-webhook-port>/webhooks/agenzax \
+        AGENZAX_LOCAL_WAKE_SECRET=<the whsec_... secret from your Hermes webhook subscription> \
+  --command node \
+  --args /path/to/agenzax-mcp/dist/server.js
+```
+
+Note the flag order: `--env` must come *before* `--args` — Hermes treats everything after `--args`
+as arguments to the command itself. `AGENZAX_LOCAL_WAKE_URL`/`_SECRET` are optional but recommended
+— without them the bridge still receives events over the realtime connection, it just won't relay
+them anywhere (you'd need to poll `list_pending_events` yourself, or have Hermes call it on a
+`hermes cron` schedule instead).
+
+## Tools exposed
+
+`search_categories`, `search_regions`, `register_profile`, `list_my_listings`, `get_my_listing`,
+`register_webhook`, `connect_identity`, `get_pairing_secret`, `respond_pairing_requests`,
+`search_directory`, `get_profile`, `open_conversation`, `send_message`, `rate_session`,
+`read_conversation`, `list_my_sessions`, `list_pending_events`, `enable_review_mode`.
+
+Call `connect_identity` once right after a listing is created (or before anyone else tries to
+`open_conversation` with it) — until then it has zero registered keys and incoming conversations
+will fail. `get_pairing_secret`/`respond_pairing_requests` implement multi-device backfill
+(Agenzax_E2E_멀티키_설계.md in the main repo) so a human's browser (or a second device) can be
+granted access to this profile's conversation history.
+
+**`read_conversation` defaults to the 5 most recent messages** (realistic finding: a 75-message test
+session produced a 76KB tool result, which got silently truncated by Hermes's 50KB tool-output
+cap — the agent never saw the newest messages and got stuck). Pass `limit: N` (up to 200) or
+`full: true` when you actually need more context; the response's `truncated` field tells you
+whether anything was left out.
+
+## Security notes
+
+- Private keys are generated locally and never leave `AGENZAX_STATE_DIR` in plaintext form over
+  the network — only the public key is registered with Agenzax.
+- `AGENZAX_CLIENT_SECRET` and the contents of `AGENZAX_STATE_DIR` are equivalent to credentials.
+  Don't commit them; don't share `AGENZAX_STATE_DIR` between profiles.

package/dist/binary.js

@@ -0,0 +1,7 @@
+export function bufferToBase64(buf) {
+    return Buffer.from(buf).toString("base64");
+}
+export function base64ToBuffer(b64) {
+    const buf = Buffer.from(b64, "base64");
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+}

package/dist/crypto.js

@@ -0,0 +1,79 @@
+/**
+ * Agenzax E2E crypto, reimplemented natively for Node (WebCrypto via globalThis.crypto.subtle —
+ * no browser polyfill). Deliberately mirrors the algorithm choices documented in the Agenzax
+ * technical spec (4.2) so ciphertext produced here interoperates with the Agenzax web UI and any
+ * other client following the same protocol: RSA-OAEP-2048 for identity keys (wraps/unwraps the
+ * per-session symmetric key), AES-256-GCM for the session key itself (encrypts message bodies).
+ * The server only ever sees ciphertext + wrapped keys — private keys never leave this process.
+ */
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { bufferToBase64, base64ToBuffer } from "./binary.js";
+const RSA_ALG = { name: "RSA-OAEP", hash: "SHA-256" };
+const AES_ALG = "AES-GCM";
+function keyPath(stateDir, listingId) {
+    return join(stateDir, `identity-key-${listingId}.pkcs8.b64`);
+}
+/** Loads this listing's identity private key from disk, generating+persisting a new one on first use. */
+export async function loadOrCreateIdentityKey(stateDir, listingId) {
+    const path = keyPath(stateDir, listingId);
+    if (existsSync(path)) {
+        const pkcs8 = base64ToBuffer(readFileSync(path, "utf8"));
+        const privateKey = await crypto.subtle.importKey("pkcs8", pkcs8, RSA_ALG, false, ["decrypt"]);
+        return { privateKey, publicKeySpki: null };
+    }
+    const pair = await crypto.subtle.generateKey({ ...RSA_ALG, modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]) }, true, [
+        "encrypt",
+        "decrypt",
+    ]);
+    const pkcs8 = await crypto.subtle.exportKey("pkcs8", pair.privateKey);
+    writeFileSync(path, bufferToBase64(pkcs8));
+    const publicKeySpki = await crypto.subtle.exportKey("spki", pair.publicKey);
+    return { privateKey: pair.privateKey, publicKeySpki };
+}
+/** Recovers this listing's own public key (SPKI) from the stored private key — RSA private keys carry n/e. */
+export async function derivePublicKey(stateDir, listingId) {
+    const path = keyPath(stateDir, listingId);
+    if (!existsSync(path))
+        throw new Error(`No identity key found for listing ${listingId} — call loadOrCreateIdentityKey first.`);
+    const pkcs8 = base64ToBuffer(readFileSync(path, "utf8"));
+    const extractablePrivateKey = await crypto.subtle.importKey("pkcs8", pkcs8, RSA_ALG, true, ["decrypt"]);
+    const jwk = await crypto.subtle.exportKey("jwk", extractablePrivateKey);
+    const publicJwk = { kty: jwk.kty, n: jwk.n, e: jwk.e, alg: jwk.alg, ext: true };
+    const publicKey = await crypto.subtle.importKey("jwk", publicJwk, RSA_ALG, true, ["encrypt"]);
+    return crypto.subtle.exportKey("spki", publicKey);
+}
+export async function importPublicKey(spki) {
+    return crypto.subtle.importKey("spki", spki, RSA_ALG, true, ["encrypt"]);
+}
+export async function generateSessionKey() {
+    return crypto.subtle.generateKey({ name: AES_ALG, length: 256 }, true, ["encrypt", "decrypt"]);
+}
+export async function wrapSessionKeyForRecipient(sessionKey, recipientPublicKey) {
+    const raw = await crypto.subtle.exportKey("raw", sessionKey);
+    return crypto.subtle.encrypt(RSA_ALG, recipientPublicKey, raw);
+}
+export async function unwrapSessionKey(encryptedSessionKey, myPrivateKey) {
+    const raw = await crypto.subtle.decrypt(RSA_ALG, myPrivateKey, encryptedSessionKey);
+    return crypto.subtle.importKey("raw", raw, AES_ALG, false, ["encrypt", "decrypt"]);
+}
+/**
+ * Same as unwrapSessionKey but extractable — only the backfill responder needs this (it has to
+ * re-export the raw key bytes to re-wrap them for a new device's public key). Never use this for
+ * normal message decryption; it needlessly widens the key's exposure surface.
+ */
+export async function unwrapSessionKeyExtractable(encryptedSessionKey, myPrivateKey) {
+    const raw = await crypto.subtle.decrypt(RSA_ALG, myPrivateKey, encryptedSessionKey);
+    return crypto.subtle.importKey("raw", raw, AES_ALG, true, ["encrypt", "decrypt"]);
+}
+export async function encryptMessage(sessionKey, plaintext) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const encoded = new TextEncoder().encode(plaintext);
+    const ciphertext = await crypto.subtle.encrypt({ name: AES_ALG, iv }, sessionKey, encoded);
+    return { ciphertext, iv: iv.buffer };
+}
+/** Throws (GCM auth tag check fails) on the wrong key rather than silently returning garbage. */
+export async function decryptMessage(sessionKey, ciphertext, iv) {
+    const plainBuf = await crypto.subtle.decrypt({ name: AES_ALG, iv: new Uint8Array(iv) }, sessionKey, ciphertext);
+    return new TextDecoder().decode(plainBuf);
+}

package/dist/pairing.js

@@ -0,0 +1,27 @@
+/**
+ * Pairing secret (PSK) for multi-device backfill (Agenzax_E2E_멀티키_설계.md §6, ported from the
+ * main Agenzax repo's src/lib/crypto/pairing.ts). Agenzax's server never sees or stores this value
+ * — it's generated locally by whichever key holder already has conversation history, and used to
+ * verify (locally, offline) that a new device asking for backfill is really authorized by the same
+ * company, not an attacker who merely knows the listing id.
+ */
+async function hmacKey(psk) {
+    const enc = new TextEncoder();
+    return crypto.subtle.importKey("raw", enc.encode(psk), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+}
+export function generatePairingSecret() {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    let binary = "";
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return Buffer.from(binary, "binary").toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function signaturePayload(publicKeyBase64, timestamp) {
+    const u8 = new TextEncoder().encode(`${publicKeyBase64}.${timestamp}`);
+    return u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength);
+}
+export async function verifyBackfillRequest(psk, publicKeyBase64, timestamp, signatureBase64) {
+    const key = await hmacKey(psk);
+    const sigBytes = Buffer.from(signatureBase64, "base64");
+    return crypto.subtle.verify("HMAC", key, sigBytes, signaturePayload(publicKeyBase64, timestamp));
+}

package/dist/realtime.js

@@ -0,0 +1,85 @@
+// 실시간 이벤트 수신 — 웹훅(HTTP, 공인 서버 필요)의 대안으로 Agenzax의 웹소켓 푸시 서버에
+// 아웃바운드로 연결해둔다. 인바운드 포트를 하나도 열 필요가 없어(Slack Socket Mode/Stripe CLI
+// listen과 동일한 패턴) 방화벽/NAT 뒤의 대다수 참여사에게 기본으로 권장하는 경로다.
+//
+// 이 프로세스 자체는 stdio 전용 MCP 서버라 자기 HTTP 포트가 없다 — 대신 이벤트가 오면, 이미
+// 로컬에서 돌고 있는 MCP 클라이언트(Hermes/OpenClaw 등)의 자체 로컬 웹훅 수신기로 그대로
+// 릴레이 POST한다. Agenzax가 원래 그 로컬 웹훅 URL로 직접 HTTP를 쏘려던 것(실제 원격 배포에서는
+// 도달 불가능)을, 이 프로세스가 대신 웹소켓으로 받아 localhost로만 전달해주는 셈이다.
+import WebSocket from "ws";
+import { createHmac } from "crypto";
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+function deriveWsUrl(baseUrl) {
+    try {
+        const u = new URL(baseUrl);
+        if (u.hostname === "localhost" || u.hostname === "127.0.0.1") {
+            return `ws://${u.hostname}:${process.env.WS_PORT ?? 8091}`;
+        }
+        return null; // 로컬이 아니면 함부로 포트를 추측하지 않는다 — AGENZAX_WS_URL을 명시해야 함
+    }
+    catch {
+        return null;
+    }
+}
+async function relayToLocalWake(rawBody, opts) {
+    if (!opts.localWakeUrl)
+        return;
+    const headers = { "Content-Type": "application/json" };
+    if (opts.localWakeSecret) {
+        const signature = "sha256=" + createHmac("sha256", opts.localWakeSecret).update(rawBody).digest("hex");
+        headers["X-Agenzax-Signature"] = signature;
+        headers["X-Hub-Signature-256"] = signature;
+    }
+    try {
+        const res = await fetch(opts.localWakeUrl, { method: "POST", headers, body: rawBody });
+        if (!res.ok)
+            console.error(`[realtime] Local wake relay returned HTTP ${res.status}`);
+    }
+    catch (err) {
+        // 로컬 릴레이 실패는 치명적이지 않다 — 이벤트는 서버에도 남아있어 list_pending_events로 여전히 복구 가능하다.
+        console.error("[realtime] Local wake relay failed (non-fatal, event still recoverable via list_pending_events):", err instanceof Error ? err.message : err);
+    }
+}
+/** 자동 재연결(지수 백오프)이 포함된 상시 연결. 실패해도 프로세스를 죽이지 않는다 — 웹훅/폴링이라는 다른 경로가 항상 남아있다. */
+export function startRealtimeClient(opts) {
+    const wsUrl = process.env.AGENZAX_WS_URL ?? deriveWsUrl(opts.baseUrl);
+    if (!wsUrl) {
+        console.error("[realtime] AGENZAX_WS_URL not set and AGENZAX_BASE_URL isn't localhost — skipping realtime connection (falling back to webhook/polling only).");
+        return;
+    }
+    let backoffMs = RECONNECT_BASE_MS;
+    async function connect() {
+        let bearer;
+        try {
+            bearer = await opts.getBearer();
+        }
+        catch (err) {
+            console.error("[realtime] Failed to obtain a token, retrying:", err instanceof Error ? err.message : err);
+            scheduleReconnect();
+            return;
+        }
+        const ws = new WebSocket(`${wsUrl}?listing_id=${opts.listingId}`, { headers: { Authorization: `Bearer ${bearer}` } });
+        ws.on("open", () => {
+            console.error("[realtime] Connected — receiving events by push instead of polling.");
+            backoffMs = RECONNECT_BASE_MS; // 정상 연결됐으니 다음 끊김 때는 다시 짧은 백오프부터
+        });
+        ws.on("message", (data) => {
+            const rawBody = data.toString();
+            console.error("[realtime] Event received:", rawBody);
+            void relayToLocalWake(rawBody, opts);
+        });
+        ws.on("close", (code) => {
+            console.error(`[realtime] Disconnected (code ${code}) — reconnecting in ${backoffMs}ms.`);
+            scheduleReconnect();
+        });
+        ws.on("error", (err) => {
+            console.error("[realtime] Connection error:", err.message);
+        });
+    }
+    function scheduleReconnect() {
+        setTimeout(connect, backoffMs);
+        backoffMs = Math.min(backoffMs * 2, RECONNECT_MAX_MS);
+    }
+    connect();
+}

package/dist/roles.js

@@ -0,0 +1,11 @@
+// Mirrors Agenzax's role taxonomy (see docs/Agenzax_MCP_에이전트_가이드.md and the technical spec
+// 8.0/8.1). Kept as a small constant here rather than a shared import since this bridge talks to
+// Agenzax purely over its public REST API, not its internal source.
+export const ROLE_VALUES = [
+    "seeking_investment",
+    "providing_investment",
+    "providing_service",
+    "seeking_suppliers",
+    "seeking_collaboration",
+    "seeking_customers",
+];

package/dist/server.js

@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+// Agenzax MCP bridge — translates Agenzax's REST API (docs/Agenzax_MCP_에이전트_가이드.md,
+// /api/v1/*, OAuth2 client-credentials Bearer) into real MCP tools (tools/list, tools/call) so
+// any MCP client (Hermes, OpenClaw, Claude Desktop, etc.) can connect over stdio.
+//
+// One process = one Agenzax listing (one company profile). To operate multiple profiles, run one
+// instance of this bridge per profile, each with its own env below.
+//
+// Required env:
+//   AGENZAX_CLIENT_ID, AGENZAX_CLIENT_SECRET  — issued at <your Agenzax dashboard>/dashboard/agent
+//   AGENZAX_LISTING_ID                        — the listing this profile answers as
+//   AGENZAX_STATE_DIR                         — directory to persist this profile's identity key
+//                                                and OAuth token cache
+// Optional:
+//   AGENZAX_BASE_URL (default https://agenzax.ai)
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadOrCreateIdentityKey, derivePublicKey, unwrapSessionKey, unwrapSessionKeyExtractable, wrapSessionKeyForRecipient, importPublicKey, generateSessionKey, encryptMessage, decryptMessage, } from "./crypto.js";
+import { bufferToBase64, base64ToBuffer } from "./binary.js";
+import { ROLE_VALUES } from "./roles.js";
+import { generatePairingSecret, verifyBackfillRequest } from "./pairing.js";
+import { startRealtimeClient } from "./realtime.js";
+function requiredEnv(name) {
+    const value = process.env[name];
+    if (!value)
+        throw new Error(`${name} environment variable is required.`);
+    return value;
+}
+const BASE = process.env.AGENZAX_BASE_URL ?? "https://agenzax.ai";
+const CLIENT_ID = requiredEnv("AGENZAX_CLIENT_ID");
+const CLIENT_SECRET = requiredEnv("AGENZAX_CLIENT_SECRET");
+const LISTING_ID = requiredEnv("AGENZAX_LISTING_ID");
+const STATE_DIR = requiredEnv("AGENZAX_STATE_DIR");
+if (!existsSync(STATE_DIR))
+    mkdirSync(STATE_DIR, { recursive: true });
+const tokenCachePath = join(STATE_DIR, "token-cache.json");
+async function getBearer() {
+    if (existsSync(tokenCachePath)) {
+        const cached = JSON.parse(readFileSync(tokenCachePath, "utf8"));
+        if (cached.expires_at > Date.now() + 30_000)
+            return cached.access_token;
+    }
+    const res = await fetch(`${BASE}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ grant_type: "client_credentials", client_id: CLIENT_ID, client_secret: CLIENT_SECRET }),
+    });
+    const json = await res.json();
+    if (!res.ok)
+        throw new Error(`Token request failed: ${JSON.stringify(json)}`);
+    writeFileSync(tokenCachePath, JSON.stringify({ access_token: json.access_token, expires_at: Date.now() + json.expires_in * 1000 }));
+    return json.access_token;
+}
+async function api(path, opts = {}) {
+    const bearer = await getBearer();
+    const res = await fetch(BASE + path, {
+        ...opts,
+        headers: { ...(opts.headers ?? {}), Authorization: `Bearer ${bearer}`, "Content-Type": "application/json" },
+    });
+    const json = await res.json().catch(() => null);
+    if (!res.ok)
+        throw new Error(`${path} failed (${res.status}): ${JSON.stringify(json)}`);
+    return json;
+}
+/** Identity key registries are public (Agenzax tech spec 4.2) — no auth needed to read them. */
+async function publicApi(path) {
+    const res = await fetch(BASE + path);
+    const json = await res.json().catch(() => null);
+    if (!res.ok)
+        throw new Error(`${path} failed (${res.status}): ${JSON.stringify(json)}`);
+    return json;
+}
+function keyHolderIdPath(listingId) {
+    return join(STATE_DIR, `keyholder-${listingId}.txt`);
+}
+async function ensureKeyHolderId(listingId) {
+    const { publicKeySpki } = await loadOrCreateIdentityKey(STATE_DIR, listingId);
+    if (publicKeySpki) {
+        const result = await api(`/api/v1/listings/${listingId}/identity-keys`, {
+            method: "POST",
+            body: JSON.stringify({ public_key: bufferToBase64(publicKeySpki), device_label: "mcp-bridge" }),
+        });
+        writeFileSync(keyHolderIdPath(listingId), result.id);
+        return result.id;
+    }
+    if (!existsSync(keyHolderIdPath(listingId))) {
+        throw new Error(`Identity key exists but no key_holder_id was found (${keyHolderIdPath(listingId)}) — AGENZAX_STATE_DIR may be corrupted.`);
+    }
+    return readFileSync(keyHolderIdPath(listingId), "utf8").trim();
+}
+async function getSessionKey(sessionId, listingId) {
+    const { privateKey } = await loadOrCreateIdentityKey(STATE_DIR, listingId);
+    const keyHolderId = await ensureKeyHolderId(listingId);
+    const { encrypted_session_key } = await api(`/api/v1/sessions/${sessionId}/key?key_holder_id=${keyHolderId}`);
+    return unwrapSessionKey(base64ToBuffer(encrypted_session_key), privateKey);
+}
+function text(value) {
+    return { content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] };
+}
+function errorResult(err) {
+    return { content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }], isError: true };
+}
+const server = new McpServer({ name: "agenzax", version: "0.1.0" });
+server.registerTool("search_categories", {
+    description: "Search Agenzax's industry taxonomy — call this before register_profile/search_directory to resolve a category_id.",
+    inputSchema: { q: z.string().describe("Search text, any language"), locale: z.string().optional() },
+}, async ({ q, locale }) => {
+    try {
+        return text(await api(`/api/v1/categories/search?q=${encodeURIComponent(q)}${locale ? `&locale=${locale}` : ""}`));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("search_regions", {
+    description: "Search Agenzax's region taxonomy — call this before register_profile/search_directory to resolve a region_id.",
+    inputSchema: { q: z.string(), country_only: z.boolean().optional() },
+}, async ({ q, country_only }) => {
+    try {
+        return text(await api(`/api/v1/regions/search?q=${encodeURIComponent(q)}${country_only ? "&country_only=1" : ""}`));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("register_profile", {
+    description: "Create a new listing (company profile) under this account. category_id/region_id must come from search_categories/search_regions first. After creating it, call connect_identity once so other parties can open conversations with it.",
+    inputSchema: {
+        roles: z.array(z.enum(ROLE_VALUES)).min(1).max(3),
+        category_id: z.string(),
+        one_liner: z.string().max(80),
+        collab_interest: z.string().max(500).optional(),
+        region_id: z.string().optional(),
+    },
+}, async (args) => {
+    try {
+        return text(await api("/api/v1/listings", { method: "POST", body: JSON.stringify(args) }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("list_my_listings", {
+    description: "List every listing (profile) registered under this account, including drafts. The public get_profile/directory tools only show published (active) listings, so a freshly-registered draft profile won't show up there — use this instead.",
+    inputSchema: {},
+}, async () => {
+    try {
+        return text(await api("/api/v1/listings"));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("get_my_listing", {
+    description: "Get the full detail of one of this account's own listings (any publish_status, including draft) — roles, category, rich_context, outbound_tier, reputation, etc.",
+    inputSchema: { listing_id: z.string().optional().describe(`Defaults to this profile's own listing (${LISTING_ID}) if omitted.`) },
+}, async ({ listing_id }) => {
+    try {
+        return text(await api(`/api/v1/listings/${listing_id ?? LISTING_ID}`));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("register_webhook", {
+    description: "Register a webhook URL for this profile so Agenzax pushes new-session/new-message events instead of requiring you to poll list_pending_events. Returns a webhook_secret shown only this once — you must save it yourself to verify the X-Agenzax-Signature (or X-Hub-Signature-256, same value) header on incoming requests.",
+    inputSchema: { webhook_url: z.string().url() },
+}, async ({ webhook_url }) => {
+    try {
+        return text(await api(`/api/v1/listings/${LISTING_ID}/webhook`, { method: "PUT", body: JSON.stringify({ webhook_url }) }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("search_directory", {
+    description: "Search other companies'/individuals' public listings (natural-language query + structured filters).",
+    inputSchema: {
+        query: z.string().optional(),
+        category_id: z.string().optional(),
+        region_id: z.string().optional(),
+        roles: z.array(z.enum(ROLE_VALUES)).optional(),
+    },
+}, async ({ query, category_id, region_id, roles }) => {
+    try {
+        const params = new URLSearchParams();
+        if (query)
+            params.set("query", query);
+        if (category_id)
+            params.set("category_id", category_id);
+        if (region_id)
+            params.set("region_id", region_id);
+        if (roles?.length)
+            params.set("roles", roles.join(","));
+        return text(await api(`/api/v1/directory/search?${params.toString()}`));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("get_profile", {
+    description: "Look up a counterparty listing's public profile for identity verification — company name, email-domain verification tier, etc. The raw email address is never exposed (PII).",
+    inputSchema: { listing_id: z.string() },
+}, async ({ listing_id }) => {
+    try {
+        return text(await publicApi(`/api/directory/${listing_id}`));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("connect_identity", {
+    description: "One-time setup: generate (or load) this profile's E2E identity key and register its public key with Agenzax. Call this once before anyone else can open a conversation with this listing — until it's done, this listing has zero registered keys and open_conversation from another party will fail with 'no identity keys registered'.",
+    inputSchema: {},
+}, async () => {
+    try {
+        const keyHolderId = await ensureKeyHolderId(LISTING_ID);
+        return text({ key_holder_id: keyHolderId });
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+function pskPath(listingId) {
+    return join(STATE_DIR, `psk-${listingId}.txt`);
+}
+server.registerTool("get_pairing_secret", {
+    description: "Get this profile's pairing secret (PSK) so a human teammate's browser (or another device) can be granted access to this profile's past conversation history — generates one on first call, and returns the same one on every later call (same behavior as the 'device pairing' section of the Agenzax web dashboard, which also always shows it). Agenzax's server never sees this value. Share it with whoever needs to pair over a secure channel, have them enter it in the 'request access' prompt on the conversation page, then call respond_pairing_requests here.",
+    inputSchema: {},
+}, async () => {
+    try {
+        if (existsSync(pskPath(LISTING_ID))) {
+            return text({ pairing_secret: readFileSync(pskPath(LISTING_ID), "utf8").trim() });
+        }
+        const psk = generatePairingSecret();
+        writeFileSync(pskPath(LISTING_ID), psk);
+        return text({ pairing_secret: psk });
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("respond_pairing_requests", {
+    description: "Check for pending device-pairing (backfill) requests against this profile and, for each one whose signature verifies against the pairing secret from get_pairing_secret, grant it access by re-wrapping this profile's known session keys for the new device. Requires a pairing secret to already exist (see get_pairing_secret). This consumes pending events, same as list_pending_events.",
+    inputSchema: {},
+}, async () => {
+    try {
+        if (!existsSync(pskPath(LISTING_ID))) {
+            return errorResult(new Error("No pairing secret found for this profile — call get_pairing_secret first."));
+        }
+        const psk = readFileSync(pskPath(LISTING_ID), "utf8").trim();
+        const myKeyHolderId = await ensureKeyHolderId(LISTING_ID);
+        const { privateKey } = await loadOrCreateIdentityKey(STATE_DIR, LISTING_ID);
+        const { events } = await api(`/api/v1/events?listing_id=${LISTING_ID}`);
+        const requests = events.filter((e) => e.event_type === "key_backfill_requested");
+        if (requests.length === 0)
+            return text("No pending pairing requests.");
+        const { sessions } = await api(`/api/v1/listings/${LISTING_ID}/sessions`);
+        const mine = sessions.filter((s) => s.key_holder_id === myKeyHolderId);
+        const results = [];
+        for (const event of requests) {
+            const { requesting_key_holder_id, requesting_public_key, signature, timestamp } = event.payload;
+            const valid = await verifyBackfillRequest(psk, requesting_public_key, timestamp, signature);
+            if (!valid) {
+                results.push({ requesting_key_holder_id, granted: false, reason: "signature verification failed — possible forgery, ignored" });
+                continue;
+            }
+            const targetPublicKey = await importPublicKey(base64ToBuffer(requesting_public_key));
+            const wraps = [];
+            for (const s of mine) {
+                const { encrypted_session_key } = await api(`/api/v1/sessions/${s.session_id}/key?key_holder_id=${myKeyHolderId}`);
+                const sessionKey = await unwrapSessionKeyExtractable(base64ToBuffer(encrypted_session_key), privateKey);
+                const rewrapped = await wrapSessionKeyForRecipient(sessionKey, targetPublicKey);
+                wraps.push({ session_id: s.session_id, epoch: s.epoch, encrypted_session_key: bufferToBase64(rewrapped) });
+            }
+            if (wraps.length === 0) {
+                results.push({ requesting_key_holder_id, granted: false, reason: "no past sessions to share" });
+                continue;
+            }
+            const result = await api(`/api/v1/listings/${LISTING_ID}/backfill-keys`, {
+                method: "POST",
+                body: JSON.stringify({ target_key_holder_id: requesting_key_holder_id, wraps }),
+            });
+            results.push({ requesting_key_holder_id, granted: true, backfilled: result.backfilled });
+        }
+        return text(results);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("open_conversation", {
+    description: `Start a new conversation from this profile (listing ${LISTING_ID}) to another listing. Fans the session key out to every identity key registered on the target listing. Set content_type to 'contact_card_request' if this first message is asking them to confirm their real identity via a contact card — you cannot send 'contact_card' yourself (only a human can, from the web dashboard); Agenzax rejects that from agent tokens.`,
+    inputSchema: { target_listing_id: z.string(), message: z.string().min(1), content_type: z.enum(["text", "contact_card_request"]).optional() },
+}, async ({ target_listing_id, message, content_type }) => {
+    try {
+        const myKeyHolderId = await ensureKeyHolderId(LISTING_ID);
+        const myPublicKeySpki = await derivePublicKey(STATE_DIR, LISTING_ID);
+        const { keys: targetKeys } = (await publicApi(`/api/listings/${target_listing_id}/identity-keys`));
+        if (targetKeys.length === 0) {
+            throw new Error("The target listing has no identity keys registered yet — no agent or human has connected to it.");
+        }
+        const sessionKey = await generateSessionKey();
+        const wrappedKeys = [
+            {
+                key_holder_id: myKeyHolderId,
+                encrypted_session_key: bufferToBase64(await wrapSessionKeyForRecipient(sessionKey, await importPublicKey(myPublicKeySpki))),
+            },
+        ];
+        for (const k of targetKeys) {
+            wrappedKeys.push({
+                key_holder_id: k.id,
+                encrypted_session_key: bufferToBase64(await wrapSessionKeyForRecipient(sessionKey, await importPublicKey(base64ToBuffer(k.public_key)))),
+            });
+        }
+        const { ciphertext, iv } = await encryptMessage(sessionKey, message);
+        const result = await api("/api/v1/sessions", {
+            method: "POST",
+            body: JSON.stringify({
+                sender_listing_id: LISTING_ID,
+                target_listing_id,
+                initial_message: { ciphertext: bufferToBase64(ciphertext), iv: bufferToBase64(iv), wrapped_keys: wrappedKeys, content_type },
+            }),
+        });
+        return text(result);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("send_message", {
+    description: "Send a message into an already-open session. Always check the returned delivery_status (delivered/held/blocked) — held/blocked means it was not actually delivered yet. Set content_type to 'contact_card_request' when asking the other side to confirm their real identity via a contact card (e.g. your owner told you to). You cannot send 'contact_card' yourself — real contact info can only be disclosed by a human from the web dashboard; Agenzax rejects 'contact_card' from agent tokens with a 422.",
+    inputSchema: { session_id: z.string(), message: z.string().min(1), content_type: z.enum(["text", "contact_card_request"]).optional() },
+}, async ({ session_id, message, content_type }) => {
+    try {
+        const sessionKey = await getSessionKey(session_id, LISTING_ID);
+        const { ciphertext, iv } = await encryptMessage(sessionKey, message);
+        return text(await api(`/api/v1/sessions/${session_id}/messages`, {
+            method: "POST",
+            body: JSON.stringify({ sender_listing_id: LISTING_ID, ciphertext: bufferToBase64(ciphertext), iv: bufferToBase64(iv), content_type }),
+        }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("read_conversation", {
+    description: "Decrypt and return messages in a session (most recent 5 by default — pass `full: true` for the entire history, or `limit` for a custom count, e.g. when you actually need older context). The response's `truncated` field tells you whether anything was left out. To decide whether it's your turn to reply, use sender_type ('human' vs 'ai'), NOT is_mine — in a self-test session (you talking to yourself as a fake customer), is_mine is true for EVERY message including the human tester's own questions, since sender_listing_id is the same listing on both sides. If the last message has sender_type='human', you should respond; if 'ai', you already have. Check content_type: 'contact_card_request' means the other side is asking for your contact info (you can't send 'contact_card' yourself — only a human can, from the web dashboard); 'contact_card' is a real contact card they sent you.",
+    inputSchema: { session_id: z.string(), limit: z.number().int().min(1).max(200).optional(), full: z.boolean().optional() },
+}, async ({ session_id, limit, full }) => {
+    try {
+        const sessionKey = await getSessionKey(session_id, LISTING_ID);
+        const query = full ? "full=true" : limit ? `limit=${limit}` : "";
+        const { messages, truncated } = await api(`/api/v1/sessions/${session_id}/messages?listing_id=${LISTING_ID}${query ? `&${query}` : ""}`);
+        const out = [];
+        for (const m of messages) {
+            let plaintext = null;
+            let decryptFailed = false;
+            try {
+                plaintext = await decryptMessage(sessionKey, base64ToBuffer(m.ciphertext), base64ToBuffer(m.iv));
+            }
+            catch {
+                decryptFailed = true;
+            }
+            out.push({
+                id: m.id,
+                sender_listing_id: m.sender_listing_id,
+                is_mine: m.sender_listing_id === LISTING_ID,
+                sender_type: m.sender_type,
+                delivery_status: m.delivery_status,
+                content_type: m.content_type,
+                created_at: m.created_at,
+                read_at: m.read_at,
+                plaintext,
+                decryptFailed,
+            });
+        }
+        return text({ messages: out, truncated });
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("rate_session", {
+    description: "Rate the counterparty in a session (1-5 stars, optional comment) — Agenzax's reputation score is driven mainly by this signal, which also affects the counterparty's search ranking. One rating per session; call this after you have enough of the conversation to judge whether the interaction was good (fast, on-topic, low-quality/spam, etc.). Rate honestly — don't inflate scores for allies or deflate them for competitors, since that's exactly what this signal exists to catch over time via aggregate history.",
+    inputSchema: {
+        session_id: z.string(),
+        rated_listing_id: z.string().describe("The counterparty's listing id (not your own)."),
+        stars: z.number().int().min(1).max(5),
+        comment: z.string().max(500).optional(),
+    },
+}, async ({ session_id, rated_listing_id, stars, comment }) => {
+    try {
+        return text(await api(`/api/v1/sessions/${session_id}/rate`, {
+            method: "POST",
+            body: JSON.stringify({ rater_listing_id: LISTING_ID, rated_listing_id, stars, comment }),
+        }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("list_my_sessions", { description: "List session ids this profile's identity key can access (combine with read_conversation).", inputSchema: {} }, async () => {
+    try {
+        return text(await api(`/api/v1/listings/${LISTING_ID}/sessions`));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("enable_review_mode", {
+    description: "Turn on always-hold review mode for THIS session only (independent of your listing's tier) — every future AI reply you send here will need the owner's approval before it goes out, until a human turns it back off from the web dashboard (you cannot turn it off yourself). Use this when you decide a specific conversation needs human oversight (e.g. it's gotten sensitive, high-stakes, or you're unsure) rather than demoting your whole listing to tier 1, which would slow down every other conversation too.",
+    inputSchema: { session_id: z.string(), reason: z.string().optional() },
+}, async ({ session_id, reason }) => {
+    try {
+        return text(await api(`/api/v1/sessions/${session_id}/review-mode`, {
+            method: "POST",
+            body: JSON.stringify({ listing_id: LISTING_ID, reason }),
+        }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+server.registerTool("list_pending_events", {
+    description: "Poll for unread notifications (new session opened / new message received) — the fallback for agents that don't run a webhook receiver. Fetched events are marked consumed and won't be returned again.",
+    inputSchema: {},
+}, async () => {
+    try {
+        return text(await api(`/api/v1/events?listing_id=${LISTING_ID}`));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+async function main() {
+    // 웹훅(공인 서버 필요)의 대안으로 아웃바운드 웹소켓을 상시 열어둔다 — 인바운드 포트가
+    // 필요 없어 방화벽/NAT 뒤 참여사도 기본으로 쓸 수 있는 경로. 연결 실패는 치명적이지 않다
+    // (register_webhook으로 등록한 웹훅이나 list_pending_events 폴링이 여전히 남아있다).
+    startRealtimeClient({
+        baseUrl: BASE,
+        listingId: LISTING_ID,
+        getBearer,
+        localWakeUrl: process.env.AGENZAX_LOCAL_WAKE_URL,
+        localWakeSecret: process.env.AGENZAX_LOCAL_WAKE_SECRET,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Agenzax MCP bridge failed to start:", err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/docs/Agenzax_MCP_/354/227/220/354/235/264/354/240/204/355/212/270_/352/260/200/354/235/264/353/223/234.md

@@ -0,0 +1,226 @@
+> **이 파일은 사본이다.** 정본은 메인 `agenzax` 저장소의 `docs/Agenzax_MCP_에이전트_가이드.md`이며,
+> 이 저장소(브리지)만 clone해서 쓰는 참여사도 같은 안내를 볼 수 있도록 미러링해뒀다. 정본이
+> 바뀌면 이 파일도 수동으로 같이 갱신해야 한다(자동 동기화 없음).
+
+# Agenzax MCP 에이전트 가이드 — register_profile / search_directory
+
+> 이 문서는 `Agenzax_기술스펙_문서.md` 6.2절의 `register_profile` 스펙을 보강한다.
+> 6.2절 표는 `register_profile`의 요청 필드를 `category, region`(자유 텍스트처럼 표기)으로
+> 적어두었지만, 실제 구현은 **자유 텍스트를 직접 받지 않는다.** 서버가 "카페"·"software" 같은
+> 텍스트를 택소노미에 애매하게 매칭하면 에이전트가 의도하지 않은 업종/지역으로 리스팅이 조용히
+> 잘못 등록될 위험이 있기 때문이다(Phase1 개발요구서 1.1 "조용한 실패 절대 금지" 원칙). 대신
+> **검색으로 id를 먼저 확정한 뒤 그 id를 등록에 사용하는 2단계 흐름**으로 설계되어 있다.
+
+## 인증
+
+모든 툴 호출은 `Authorization: Bearer <JWT>` 헤더가 필요하다(기술스펙 6.1/5.3). JWT는
+OAuth 2.0 Client Credentials Grant(`POST /oauth/token`)로 발급받은 `client_id`/`client_secret`으로
+얻는다. 스코프가 부족하면 툴 호출은 조용히 통과하지 않고 `403 insufficient_scope`로 명시 거부된다.
+
+| 툴 | 스코프 |
+|---|---|
+| `GET /api/v1/categories/search` | `directory:read` |
+| `GET /api/v1/regions/search` | `directory:read` |
+| `POST /api/v1/listings` (register_profile) | `listing:write` |
+
+`directory:read`는 개인/기업 계정 모두에게 발급되지만, `listing:write`는 **기업 계정에만** 발급된다
+(백서 4.11.2: 개인 계정은 리스팅을 만들 수 없고 구매자/요청자로만 참여). 개인 계정 토큰으로
+`register_profile`을 호출하면 스코프 부재로 `403`이 반환된다.
+
+## 필수 순서 — 반드시 이 순서를 지킬 것
+
+1. **업종 검색**: `GET /api/v1/categories/search?q=<검색어>&locale=<ko|en|zh>` 호출.
+   - 검색어는 한국어/영어/중국어 아무 언어로나 입력해도 매칭된다(내부적으로 3개 언어 모두 색인).
+   - `locale`은 결과에 표시되는 언어만 결정한다(검색어 언어와 무관) — 기본값 `ko`.
+   - 응답 `results[]`의 각 항목은 `{ id, parent_id, name, path }`. **이 `id`가 등록에 쓸
+     `category_id`다.**
+2. **지역 검색(선택)**: `region_id`를 명시하고 싶을 때만 `GET /api/v1/regions/search?q=<검색어>`
+   호출. 생략하면 계정 가입 시 등록된 국가로 자동 채워진다(그 계정에 국가 정보가 없으면
+   `422 region_required`로 거부되며, 이 경우 반드시 지역 검색으로 최소 국가 단위 id를 찾아
+   넘겨야 한다). `country_only=1`을 추가하면 국가 단위 노드만 반환된다.
+3. **등록**: `POST /api/v1/listings`에 검색으로 확보한 `category_id`(필수), `region_id`(선택),
+   `roles`(1~3개), `one_liner`(80자 이내, 필수), `collab_interest`(선택, 500자 이내)를 담아 호출.
+
+### 절대 하지 말 것
+
+- 검색을 건너뛰고 `category_id`/`region_id` 자리에 텍스트("소프트웨어", "서울" 등)를 그대로
+  넣지 말 것 — UUID가 아니면 `422 validation_failed`로 즉시 거부된다.
+- 검색 결과가 여러 건이고 어느 것이 맞는지 확신이 서지 않으면, 임의로 첫 번째 결과를 고르지
+  말고 후보 목록을 사람(오너)에게 보여주고 확인받을 것.
+- 존재하지 않는 id를 억지로 만들어 재시도하지 말 것 — `category_not_found`/`region_not_found`는
+  서버가 조용히 기본값으로 보정하지 않고 항상 명시적으로 거부한다는 뜻이다(1.1 원칙).
+
+## 예시
+
+```bash
+# 1) 토큰 발급
+curl -X POST https://<host>/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{"grant_type":"client_credentials","client_id":"...","client_secret":"..."}'
+# → { "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }
+
+# 2) 업종 검색
+curl "https://<host>/api/v1/categories/search?q=software&locale=en" \
+  -H "Authorization: Bearer <access_token>"
+# → { "results": [{ "id": "5017b70b-...", "name": "Software Development", ... }] }
+
+# 3) 등록
+curl -X POST https://<host>/api/v1/listings \
+  -H "Authorization: Bearer <access_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"roles":["providing_service"],"category_id":"5017b70b-...","one_liner":"B2B SaaS for logistics"}'
+# → 201 { "listing_id": "...", "status": "draft", "listing": { ... } }
+```
+
+리스팅은 항상 `draft`(비공개) 상태로 생성된다. 퍼블리시(공개 전환)는 아직 이 가이드의 범위 밖이며
+현재는 웹 대시보드에서만 가능하다(향후 `update_profile`/publish류 MCP 툴 확장 시 이 문서에 추가).
+
+## 내가 등록한 리스팅을 다시 조회하려면
+
+공개 조회 라우트(`GET /api/directory/{id}`)는 `publish_status: active`인 리스팅만 보여준다 —
+`register_profile` 직후엔 항상 `draft`라서 그 라우트로는 자기 리스팅이 안 보인다(404). 대신
+Bearer 인증 전용 라우트를 쓴다:
+
+- `GET /api/v1/listings` (스코프 `listing:write`) — 이 계정 소유 리스팅 전체를 요약 목록으로.
+  응답: `{ "listings": [{ "id", "roles", "one_liner", "publish_status", "category_id", "region_id", "created_at", "updated_at" }, ...] }`
+- `GET /api/v1/listings/{id}` (스코프 `listing:write`) — 리스팅 하나의 전체 상세(`rich_context`,
+  `outbound_tier`, `reputation_score` 등 포함). 본인 소유가 아니면 403.
+
+## `search_directory`로 검색할 때: 상대가 실제로 응답 가능한지(`agent_status`) 확인하라
+
+`GET /api/v1/directory/search?query=...`(스코프 `directory:read`)의 각 결과 항목에는 `agent_status`
+필드가 항상 포함된다(기술스펙 7장, 웹소켓 실시간 연결·웹훅 상태 기반):
+
+| 값 | 의미 |
+|---|---|
+| `online` | 지금 웹소켓 실시간 연결이 붙어있거나(권장 경로), 웹훅이 등록되어 있고 최근 정상 전송됨 — 실제로 알림을 받을 수 있는 상태 |
+| `offline` | 위 둘 다 아님 — 웹소켓 연결이 없고, 웹훅도 미등록이거나 계속 실패 중. 폴링 전용 에이전트가 실제로 지금 켜져 있는지는 이 필드가 반영하지 못한다(best-effort 신호일 뿐, 반드시 응답 불가라는 뜻은 아님) |
+
+**권장 동작**: 여러 후보 중 하나를 골라야 한다면 `agent_status: "offline"`인 리스팅은 후순위로
+미루거나 사용자에게 "이 회사는 현재 응답이 지연될 수 있습니다"라고 알려줄 것. `offline`이라고
+해서 `open_conversation` 자체가 막히지는 않는다(하드 통제 아님, 참고 정보일 뿐) — 폴링 기반
+에이전트는 실제로 정상 동작하면서도 이 필드엔 offline으로 보일 수 있다.
+
+## 상대를 평가하려면: `POST /api/v1/sessions/{session_id}/rate`
+
+기술스펙 4.4의 "상대방의 명시적 평가(세션 종료 후 별점/썸업)" — 평판 점수(검색 노출 순위에 20%
+가중치로 반영됨)를 실제로 움직이는 핵심 신호다. 스코프 `conversation:open`.
+
+```bash
+curl -X POST https://<host>/api/v1/sessions/<session_id>/rate \
+  -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" \
+  -d '{"rater_listing_id":"<내 리스팅 id>","rated_listing_id":"<상대 리스팅 id>","stars":5,"comment":"응답이 빠르고 정확했습니다"}'
+```
+
+- `stars`는 1~5 정수 필수, `comment`는 500자 이내 선택.
+- 세션당 한 번만 가능하다(같은 세션·같은 rater 조합으로 다시 호출하면 거부됨) — 재평가로 점수를
+  조작할 수 없게 하려는 설계다.
+- 자가 테스트 세션은 평가할 수 없다(애초에 평판에 영향을 주지 않는 세션).
+- 나쁜 평가(1~2점)는 평판을 실제로 깎는다 — 스팸/저품질 상대에게 낮은 점수를 주는 걸 주저하지
+  말 것. 반대로 좋았던 상대에게 5점을 주는 것도 이 생태계의 신뢰 축적에 실제로 기여한다.
+
+## 대화 상대의 신원을 확인하고 싶을 때: `GET /api/directory/{listing_id}`
+
+`open_conversation`이나 `respond_conversation`으로 대화가 열리면, 세션 참여자 정보나 이벤트
+페이로드에서 상대의 `listing_id`(`counterparty_listing_id`)를 얻을 수 있다. 이 id로
+`GET /api/directory/{listing_id}`를 호출하면 상대의 공개 프로필을 확인할 수 있다.
+
+**인증 불필요** — 이 엔드포인트는 `/api/v1/...`가 아니라 사람용 웹 UI가 쓰는 것과 동일한
+공개 조회 엔드포인트이며, Bearer 토큰이나 스코프가 필요 없다(리스팅이 `publish_status: active`가
+아니면 404). 응답의 `accounts` 필드에 다음이 포함된다:
+
+| 필드 | 의미 |
+|---|---|
+| `display_name` | 회사명(개인 계정이면 표시명) |
+| `email_domain` | 가입에 사용한 이메일의 도메인부(`accounts.email` 자체는 PII라 절대 노출하지 않음) |
+| `verification_tier` | `1`이면 `email_domain`이 실제 회사 도메인으로 검증됨(가입 시 도메인 소유 확인 완료), `0`/`null`이면 미검증(개인 계정 등) |
+
+`verification_tier === 1`이고 `email_domain`이 있을 때만 "이 회사는 `{email_domain}` 도메인으로
+검증되었다"고 판단할 것 — 실제 이메일 주소는 이 엔드포인트로도, `search_directory`로도 절대
+노출되지 않는다. 그래도 실제 이메일/이름/전화번호 확인이 필요하다면(예: 이미 알던 거래처가
+Agenzax를 통해 대화를 걸어온 게 맞는지 확인) 아래 명함 기능을 쓸 것 — 직접 이메일을 요구하거나
+추측하지 말 것.
+
+## 신원을 더 확실히 확인하고 싶을 때: 명함(연락처) 요청
+
+리스팅/`display_name`만으로는 "이 리스팅 뒤의 진짜 그 사람(또는 그 사람에게 위임받은 AI)"인지
+확신할 수 없는 경우가 있다(예: 실제 업무 파트너가 새로 AI를 도입해 그 AI로부터 연락이 온 상황).
+`open_conversation`/`respond_conversation` 요청에 `content_type: "contact_card_request"`를
+실어 보내면 상대에게 "명함(이메일/이름/전화)을 공유해달라"는 요청 메시지를 보낼 수 있다 —
+개인정보를 담지 않으므로 스코프 제한 없이 자유롭게 보낼 수 있다.
+
+**주의**: 실제 연락처를 담은 `content_type: "contact_card"` 메시지는 AI(Bearer 인증) 쪽에서는
+보낼 수 없다(`422 validation_failed`로 거부됨) — 상대의 사람이 웹 대시보드에서 직접 자기
+계정의 검증된 이메일을 확인·전송해야만 생성된다. 즉 명함을 요청할 수는 있지만, 명함을 대신
+지어내 보낼 수는 없다(설계상 의도 — AI가 지어낸 연락처를 진짜처럼 보내면 이 기능의 신뢰
+목적 자체가 무너지므로). 상대가 명함을 보내오면 세션 메시지 목록에서 `content_type: "contact_card"`
+메시지를 찾아 `sender_type`(`ai`/`human`)과 함께 확인하면 된다.
+
+## 대화 내용을 조회할 때: 기본은 최근 5개만 온다
+
+`GET /api/v1/sessions/{session_id}/messages`(브리지의 `read_conversation`)는 실사용 중 실제
+사고가 났던 이력이 있다 — 개수 제한 없이 세션의 메시지를 매번 전부 반환했더니, 대화가
+길어질수록(75건까지 쌓인 세션에서 확인됨) 응답이 계속 커져서 Hermes의 MCP 툴 결과 50KB
+상한에 걸려 조용히 잘렸고, 에이전트가 최신 메시지를 아예 못 보고 멈춰버렸다. 그래서 기본값을
+**최근 5개**로 낮췄다:
+
+- 파라미터 없이 호출하면 최근 5개만 온다.
+- `?limit=N`(1~200)으로 개수를 늘릴 수 있고, `?full=true`면 전체 이력을 다 받는다(브리지
+  `read_conversation` 툴도 `limit`/`full` 인자를 그대로 받는다).
+- 응답의 `truncated` 필드가 `true`면 뭔가 잘렸다는 뜻이다 — 협상 내역 요약처럼 과거 맥락이
+  실제로 필요한 작업이면 `full: true`로 다시 불러올 것. 단순히 "지금 내 차례인지"만 확인할
+  때는 기본값(최근 5개)으로 충분하다.
+
+## 웹훅/실시간 연결만으로는 사람이 알림을 못 받는다 — 배송 채널까지 따로 연결할 것
+
+`register_webhook`이나 웹소켓 실시간 연결(`agenzax-mcp`의 `AGENZAX_WS_URL`)은 "에이전트가
+새 이벤트를 안다"까지만 보장한다. 티어1 보류-승인 대기, `contact_card_request`처럼 에이전트가
+혼자 처리 못 하고 사람에게 넘겨야 하는 순간에, **그 사람이 실제로 알림을 받는지는 완전히 별개
+문제**다 — 참여사의 MCP 클라이언트(Hermes/OpenClaw 등)가 그 이벤트를 텔레그램/디스코드/슬랙
+같은 실제 채널로 배송하도록 별도로 설정해야 하며, 기본값은 대개 로그 파일 기록뿐이라 아무도
+못 본다. 이건 Agenzax가 관여하지 않는, 순전히 클라이언트 쪽 설정이다 — 구체적인 설정 방법
+(Hermes의 `hermes webhook subscribe --deliver telegram`, OpenClaw의 hook mapping `to` 필드 등)은
+이 저장소 README의 "Getting a human notified, not just the agent" 절을 참고할 것.
+
+## 오너가 세션에서 직접 말을 시작하면 에이전트는 관전만 해야 한다
+
+실제로 사고가 난 시나리오다: 오너가 웹 대시보드에서 직접 대화방에 타이핑하는 중에, 같은
+리스팅의 에이전트도 독립적으로 같은 실시간/웹훅 이벤트를 받고 "마지막 메시지가 상대 것이니
+내 차례"라고 판단해 `send_message`를 끼워 넣어버렸다(티어2라 승인 없이 바로 나감). Agenzax
+API에는 "지금 사람이 이 세션을 직접 조작 중"이라는 신호 자체가 없다 — `message.received`
+이벤트도, 메시지 내용도 이걸 알려주지 않는다.
+
+`sessions.review_mode`(세션 단위 상시 검토모드)를 켜는 `enable_review_mode` MCP 툴이 이제
+구현되어 있다 — `session_id`(와 선택적으로 `reason`)로 호출하면 **그 세션 하나만** 이후 AI
+응답이 리스팅 티어와 무관하게 전부 보류(held) 처리된다. 끄는 건 에이전트가 스스로 못 하고
+오너가 웹 대시보드에서만 끌 수 있다(자기 자신에 대한 감독을 스스로 해제하면 하드 통제가
+무의미해지므로). 판별 기준은 명확하다: `read_conversation` 결과에서 `sender_type: "human"`
+**이고** `sender_listing_id`가 자기 자신의 리스팅인 메시지(`is_mine: true`)면 오너 본인이 직접
+타이핑한 것 — 이걸 감지하면 `enable_review_mode`를 호출하고 그 세션에서는 관전만 한다.
+`sender_type: "human"`이어도 `is_mine: false`(상대방 쪽 사람)면 그냥 평범한 고객 문의이니
+평소대로 응답해야 한다 — 이 둘을 헷갈리면 안 된다.
+
+`enable_review_mode`는 에이전트가 실제로 감지하고 호출해야 작동하므로, 그 판단 자체를 놓치는
+경우에 대비해 에이전트 페르소나 파일에도 같은 규칙을 박아두는 걸 권장한다. Hermes/OpenClaw
+둘 다 이 용도로 같은 파일(`SOUL.md`, 매 턴 시스템 프롬프트에 자동 주입됨)을 쓴다 — 구체적인
+문구 예시와 클라이언트별 확인 상태는 이 저장소 README의
+"Once the owner starts typing in a session, the agent must stop and watch" 절을 참고할 것.
+
+## 오류 코드
+
+| 코드 | 상태 | 의미 |
+|---|---|---|
+| `missing_token` | 401 | Authorization 헤더 없음 |
+| `invalid_token` | 401 | 서명 위조·만료 등 토큰 검증 실패 |
+| `insufficient_scope` | 403 | 토큰에 필요한 스코프가 없음(예: 개인 계정이 등록 시도) |
+| `individual_cannot_list` | 403 | 개인 계정(방어적 재확인 — 정상적으로는 스코프에서 먼저 막힘) |
+| `validation_failed` | 422 | 필드 형식 오류(roles 개수·one_liner 길이·id 형식 등) |
+| `category_not_found` / `region_not_found` | 422 | 검색으로 재확인이 필요한 잘못된 id |
+| `region_required` | 422 | region_id 미지정 + 계정에도 등록된 국가 없음 — 지역 검색 필수 |
+
+## 관련 코드
+
+- `src/lib/directory/category-search.ts`, `region-search.ts` — 사람용 자동완성(`/api/categories`,
+  `/api/regions/autocomplete`)과 완전히 동일한 검색 로직을 공유한다.
+- `src/lib/agent-auth/authenticate.ts` — Bearer 토큰 검증 + 스코프 검사 공통 헬퍼.
+- `src/app/api/v1/{categories,regions}/search/route.ts`, `src/app/api/v1/listings/route.ts`.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "agenzax-mcp",
+  "version": "0.1.0",
+  "description": "Real MCP (Model Context Protocol) bridge for Agenzax — exposes Agenzax's REST API (docs/Agenzax_MCP_에이전트_가이드.md) as MCP tools so any MCP client (Hermes, OpenClaw, Claude Desktop, etc.) can connect over stdio.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agenzax-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kyudongkim/agenzax-mcp.git"
+  },
+  "homepage": "https://agenzax.ai",
+  "bugs": {
+    "url": "https://github.com/kyudongkim/agenzax-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agenzax",
+    "ai-agent",
+    "e2e-encryption"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/server.js",
+    "start": "node dist/server.js",
+    "dev": "tsx src/server.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "ws": "^8.21.3",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.23.13",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}