@softure-ai/mcp-access 0.2.4 → 0.2.6

package/src/server/tools.ts

@@ -1,8 +1,9 @@
 // Tool results for the app's MCP server and the boundary that keeps failures safe: the assistant gets
 // a value, a `PublicError`'s message or a hint, never a thrown error's text (a failed query carries
-// its SQL and parameters). The log gets the error's kind only (`errorLogLabel`).
+// its SQL and parameters). The log gets the error's kind only (`errorLogLabel`). An optional hook sees
+// each call as a whole: which tool, which client, the outcome with its code, and how long it took.
 import { isCallToolResult, type CallToolResult } from "@modelcontextprotocol/server";
-import { errorLogLabel, getPublicMessage, safeError } from "@softure-ai/core";
+import { errorLogLabel, getPublicMessage, safeError, type CoreErrorCode } from "@softure-ai/core";
 
 /** What the assistant reads for an error code: the app's own text per code, e.g. `{ "orders.not_found": "No order with that number." }`. */
 export type ToolErrorHints = Readonly<Record<string, string>>;
@@ -10,10 +11,46 @@ export type ToolErrorHints = Readonly<Record<string, string>>;
 export interface ToolErrorOptions {
   /** Texts per error code; a code without one is answered as the code itself. */
   readonly hints?: ToolErrorHints;
-  /** The tool's name in the log line. */
+  /** The tool's name in the log line and in the `onToolCall` record. */
   readonly label?: string;
+  /** Called once after each call with its record. Its failure is logged by kind and never changes the answer. */
+  readonly onToolCall?: ToolCallHook;
+  /** Who called, for the record: built once per request in the app's server factory. */
+  readonly caller?: ToolCaller;
+  /** The tool's arguments, for the record: only their names are read, never their values. */
+  readonly args?: Readonly<Record<string, unknown>>;
 }
 
