@kakunin/mcp 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# @kakunin/mcp
+
+Model Context Protocol server for the [Kakunin](https://kakunin.ai) AI agent compliance API. Lets AI agents self-verify scope, check their own risk score, and log behavioral events — all from within Claude, Cursor, or any MCP-compatible runtime.
+
+```bash
+npx @kakunin/mcp
+```
+
+## Tools
+
+### `verify_agent_scope`
+Check whether this agent is authorised to perform an action before executing it. Verifies the active X.509 certificate, permitted_actions scope, financial limits, and revocation status.
+
+```json
+{
+  "action": "initiate EUR/USD trade on euronext for 50000 USD",
+  "venue": "euronext",
+  "amount_usd": 50000
+}
+```
+
+Returns `{ allowed: true|false, reason, certificate_status, permitted_actions }`.
+
+### `check_risk_score`
+Retrieve the agent's rolling 30-day risk score, band (`low`/`medium`/`high`), drift trend, and actionable guidance. No input required.
+
+### `audit_log_append`
+Append a behavioral event to the agent's immutable audit log. Returns risk score + transaction ID. Events scoring ≥ 0.85 auto-trigger a certificate revocation check.
+
+```json
+{
+  "action_type": "transaction_initiated",
+  "details": { "amount_usd": 50000, "venue": "NYSE" }
+}
+```
+
+## Setup
+
+**Prerequisites:** Node ≥ 18, Kakunin API key + Agent ID from [kakunin.ai/dashboard](https://kakunin.ai/dashboard).
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kakunin": {
+      "command": "npx",
+      "args": ["-y", "@kakunin/mcp"],
+      "env": {
+        "KAKUNIN_API_KEY": "kkn_live_...",
+        "KAKUNIN_AGENT_ID": "agt_..."
+      }
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `KAKUNIN_API_KEY` | ✅ | API key (`kkn_live_...` or `kkn_test_...`) |
+| `KAKUNIN_AGENT_ID` | ✅ | Agent ID the server acts on behalf of |
+| `KAKUNIN_BASE_URL` | optional | Override API base (default: `https://kakunin.ai`) |
+
+## Sandbox mode
+
+Use a `kkn_test_...` key for development — hits the sandbox CA, no cost, 100 free certs/day.
+
+Full docs at [docs.kakunin.ai](https://docs.kakunin.ai).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,310 @@
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.kakunin.ai/v1";
+var KakuninMcpClient = class {
+  apiKey;
+  agentId;
+  baseUrl;
+  timeoutMs;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.agentId = config.agentId;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = config.timeoutMs ?? 8e3;
+  }
+  async request(path, options = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          "User-Agent": `@kakunin/mcp/0.1.0`,
+          ...options.headers
+        },
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({ error: res.statusText }));
+      throw new Error(`Kakunin API error ${res.status}: ${body.error ?? res.statusText}`);
+    }
+    const json = await res.json();
+    return json.data;
+  }
+  /** Fetch the agent's current active certificate, including permitted_actions. */
+  async getActiveCertificate() {
+    const agent = await this.request(
+      `/agents/${this.agentId}`
+    );
+    const active = agent.certificates.find((c) => c.status === "active");
+    return active ?? null;
+  }
+  /** Fetch rolling 30-day risk profile. */
+  async getRiskProfile() {
+    return this.request(`/agents/${this.agentId}/risk`);
+  }
+  /** Ingest a behavioral event. Returns risk score synchronously. */
+  async ingestEvent(actionType, metadata, sessionId) {
+    return this.request("/events", {
+      method: "POST",
+      body: JSON.stringify({
+        agent_id: this.agentId,
+        action_type: actionType,
+        details: metadata,
+        ...sessionId !== void 0 ? { session_id: sessionId } : {},
+        occurred_at: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    });
+  }
+};
+
+// src/tools/verify-scope.ts
+import { z } from "zod";
+var verifyScopeInputSchema = z.object({
+  action: z.string().min(1).describe(
+    'The action or endpoint the agent wants to perform. Can be a scope string (e.g. "write:invoices"), an API path (e.g. "/api/v1/execute_trade"), or a plain description (e.g. "initiate EUR/USD trade on euronext for 50000 USD").'
+  ),
+  venue: z.string().optional().describe('Optional trading venue or system being accessed (e.g. "euronext", "xetra").'),
+  amount_usd: z.number().optional().describe("Optional transaction amount in USD for financial scope enforcement.")
+});
+async function verifyScopeHandler(client2, input) {
+  const cert = await client2.getActiveCertificate();
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (!cert) {
+    return {
+      allowed: false,
+      reason: "No active certificate found. Agent must be certified before performing actions.",
+      certificate_status: "none",
+      permitted_actions: [],
+      checked_at: checkedAt
+    };
+  }
+  if (cert.status !== "active") {
+    return {
+      allowed: false,
+      reason: `Certificate is ${cert.status}. All actions are blocked until a new certificate is issued.`,
+      certificate_status: cert.status,
+      permitted_actions: cert.permitted_actions,
+      checked_at: checkedAt
+    };
+  }
+  if (input.amount_usd !== void 0 && cert.financial_scope?.max_single_trade_usd !== void 0) {
+    if (input.amount_usd > cert.financial_scope.max_single_trade_usd) {
+      return {
+        allowed: false,
+        reason: `Transaction amount $${input.amount_usd.toLocaleString()} USD exceeds the per-trade limit of $${cert.financial_scope.max_single_trade_usd.toLocaleString()} USD encoded in this certificate.`,
+        certificate_status: "active",
+        permitted_actions: cert.permitted_actions,
+        checked_at: checkedAt
+      };
+    }
+  }
+  if (input.venue !== void 0 && cert.financial_scope?.permitted_venues !== void 0) {
+    const venues = cert.financial_scope.permitted_venues;
+    if (!venues.includes(input.venue)) {
+      return {
+        allowed: false,
+        reason: `Venue "${input.venue}" is not in the permitted venues list: ${venues.join(", ")}.`,
+        certificate_status: "active",
+        permitted_actions: cert.permitted_actions,
+        checked_at: checkedAt
+      };
+    }
+  }
+  const action = input.action;
+  const allowed = isActionPermitted(action, cert.permitted_actions);
+  return {
+    allowed,
+    reason: allowed ? `Action "${action}" is within the scope of this certificate.` : `Action "${action}" is not in the permitted actions for this certificate. Permitted: ${cert.permitted_actions.join(", ")}.`,
+    certificate_status: "active",
+    permitted_actions: cert.permitted_actions,
+    checked_at: checkedAt
+  };
+}
+function isActionPermitted(action, permitted) {
+  const normalized = action.toLowerCase().trim();
+  for (const perm of permitted) {
+    const p = perm.toLowerCase().trim();
+    if (p === normalized) return true;
+    if (p.endsWith(":*")) {
+      const prefix = p.slice(0, -1);
+      if (normalized.startsWith(prefix)) return true;
+    }
+    if (normalized.startsWith("/") || normalized.startsWith("http")) {
+      const resource = p.includes(":") ? p.split(":")[1] : p;
+      if (resource && normalized.includes(resource)) return true;
+    }
+    if (!normalized.startsWith("/") && !normalized.includes(":")) {
+      if (p.includes(normalized) || normalized.includes(p.replace(/.*:/, ""))) return true;
+    }
+  }
+  return false;
+}
+
+// src/tools/check-risk.ts
+async function checkRiskHandler(client2) {
+  const profile = await client2.getRiskProfile();
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const trend = profile.drift.drift_trend ?? "insufficient_data";
+  const recommendation = buildRecommendation(profile.dominant_band, trend, profile.avg_score);
+  return {
+    score: profile.avg_score,
+    band: profile.dominant_band,
+    trend,
+    recommendation,
+    recent_high_risk_events: profile.recent_high_risk_events,
+    checked_at: checkedAt
+  };
+}
+function buildRecommendation(band, trend, score) {
+  if (band === "high") {
+    return `Risk score ${score.toFixed(2)} is HIGH. Certificate revocation check has been queued. You should pause non-essential operations and notify your human operator immediately.`;
+  }
+  if (band === "medium" && trend === "increasing") {
+    return `Risk score ${score.toFixed(2)} is MEDIUM and increasing. Consider reducing transaction frequency or scope until trend stabilises.`;
+  }
+  if (band === "medium") {
+    return `Risk score ${score.toFixed(2)} is MEDIUM. Continue with caution \u2014 avoid high-value or irreversible operations without human confirmation.`;
+  }
+  if (trend === "increasing") {
+    return `Risk score ${score.toFixed(2)} is LOW but trend is increasing. Monitor closely \u2014 consider logging additional context with audit_log_append.`;
+  }
+  return `Risk score ${score.toFixed(2)} is LOW. Normal operations permitted.`;
+}
+
+// src/tools/audit-log-append.ts
+import { z as z2 } from "zod";
+var ACTION_TYPES = [
+  "api_call",
+  "authentication_attempt",
+  "authentication_failure",
+  "data_access",
+  "data_mutation",
+  "transaction_initiated",
+  "transaction_anomaly",
+  "unauthorized_access_attempt",
+  "message_signed",
+  "message_verification_failed"
+];
+var auditLogAppendInputSchema = z2.object({
+  event_type: z2.enum(ACTION_TYPES).describe(
+    'Type of behavioral event being logged. Use "transaction_initiated" for financial operations, "data_mutation" for write/delete ops, "api_call" for standard API calls.'
+  ),
+  metadata: z2.record(z2.unknown()).describe(
+    "Arbitrary key-value pairs describing the event. For transactions: include amount, currency, venue. For data ops: include resource_type, resource_id, operation. Avoid PII \u2014 this is stored in the immutable audit log."
+  ),
+  session_id: z2.string().optional().describe("Optional session ID for grouping related events in the audit trail.")
+});
+async function auditLogAppendHandler(client2, input) {
+  const result = await client2.ingestEvent(
+    input.event_type,
+    input.metadata,
+    input.session_id
+  );
+  return {
+    inserted: true,
+    tx_id: result.event_id,
+    risk_score: result.risk_score,
+    risk_band: result.risk_band,
+    revocation_check_queued: result.revocation_check_queued,
+    logged_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/index.ts
+var apiKey = process.env["KAKUNIN_API_KEY"];
+var agentId = process.env["KAKUNIN_AGENT_ID"];
+var baseUrl = process.env["KAKUNIN_BASE_URL"];
+if (!apiKey) {
+  console.error("[kakunin-mcp] KAKUNIN_API_KEY is required");
+  process.exit(1);
+}
+if (!agentId) {
+  console.error("[kakunin-mcp] KAKUNIN_AGENT_ID is required");
+  process.exit(1);
+}
+var client = new KakuninMcpClient({
+  apiKey,
+  agentId,
+  ...baseUrl !== void 0 ? { baseUrl } : {}
+});
+var server = new McpServer({
+  name: "kakunin",
+  version: "0.1.0"
+});
+server.tool(
+  "verify_agent_scope",
+  "Check whether this agent is authorised to perform a specific action or call a specific endpoint. Verifies the active X.509 certificate, permitted_actions scope, financial limits, and revocation status. Call this BEFORE executing any action that might exceed scope \u2014 not after.",
+  verifyScopeInputSchema.shape,
+  async (input) => {
+    const result = await verifyScopeHandler(client, input);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
+    };
+  }
+);
+server.tool(
+  "check_risk_score",
+  "Retrieve this agent's rolling 30-day risk score, risk band (low/medium/high), and drift trend. Returns actionable guidance \u2014 use this to decide whether to self-throttle, escalate to a human, or proceed normally.",
+  // No input parameters
+  {},
+  async () => {
+    const result = await checkRiskHandler(client);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
+    };
+  }
+);
+server.tool(
+  "audit_log_append",
+  "Append a behavioral event to this agent's immutable audit log. Use this to voluntarily record actions \u2014 transactions, data operations, API calls. Returns the risk score for the event and a transaction ID for traceability. High-risk events (score >= 0.85) automatically trigger a certificate revocation check.",
+  auditLogAppendInputSchema.shape,
+  async (input) => {
+    const parsed = auditLogAppendInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ error: parsed.error.message }, null, 2)
+          }
+        ],
+        isError: true
+      };
+    }
+    const result = await auditLogAppendHandler(client, parsed.data);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
+    };
+  }
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);
+process.on("SIGINT", async () => {
+  await server.close();
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@kakunin/mcp",
+  "version": "0.1.0",
+  "description": "Kakunin MCP server — lets AI agents query their own scope, risk score, and log behavioral events",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "kakunin-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "dev": "node --env-file=.env dist/index.js",
+    "prepublishOnly": "npm run build && npm run typecheck"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "kyc",
+    "kakunin",
+    "compliance"
+  ],
+  "license": "MIT",
+  "homepage": "https://kakunin.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nqzai/kakunin.git",
+    "directory": "mcp/kakunin-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}