@apiosk/mcp 1.3.1 → 2.0.0

package/src/observability.mjs

@@ -0,0 +1,210 @@
+// MCP observability side-car — the MCP server historically logged NOTHING about
+// its own activity (tool calls, SSE sessions, OAuth/installs). This module writes
+// append-only rows to the mcp_tool_calls / mcp_sessions / mcp_oauth_events tables
+// (gateway migration 057) so the admin portal can see MCP traffic.
+//
+// Design: fire-and-forget, NEVER throws into the hot path (every write is wrapped
+// in try/catch and returns a swallowed promise). Uses the service-role key exactly
+// like publisher.mjs (rest/v1/<table>). PRIVACY: raw connect tokens are sha256-hashed
+// (never stored raw), and only argument KEY NAMES are stored — never values, headers,
+// or bodies.
+
+import { createHash } from "node:crypto";
+
+const DEFAULT_SUPABASE_URL = "https://api.apiosk.com";
+const physicalSchemaOrigins = new Set();
+
+function resolveConfig(env = {}) {
+  const raw =
+    env.APIOSK_SUPABASE_URL || env.SUPABASE_URL || DEFAULT_SUPABASE_URL;
+  const url = String(raw).replace(/\/+$/, "");
+  const key =
+    env.APIOSK_SUPABASE_SERVICE_ROLE_KEY || env.SUPABASE_SERVICE_ROLE_KEY || "";
+  return { url, key };
+}
+
+function sha256(value) {
+  if (!value || typeof value !== "string") return null;
+  try {
+    return createHash("sha256").update(value).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+function trimStr(v, max = 400) {
+  if (v == null) return null;
+  const s = String(v);
+  return s.length > max ? s.slice(0, max) : s;
+}
+
+// Low-level fire-and-forget REST write. Resolves regardless of outcome; a failure
+// is logged to stderr but never propagates — observability must not break a tool call.
+async function restWrite(env, path, body, { method = "POST", extraHeaders = {} } = {}) {
+  const { url, key } = resolveConfig(env);
+  if (!key) return; // not configured on this deployment — skip silently
+  const fetchImpl = globalThis.fetch;
+  if (typeof fetchImpl !== "function") return;
+  try {
+    const physical = physicalSchemaOrigins.has(url);
+    const options = {
+      method,
+      headers: {
+        apikey: key,
+        authorization: `Bearer ${key}`,
+        "content-type": "application/json",
+        prefer: "return=minimal",
+        ...(physical ? { "Accept-Profile": "agents", "Content-Profile": "agents" } : {}),
+        ...extraHeaders,
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    };
+    const response = await fetchImpl(`${url}/rest/v1/${path}`, options);
+    // A lookup failure means no SQL ran; never retry an ambiguous write.
+    if (response?.status === 404 && (await response.clone().json()).code === "PGRST205") {
+      const schema = physical ? "public" : "agents";
+      const retried = await fetchImpl(`${url}/rest/v1/${path}`, {
+        ...options,
+        headers: { ...options.headers, "Accept-Profile": schema, "Content-Profile": schema },
+      });
+      if (retried.ok) {
+        if (physical) physicalSchemaOrigins.delete(url);
+        else physicalSchemaOrigins.add(url);
+      }
+    }
+  } catch (error) {
+    try {
+      console.warn(
+        "[observability] write failed:",
+        error && error.message ? error.message : String(error),
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/** Extract caller identity from the MCP authInfo (never returns a raw token). */
+export function callerFrom(authInfo) {
+  const x = (authInfo && (authInfo.extra || authInfo)) || {};
+  const rawToken = x.apiosk_connect_token || x.connectToken || null;
+  const hasToken = Boolean(rawToken || x.apiosk_connect_token_id);
+  return {
+    auth_method: hasToken ? "connect_token" : x.userId ? "oauth" : "anonymous",
+    user_id: x.userId || x.user_id || null,
+    connect_token_id: x.apiosk_connect_token_id || x.connect_token_id || null,
+    connect_token_hash: sha256(rawToken),
+    wallet_address:
+      x.walletAddress || x.apiosk_connect_wallet_address || x.wallet_address || null,
+    provider_id: x.providerId || x.provider_id || null,
+    client_name: (authInfo && (authInfo.clientName || authInfo.client_name)) || null,
+    client_kind: (authInfo && (authInfo.clientKind || authInfo.client_kind)) || null,
+  };
+}
+
+/** Log one tools/call dispatch. Fire-and-forget. */
+export function logToolCall(
+  env,
+  {
+    toolName,
+    outcome = "ok",
+    errorCode = null,
+    latencyMs = null,
+    authInfo = null,
+    argKeys = [],
+    sessionId = null,
+    gatewayRequestId = null,
+    ip = null,
+    userAgent = null,
+  } = {},
+) {
+  const caller = callerFrom(authInfo);
+  return restWrite(env, "mcp_tool_calls", {
+    tool_name: String(toolName || "unknown"),
+    outcome,
+    error_code: errorCode ? trimStr(errorCode, 120) : null,
+    latency_ms: typeof latencyMs === "number" ? Math.round(latencyMs) : null,
+    ...caller,
+    session_id: sessionId,
+    gateway_request_id: gatewayRequestId,
+    arg_keys: Array.isArray(argKeys) ? argKeys.slice(0, 64).map(String) : [],
+    ip_address: ip,
+    user_agent: trimStr(userAgent),
+  });
+}
+
+/** Record an SSE session on connect (upsert on session_id). Fire-and-forget. */
+export function openSession(
+  env,
+  { sessionId, transport = "sse", ip = null, userAgent = null, clientName = null, clientKind = null, protocolVersion = null } = {},
+) {
+  if (!sessionId) return;
+  return restWrite(
+    env,
+    "mcp_sessions",
+    {
+      session_id: String(sessionId),
+      transport,
+      ip_address: ip,
+      user_agent: trimStr(userAgent),
+      client_name: clientName,
+      client_kind: clientKind,
+      protocol_version: protocolVersion,
+      status: "online",
+    },
+    // Upsert: a reconnect with the same id refreshes it instead of 409-ing.
+    { extraHeaders: { prefer: "resolution=merge-duplicates,return=minimal" } },
+  );
+}
+
+/** Mark an SSE session closed on disconnect. Fire-and-forget. */
+export function closeSession(env, sessionId) {
+  if (!sessionId) return;
+  const now = new Date().toISOString();
+  return restWrite(
+    env,
+    `mcp_sessions?session_id=eq.${encodeURIComponent(String(sessionId))}`,
+    { status: "closed", disconnected_at: now, last_activity_at: now },
+    { method: "PATCH" },
+  );
+}
+
+/** Log an OAuth / install event (authorize, consent, token_issued, wallet_created…). */
+export function logOAuthEvent(
+  env,
+  {
+    eventType,
+    userId = null,
+    clientId = null,
+    clientName = null,
+    redirectUri = null,
+    scopes = [],
+    connectTokenId = null,
+    connectTokenHash = null,
+    connectTokenRaw = null,
+    walletAddress = null,
+    walletCreated = false,
+    outcome = "ok",
+    errorCode = null,
+    ip = null,
+    userAgent = null,
+  } = {},
+) {
+  if (!eventType) return;
+  return restWrite(env, "mcp_oauth_events", {
+    event_type: eventType,
+    user_id: userId,
+    client_id: clientId ? trimStr(clientId, 200) : null,
+    client_name: clientName,
+    redirect_uri: redirectUri ? trimStr(redirectUri, 500) : null,
+    scopes: Array.isArray(scopes) ? scopes.map(String) : [],
+    connect_token_id: connectTokenId,
+    connect_token_hash: connectTokenHash || sha256(connectTokenRaw),
+    wallet_address: walletAddress,
+    wallet_created: Boolean(walletCreated),
+    outcome,
+    error_code: errorCode ? trimStr(errorCode, 120) : null,
+    ip_address: ip,
+    user_agent: trimStr(userAgent),
+  });
+}

package/src/result-presentation.mjs

@@ -0,0 +1,9 @@
+// Shared by the tool response and the card's completion notification.
+export const V2_SOURCES_PRESENTATION = "Source overview presentation: the interactive Apiosk card already displays the sources, total, filters, pagination and expandable services. When the card is displayed, add at most one short confirmation sentence. Do not repeat the sources as a second table, list, category breakdown or readiness report underneath or above the card. 'Show sources', 'list all sources' and 'which sources are available' request this one card, not a duplicate text overview. Only provide a separate text table or export when the actual user explicitly requests that format. If the host cannot display the card, provide one compact text overview from the returned sources and respect pagination. Count Pulse Network once and keep its services nested. Show only supported function counts; never display registered endpoint totals or supported/registered ratios in a source overview. Use this fresh result's total; never repeat an older catalog count from conversation history. Do not append an unsolicited question or analysis.";
+
+export const V2_RESULT_TOOL_DESCRIPTION = "Use English for Apiosk workflow messages, unless a translation is explicitly requested. Display Apiosk prices, charges and balances in the account display currency from context_view.money_display, using the converted prices supplied in the response. Raw proposal and billing amounts remain micro USD for authorization; never present those raw amounts as the preferred currency or override EUR with USD. Never change source document currencies. Output: this tool displays the complete result in an interactive card. After it, write only a brief confirmation (entity, source, period/date and optional unit caveat) and source citation. Do not add a second table, figures, costs, missing-data list or analysis unless the user explicitly requests those details. 'Show the result' or 'retrieve annual accounts' means display the card, not write a second report.";
+export const V2_RESULT_PRESENTATION = "Use the converted Apiosk prices and account display currency supplied by this response, including EUR when preferred. Raw billing and approval micro USD amounts are internal accounting values, not the user display currency. Preserve source document figures and currencies. Display all-uppercase company names in readable title case, for example ORION BEHEER BV as Orion Beheer BV; preserve legal abbreviations such as BV/NV and mixed-case brands. Keep identifiers, URLs and raw source JSON exact. When the interactive Apiosk result card is visible, the default reply after it is only 1–3 short sentences plus a source citation: identify what was retrieved, the entity, source, covered period and relevant source dates. A short currency/unit caveat is allowed when relevant. Do not repeat the card's figures, tables, JSON, charges, fees, balance or detailed missing-data lists. Give those details or analysis only when the actual user explicitly asks for them; a request to fetch or show records alone is not such a request. Use only returned evidence. If no result card can be displayed, provide the requested source-backed answer in text.";
+
+export const V2_VERIFICATION_PRESENTATION = "For a supplier verification or validity question, answer the question with a concise supported conclusion and the material unknowns, not merely 'results retrieved'. Distinguish active legal registration from complete onboarding clearance. If ownership or VAT is unverified, say not fully verified for onboarding, not that the company is invalid. Screening candidates require identity review and are not confirmed sanctions findings. Do not treat no matches or a completed task as a compliance certificate. Source records are available in the card's collapsed Sources and details section.";
+
+export const V2_RESULT_READY_PROMPT = "The Apiosk answer is now visible above collapsed source details. Add only a brief conclusion and source citation below it. Do not generate a second detailed answer automatically. " + V2_RESULT_PRESENTATION + " " + V2_VERIFICATION_PRESENTATION + " Do not purchase the same data again.";