+/** The client behind a call: the token's id (`McpServerIdentity.tokenId`) and its name (`findTokenClientName`). */
+export interface ToolCaller {
+  readonly tokenId: string;
+  readonly clientName: string | null;
+}
+
+/**
+ * How a call ended. `succeeded`: `itemCount` is the length of an array value, else `null`. `failed`: the
+ * result's error code, `null` for a `CallToolResult` the tool marked `isError` itself. `thrown`: the
+ * `safeError` code, `null` for a `PublicError` (a deliberate message, no code).
+ */
+export type ToolCallOutcome =
+  | { readonly kind: "succeeded"; readonly itemCount: number | null }
+  | { readonly kind: "failed"; readonly code: string | null }
+  | { readonly kind: "thrown"; readonly code: CoreErrorCode | null };
+
+/** One tool call as the `onToolCall` hook sees it. */
+export interface ToolCallRecord {
+  /** The tool's `label`, else `"call"`. */
+  readonly tool: string;
+  readonly tokenId: string | null;
+  readonly clientName: string | null;
+  readonly argumentNames: readonly string[];
+  readonly outcome: ToolCallOutcome;
+  readonly startedAt: Date;
+  readonly durationMs: number;
+}
+
+export type ToolCallHook = (record: ToolCallRecord) => unknown;
+
 /** For failures the tool did not expect: what `safeError` makes of them, unless a hint replaces it. */
 const DEFAULT_FAILURE_TEXT: ToolErrorHints = {
   "core.database_failed": "The database could not answer; try again later.",
@@ -37,11 +74,47 @@ export function toolError(message: string): CallToolResult {
  * anything else is logged by kind and answered with the hint for its `safeError` code, else a fixed text.
  */
 export async function withToolErrors(work: () => unknown, options: ToolErrorOptions = {}): Promise<CallToolResult> {
+  const startedAt = Date.now();
+  let answer: CallToolResult;
+  let outcome: ToolCallOutcome;
   try {
-    return answerValue(await work(), options.hints);
+    const value = await work();
+    answer = answerValue(value, options.hints);
+    outcome = describeValueOutcome(value);
   } catch (error) {
-    return answerFailure(error, options);
+    answer = answerFailure(error, options);
+    outcome = { kind: "thrown", code: getPublicMessage(error) === null ? safeError(error).error : null };
   }
+  if (options.onToolCall !== undefined) await reportToolCall(options, outcome, startedAt);
+  return answer;
+}
+
+async function reportToolCall(options: ToolErrorOptions, outcome: ToolCallOutcome, startedAt: number): Promise<void> {
+  const tool = options.label ?? "call";
+  const record: ToolCallRecord = {
+    tool,
+    tokenId: options.caller?.tokenId ?? null,
+    clientName: options.caller?.clientName ?? null,
+    argumentNames: Object.keys(options.args ?? {}),
+    outcome,
+    startedAt: new Date(startedAt),
+    durationMs: Date.now() - startedAt,
+  };
+  try {
+    await options.onToolCall?.(record);
+  } catch (error) {
+    console.error(`@softure-ai/mcp-access: the onToolCall hook failed for tool ${tool}: ${errorLogLabel(error)}`);
+  }
+}
+
+function describeValueOutcome(value: unknown): ToolCallOutcome {
+  if (isCallToolResult(value)) return value.isError === true ? { kind: "failed", code: null } : { kind: "succeeded", itemCount: null };
+  if (isResult(value)) return value.ok ? countItems(value.value) : { kind: "failed", code: value.error };
+  return countItems(value);
+}
+
+function countItems(value: unknown): ToolCallOutcome {
+  return { kind: "succeeded", itemCount: Array.isArray(value) ? value.length : null };
 }
 
 /** The answer for a value a tool or an action returned. */

package/src/ui/token-manager.tsx

@@ -2,7 +2,7 @@
 
 import { formatMessage, type Locale } from "@softure-ai/core";
 import { Button, ButtonLink, Checkbox, type ClassNames, createSlotClassGetter, FormError, TextField } from "@softure-ai/ui";
-import { useActionState, useState } from "react";
+import { useActionState, useEffect, useRef, useState } from "react";
 import type { IssuedToken, IssueTokenFormState, RevokeGrantFormState, RevokeTokenFormState } from "../contract.js";
 import { getTokenErrorMessage, type McpAccessMessages } from "../messages/index.js";
 import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
@@ -11,8 +11,9 @@ import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
 // setup snippets, the owner's tokens with a revoke button each, and, with OAuth on, the apps
 // connected through OAuth with a disconnect button each. Both forms submit to their
 // server actions through `useActionState`. The plaintext lives only in the issue form's state:
-// "Done" or leaving the page drops it. Copy comes from the module's messages; styling only from
-// @softure-ai/ui classes.
+// "Done" or leaving the page drops it. Focus follows the one-time token: its heading takes focus
+// when it appears, and "Done" hands focus back to the name field. Copy comes from the module's
+// messages; styling only from @softure-ai/ui classes.
 
 export type IssueTokenAction = (previous: IssueTokenFormState, formData: FormData) => Promise<IssueTokenFormState>;
 export type RevokeTokenAction = (previous: RevokeTokenFormState, formData: FormData) => Promise<RevokeTokenFormState>;
@@ -124,9 +125,14 @@ function IssuedTokenPanel({
   unstyled: boolean | undefined;
 }) {
   const snippet = (title: string, value: string) => <Snippet title={title} value={value} messages={messages} slot={slot} unstyled={unstyled} />;
+  const headingRef = useRef<HTMLHeadingElement>(null);
+  // Once per issued token, so a screen reader announces it; not on re-renders while the owner copies.
+  useEffect(() => {
+    headingRef.current?.focus();
+  }, [issued.id]);
   return (
     <section className={slot("section")}>
-      <h3 className={slot("heading")}>{formatMessage(messages.issued.title, { name: issued.name })}</h3>
+      <h3 ref={headingRef} tabIndex={-1} className={slot("heading")}>{formatMessage(messages.issued.title, { name: issued.name })}</h3>
       <p className={slot("text")}>{messages.issued.once}</p>
       <p className={slot("text")}>
         {issued.expiresText} {issued.canWrite ? messages.issued.readWrite : messages.issued.readOnly}
@@ -168,11 +174,20 @@ function IssueForm({
   // The id of the issued token the owner dismissed; a new one shows again.
   const [dismissedId, setDismissedId] = useState<string | null>(null);
   const issued = state.status === "ok" && state.issued.id !== dismissedId ? state.issued : null;
+  const formRef = useRef<HTMLFormElement>(null);
+  function dismiss(id: string) {
+    setDismissedId(id);
+    // The focused "Done" button unmounts with the panel; once it is gone, the name field is the next step.
+    requestAnimationFrame(() => {
+      const field = formRef.current?.elements.namedItem("name");
+      if (field instanceof HTMLInputElement) field.focus();
+    });
+  }
   return (
     <>
       <section className={slot("section")}>
         <h2 className={slot("heading")}>{messages.issue.title}</h2>
-        <form action={formAction} className={slot("list")}>
+        <form ref={formRef} action={formAction} className={slot("list")}>
           <TextField
             name="name"
             label={messages.issue.name}
@@ -191,7 +206,7 @@ function IssueForm({
           </Button>
         </form>
       </section>
-      {issued === null ? null : <IssuedTokenPanel issued={issued} onDone={() => setDismissedId(issued.id)} messages={messages} slot={slot} unstyled={unstyled} />}
+      {issued === null ? null : <IssuedTokenPanel issued={issued} onDone={() => dismiss(issued.id)} messages={messages} slot={slot} unstyled={unstyled} />}
     </>
   );
 }