@softure-ai/mcp-access 0.1.12 → 0.1.13

package/src/cli/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `softure-mcp` executable. All logic lives in command.ts and run.ts, which the tests call directly.
+import { runMcpAccessCommand } from "./command.js";
+
+process.exitCode = await runMcpAccessCommand({ argv: process.argv.slice(2), cwd: process.cwd() });

package/src/cli/command.ts

@@ -0,0 +1,38 @@
+// The `softure-mcp` bin. It loads the app's config through `@softure-ai/core/cli`, like `softure-mail`
+// (@softure-ai/mailing): the file must be loadable by Node itself (`.js`/`.mjs`, or `.ts` where Node
+// strips types). Anything else uses an app script with `runMcpAccessCli` instead (see run.ts).
+import { loadAppConfig, takeConfigOption } from "@softure-ai/core/cli";
+import { EXIT_FAILED, EXIT_USAGE, MCP_ACCESS_USAGE, runMcpAccessCli, type CliOutput } from "./run.js";
+
+export interface RunMcpAccessCommandOptions {
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly output?: CliOutput;
+}
+
+const APP_SCRIPT = { runner: "runMcpAccessCli", packageName: "@softure-ai/mcp-access" };
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+/** Loads the config (unless only help is asked for) and runs `runMcpAccessCli`. */
+export async function runMcpAccessCommand(options: RunMcpAccessCommandOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const taken = takeConfigOption(options.argv);
+  if (!taken.ok) {
+    output.error(`softure-mcp: ${taken.problem}`);
+    output.error(MCP_ACCESS_USAGE);
+    return EXIT_USAGE;
+  }
+  const { configPath, argv } = taken;
+  if (argv[0] !== "prune") return runMcpAccessCli({ argv, output });
+
+  const loaded = await loadAppConfig({ cwd: options.cwd, configPath, appScript: APP_SCRIPT });
+  if (!loaded.ok) {
+    output.error(`softure-mcp: ${loaded.problem}`);
+    return EXIT_FAILED;
+  }
+  return runMcpAccessCli({ config: loaded.config, argv, output });
+}

package/src/cli/index.ts

@@ -0,0 +1,3 @@
+// `@softure-ai/mcp-access/cli`: the `softure-mcp` command for app scripts and container bundles.
+export { runMcpAccessCommand, type RunMcpAccessCommandOptions } from "./command.js";
+export { EXIT_FAILED, EXIT_OK, EXIT_USAGE, MCP_ACCESS_USAGE, runMcpAccessCli, type CliOutput, type RunMcpAccessCliOptions } from "./run.js";

package/src/cli/run.ts

@@ -0,0 +1,79 @@
+// `softure-mcp`: the module's maintenance command. `prune` deletes expired access tokens and dead OAuth
+// records (`pruneMcpAccess`), for a daily job such as a deploy `maintain` hook. The app passes its
+// validated config, so the same function serves the bin and an app script a bundler packs:
+//
+//   // scripts/mcp.ts
+//   import { runMcpAccessCli } from "@softure-ai/mcp-access/cli";
+//   import config from "../softure.config";
+//   process.exitCode = await runMcpAccessCli({ config, argv: process.argv.slice(2) });
+import { errorLogLabel, systemClock, type Clock, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
+import { openCommandDatabase, type CommandDatabase } from "@softure-ai/db";
+import { pruneMcpAccess } from "../server/prune.js";
+
+export interface CliOutput {
+  readonly log: (line: string) => void;
+  readonly error: (line: string) => void;
+}
+
+export interface RunMcpAccessCliOptions {
+  /** The app's config; only help needs none. */
+  readonly config?: SoftureConfig;
+  /** The arguments after the executable, e.g. `["prune"]`. */
+  readonly argv: readonly string[];
+  readonly output?: CliOutput;
+  /** Default: the wall clock. */
+  readonly clock?: Clock;
+  /** Default: the config's `database.handle`, else a connection on `database.url`. */
+  readonly openDatabase?: (database: SoftureDatabaseConfig) => Promise<CommandDatabase>;
+}
+
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+
+export const MCP_ACCESS_USAGE = `Usage:
+  softure-mcp prune    deletes expired access tokens, authorization codes, grants and abandoned clients`;
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+/** Runs one command and answers its exit code. */
+export async function runMcpAccessCli(options: RunMcpAccessCliOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const [command, ...rest] = options.argv;
+  if (command === undefined || command === "--help" || command === "help") {
+    output.log(MCP_ACCESS_USAGE);
+    return EXIT_OK;
+  }
+  if (command !== "prune" || rest.length > 0) {
+    output.error(command === "prune" ? `softure-mcp prune: unexpected argument "${rest[0] ?? ""}"` : `softure-mcp: unknown command "${command}"`);
+    output.error(MCP_ACCESS_USAGE);
+    return EXIT_USAGE;
+  }
+  return prune(options, output);
+}
+
+async function prune(options: RunMcpAccessCliOptions, output: CliOutput): Promise<number> {
+  const database = options.config?.database ?? null;
+  if (options.config === undefined || database === null) {
+    output.error("softure-mcp prune: the config has no database; set database.url in softure.config");
+    return EXIT_FAILED;
+  }
+  let opened: CommandDatabase | undefined;
+  try {
+    opened = await (options.openDatabase ?? ((settings) => openCommandDatabase(settings, { max: 1 })))(database);
+    const removed = await pruneMcpAccess({ db: opened.handle.db, clock: options.clock ?? systemClock, config: options.config });
+    output.log(
+      `softure-mcp prune: removed ${String(removed.accessTokens)} access tokens, ${String(removed.codes)} authorization codes, ${String(removed.grants)} grants, ${String(removed.clients)} clients`,
+    );
+    return EXIT_OK;
+  } catch (error) {
+    // The kind only: a driver message can carry the database address or credentials.
+    output.error(`softure-mcp prune: failed: ${errorLogLabel(error)}`);
+    return EXIT_FAILED;
+  } finally {
+    await opened?.close();
+  }
+}

package/src/contract.ts

@@ -9,8 +9,11 @@ export type McpAccessErrorCode =
   | "mcp-access.token_not_found"
   | "mcp-access.grant_not_found";
 
-/** Every code the token page can show: its own, a missing session and the generic ones. */
-export type TokenFormErrorCode = McpAccessErrorCode | "auth.unauthenticated" | CoreErrorCode;
+/** What an app's `beforeIssue` gate may answer instead of letting a token be issued. */
+export type McpIssueRefusalCode = "mcp-access.issue_refused" | "mcp-access.write_refused";
+
+/** Every code the token page can show: its own, a gate's refusal, a missing session and the generic ones. */
+export type TokenFormErrorCode = McpAccessErrorCode | McpIssueRefusalCode | "auth.unauthenticated" | CoreErrorCode;
 
 /** What the app's MCP server factory receives for one request. */
 export interface McpServerIdentity {

package/src/index.ts

@@ -3,8 +3,10 @@
 // work and the endpoint are in `@softure-ai/mcp-access/server`, the Next.js adapter (route, page,
 // actions) in `/next`, the token manager in `/ui`.
 import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
+import type { RateLimitBucketInput } from "@softure-ai/security";
 import { mcpAccessMessages } from "./messages/index.js";
 import { mcpAccessOptionsSchema } from "./options.js";
+import { DEFAULT_MCP_ACCESS_ROUTES } from "./routes.js";
 import { checkAccessTokensTable } from "./server/health.js";
 import { mcpAccessPrivacyContributor } from "./server/privacy.js";
 
@@ -16,14 +18,14 @@ export const MODULE_ID = "mcp-access";
  * the traffic behind one address (several assistants share it), not for one token.
  */
 export const MCP_RATE_LIMIT_BUCKETS = {
-  mcp: { limit: 200, windowMinutes: 15 },
+  mcp: { limit: 200, windowMinutes: 15, key: "ip" },
   /**
    * OAuth registration (per address) and token requests (per address and client id), when
    * `oauth.enabled`. Enough for an assistant platform refreshing many users' tokens per client,
    * too little for a script filling the clients table.
    */
-  "mcp-oauth": { limit: 60, windowMinutes: 15 },
-} as const;
+  "mcp-oauth": { limit: 60, windowMinutes: 15, key: "ip" },
+} as const satisfies Readonly<Record<string, RateLimitBucketInput>>;
 
 /**
  * Enables MCP access in `softure.config.ts` (after `security` and `auth`):
@@ -32,20 +34,13 @@ export const MCP_RATE_LIMIT_BUCKETS = {
 export const mcpAccess = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.12",
+    version: "0.1.13",
     dependsOn: { security: "^0.1.0", auth: "^0.1.0" },
     dbSchema: "mcp",
     tables: ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants"],
     env: [],
     switches: [],
-    routes: {
-      page: "/account/mcp",
-      endpoint: "/api/mcp",
-      oauthConsent: "/oauth/authorize",
-      oauthDecision: "/api/oauth/authorize",
-      oauthToken: "/api/oauth/token",
-      oauthRegister: "/api/oauth/register",
-    },
+    routes: { ...DEFAULT_MCP_ACCESS_ROUTES },
     mount: [
       { kind: "page", path: "app/account/mcp/page.tsx", export: "McpAccessPage" },
       { kind: "route-handler", path: "app/api/mcp/route.ts", export: "createMcpRoute" },
@@ -81,6 +76,7 @@ export type {
   IssuedToken,
   IssueTokenFormState,
   McpAccessErrorCode,
+  McpIssueRefusalCode,
   McpClientSetup,
   McpServerIdentity,
   OAuthGrantView,
@@ -105,6 +101,7 @@ export {
   type McpToolDefinition,
   type McpToolDefinitionInput,
 } from "./options.js";
+export { DEFAULT_MCP_ACCESS_ROUTES } from "./routes.js";
 export { readRequestOrigin, type McpOriginRequest, type McpOrigins } from "./origins.js";
 export { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants, type OAuthClientRow, type OAuthTokenEndpointAuthMethod } from "./schema.js";
 export { getAccessTokenStatus, type AccessTokenStatusOptions } from "./token-status.js";

package/src/messages/en.ts

@@ -92,6 +92,8 @@ export const en = {
       token_limit_reached: "You already hold the most active tokens allowed. Revoke one before creating another.",
       token_not_found: "This token no longer exists. It may have been revoked already.",
       grant_not_found: "This app is no longer connected.",
+      issue_refused: "Your account cannot create tokens right now.",
+      write_refused: "Your account cannot create tokens with write access. Create a read-only token instead.",
     },
     auth: {
       unauthenticated: "Your session has ended. Log in again.",

package/src/messages/pl.ts

@@ -94,6 +94,8 @@ export const pl: typeof en = {
       token_limit_reached: "Masz już najwięcej aktywnych tokenów, ile można. Unieważnij któryś, zanim utworzysz nowy.",
       token_not_found: "Ten token już nie istnieje. Mógł zostać unieważniony.",
       grant_not_found: "Ta aplikacja nie jest już połączona.",
+      issue_refused: "Twoje konto nie może teraz tworzyć tokenów.",
+      write_refused: "Twoje konto nie może tworzyć tokenów z prawem zapisu. Utwórz token tylko do odczytu.",
     },
     auth: {
       unauthenticated: "Twoja sesja wygasła. Zaloguj się ponownie.",

package/src/next/actions.ts

@@ -4,18 +4,17 @@
 // which the client controls, docs/02 §8) before the form is read, and every query is scoped to
 // that owner. Unexpected failures become `safeError` codes; the token never reaches a log.
 import { getCurrentUser } from "@softure-ai/auth/next";
-import { errorLogLabel, formatMessage, safeError, type SoftureConfig } from "@softure-ai/core";
+import { errorLogLabel, safeError, type SoftureConfig } from "@softure-ai/core";
 import { getSoftureConfig } from "@softure-ai/core/next";
 import { revalidatePath } from "next/cache";
 import { z } from "zod";
-import { getMcpClientSetup } from "../client-setup.js";
 import type { IssueTokenFormState, RevokeGrantFormState, RevokeTokenFormState } from "../contract.js";
 import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
-import { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl } from "../server/options.js";
+import { getMcpAccessRoutes } from "../server/options.js";
 import { revokeOAuthGrant } from "../server/oauth.js";
-import { issueAccessToken, revokeAccessToken } from "../server/tokens.js";
-import { getMcpAccessContext, getRequestOrigins } from "./context.js";
-import { formatDate } from "./format.js";
+import { revokeAccessToken } from "../server/tokens.js";
+import { getMcpAccessContext } from "./context.js";
+import { issueToken } from "./issue-token.js";
 
 /** Longer values are cut: the server functions refuse them anyway, and nothing huge is echoed back. */
 const MAX_FIELD_LENGTH = MAX_TOKEN_NAME_LENGTH * 4;
@@ -24,11 +23,6 @@ const text = z
   .catch("")
   .transform((value) => value.slice(0, MAX_FIELD_LENGTH));
 
-const issueInput = z.object({
-  name: text,
-  // A checked HTML checkbox sends "on"; an unchecked one sends nothing, which means read only.
-  canWrite: z.string().nullable().catch(null),
-});
 const revokeInput = z.object({ id: text });
 
 function reportFailure(operation: string, error: unknown) {
@@ -40,40 +34,9 @@ function refreshPage(config: SoftureConfig): void {
   revalidatePath(getMcpAccessRoutes(config).page);
 }
 
-/** Issues a token for the signed-in user and returns its plaintext with the setup snippets, once. */
-export async function issueTokenAction(_previous: IssueTokenFormState, formData: FormData): Promise<IssueTokenFormState> {
-  const config = getSoftureConfig();
-  const user = await getCurrentUser();
-  if (user === null) return { status: "error", error: "auth.unauthenticated" };
-
-  // Every field has a `catch`, so parsing cannot fail.
-  const input = issueInput.parse({ name: formData.get("name"), canWrite: formData.get("canWrite") });
-  try {
-    // Resolved before issuing: a failure afterwards would leave a token nobody received.
-    const endpointUrl = getMcpEndpointUrl(config, await getRequestOrigins(config, getMcpAccessRoutes(config).page));
-    const result = await issueAccessToken(await getMcpAccessContext(config), { userId: user.id, name: input.name, canWrite: input.canWrite !== null });
-    if (!result.ok) return { status: "error", error: result.error };
-    refreshPage(config);
-    const issued = result.value;
-    const messages = getMcpAccessMessages(config);
-    return {
-      status: "ok",
-      issued: {
-        id: issued.id,
-        name: issued.name,
-        canWrite: issued.canWrite,
-        expiresText: formatMessage(messages.issued.expires, { date: formatDate(config, issued.expiresAt) }),
-        setup: getMcpClientSetup({
-          serverName: getMcpAccessOptions(config).serverName,
-          endpointUrl,
-          token: issued.token,
-          promptTemplate: messages.setup.assistantPrompt,
-        }),
-      },
-    };
-  } catch (error) {
-    return { status: "error", error: reportFailure("issuing a token", error) };
-  }
+/** Issues a token for the signed-in user and returns its plaintext with the setup snippets, once. No gate: see `issueToken`. */
+export async function issueTokenAction(previous: IssueTokenFormState, formData: FormData): Promise<IssueTokenFormState> {
+  return issueToken(previous, formData);
 }
 
 /** Revokes one of the signed-in user's tokens; another account's id matches nothing. */

package/src/next/format.ts

@@ -1,8 +1,8 @@
 // Dates on the token page, in the app's locale and time zone.
-import type { SoftureConfig } from "@softure-ai/core";
+import { formatCalendarDay, toCalendarDay, type SoftureConfig } from "@softure-ai/core";
 
 export function formatDate(config: SoftureConfig, date: Date): string {
-  return new Intl.DateTimeFormat(config.locale, { dateStyle: "long", timeZone: config.timezone }).format(date);
+  return formatCalendarDay(toCalendarDay(date, config.timezone), config.locale, "long");
 }
 
 export function formatDateTime(config: SoftureConfig, date: Date): string {

package/src/next/index.ts

@@ -11,5 +11,6 @@ export {
   registerOAuthClientRoute,
 } from "./oauth-routes.js";
 export { getMcpAccessContext, getRequestOrigins } from "./context.js";
-export { McpAccessPage } from "./pages.js";
+export { issueToken, type BeforeIssueGate, type IssueGateInput, type IssueTokenOptions } from "./issue-token.js";
+export { McpAccessPage, type McpAccessPageProps } from "./pages.js";
 export { createMcpRoute } from "./route.js";

package/src/next/issue-token.ts

@@ -0,0 +1,90 @@
+// Issuing a token from the token page's form, with an optional gate the app puts in front of it (a
+// billing write gate). Not a server action itself: the app calls it from its own `"use server"` file,
+// so the gate stays in the app's code and out of softure.config.ts:
+//
+//   "use server";
+//   export async function issueGatedToken(previous: IssueTokenFormState, form: FormData) {
+//     return issueToken(previous, form, { beforeIssue: checkPlan });
+//   }
+//
+// The owner comes from the session (never from a bound argument, which the client controls, docs/02 §8)
+// before the form is read. Unexpected failures, the gate's included, become `safeError` codes.
+import { getCurrentUser } from "@softure-ai/auth/next";
+import { errorLogLabel, formatMessage, safeError, type Err, type Ok } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { revalidatePath } from "next/cache";
+import { z } from "zod";
+import { getMcpClientSetup } from "../client-setup.js";
+import type { IssueTokenFormState, McpIssueRefusalCode } from "../contract.js";
+import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
+import { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl } from "../server/options.js";
+import { issueAccessToken } from "../server/tokens.js";
+import { getMcpAccessContext, getRequestOrigins } from "./context.js";
+import { formatDate } from "./format.js";
+
+/** Longer values are cut: the server functions refuse them anyway, and nothing huge is echoed back. */
+const MAX_FIELD_LENGTH = MAX_TOKEN_NAME_LENGTH * 4;
+
+const issueInput = z.object({
+  name: z
+    .string()
+    .catch("")
+    .transform((value) => value.slice(0, MAX_FIELD_LENGTH)),
+  // A checked HTML checkbox sends "on"; an unchecked one sends nothing, which means read only.
+  canWrite: z.string().nullable().catch(null),
+});
+
+/** What the gate learns about the token about to be issued. */
+export interface IssueGateInput {
+  readonly userId: string;
+  readonly canWrite: boolean;
+}
+
+/** The app's check before a token is issued: `ok()` lets it through, `err(code)` refuses with a message the page shows. */
+export type BeforeIssueGate = (input: IssueGateInput) => Ok<unknown> | Err<McpIssueRefusalCode> | Promise<Ok<unknown> | Err<McpIssueRefusalCode>>;
+
+export interface IssueTokenOptions {
+  readonly beforeIssue?: BeforeIssueGate;
+}
+
+/** Issues a token for the signed-in user, after the gate, and returns its plaintext with the setup snippets, once. */
+export async function issueToken(_previous: IssueTokenFormState, formData: FormData, options: IssueTokenOptions = {}): Promise<IssueTokenFormState> {
+  const config = getSoftureConfig();
+  const user = await getCurrentUser();
+  if (user === null) return { status: "error", error: "auth.unauthenticated" };
+
+  // Every field has a `catch`, so parsing cannot fail.
+  const input = issueInput.parse({ name: formData.get("name"), canWrite: formData.get("canWrite") });
+  const canWrite = input.canWrite !== null;
+  try {
+    if (options.beforeIssue !== undefined) {
+      const gate = await options.beforeIssue({ userId: user.id, canWrite });
+      if (!gate.ok) return { status: "error", error: gate.error };
+    }
+    // Resolved before issuing: a failure afterwards would leave a token nobody received.
+    const endpointUrl = getMcpEndpointUrl(config, await getRequestOrigins(config, getMcpAccessRoutes(config).page));
+    const result = await issueAccessToken(await getMcpAccessContext(config), { userId: user.id, name: input.name, canWrite });
+    if (!result.ok) return { status: "error", error: result.error };
+    revalidatePath(getMcpAccessRoutes(config).page);
+    const issued = result.value;
+    const messages = getMcpAccessMessages(config);
+    return {
+      status: "ok",
+      issued: {
+        id: issued.id,
+        name: issued.name,
+        canWrite: issued.canWrite,
+        expiresText: formatMessage(messages.issued.expires, { date: formatDate(config, issued.expiresAt) }),
+        setup: getMcpClientSetup({
+          serverName: getMcpAccessOptions(config).serverName,
+          endpointUrl,
+          token: issued.token,
+          promptTemplate: messages.setup.assistantPrompt,
+        }),
+      },
+    };
+  } catch (error) {
+    console.error(`@softure-ai/mcp-access: issuing a token failed: ${errorLogLabel(error)}`);
+    return { status: "error", error: safeError(error).error };
+  }
+}

package/src/next/pages.tsx

@@ -14,7 +14,7 @@ import { getLocalizedText, getMcpAccessMessages, getMcpAccessOptions, getMcpAcce
 import { listOAuthGrants } from "../server/oauth.js";
 import { listAccessTokens } from "../server/tokens.js";
 import { getAccessTokenStatus } from "../token-status.js";
-import { TokenManager, type TokenManagerGrant, type TokenManagerRow, type TokenManagerTool } from "../ui/token-manager.js";
+import { TokenManager, type IssueTokenAction, type TokenManagerGrant, type TokenManagerRow, type TokenManagerTool } from "../ui/token-manager.js";
 import { issueTokenAction, revokeGrantAction, revokeTokenAction } from "./actions.js";
 import { getMcpAccessContext } from "./context.js";
 import { formatDate, formatDateTime } from "./format.js";
@@ -64,7 +64,15 @@ function toTool(tool: McpAccessOptions["tools"][number], config: SoftureConfig,
   return { name: tool.name, description: getLocalizedText(tool.description, config.locale), accessText };
 }
 
-export async function McpAccessPage() {
+export interface McpAccessPageProps {
+  /**
+   * The app's own issue action, e.g. one that calls `issueToken` with a `beforeIssue` gate. Default:
+   * `issueTokenAction`, which issues without a gate.
+   */
+  readonly issueAction?: IssueTokenAction;
+}
+
+export async function McpAccessPage({ issueAction = issueTokenAction }: McpAccessPageProps = {}) {
   const config = getSoftureConfig();
   const user = await requireUser({ next: getMcpAccessRoutes(config).page });
   const options = getMcpAccessOptions(config);
@@ -81,7 +89,7 @@ export async function McpAccessPage() {
           tokens={tokens.map((token) => toRow(token, now, config, options, messages))}
           allowWrites={options.allowWrites}
           maxTokens={options.maxTokensPerUser}
-          issueAction={issueTokenAction}
+          issueAction={issueAction}
           revokeAction={revokeTokenAction}
           {...(grants === null ? {} : { grants: grants.map((grant) => toGrant(grant, config, options, messages)), revokeGrantAction })}
           messages={messages}

package/src/options.ts

@@ -28,6 +28,10 @@ const toolSchema = z.strictObject({
   access: z.enum(["read", "write"]),
   /** What the tool does, for the owner deciding which token to issue. */
   description: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text"),
+  /** A short display name (MCP's `title`), for clients and agent docs that show one. */
+  title: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text").optional(),
+  /** A request a person could make that uses the tool, e.g. "Show my last five orders.", for agent docs. */
+  example: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text").optional(),
 });
 
 /**

package/src/routes.ts

@@ -0,0 +1,17 @@
+// The routes the module mounts, as constants for code that cannot read the config: a proxy matcher,
+// a client, a test. The manifest declares the same object.
+
+export const DEFAULT_MCP_ACCESS_ROUTES = {
+  /** The token page. */
+  page: "/account/mcp",
+  /** `POST` MCP endpoint. */
+  endpoint: "/api/mcp",
+  /** OAuth consent page, the authorization endpoint. */
+  oauthConsent: "/oauth/authorize",
+  /** `POST` target of the consent form. */
+  oauthDecision: "/api/oauth/authorize",
+  /** `POST` OAuth token endpoint. */
+  oauthToken: "/api/oauth/token",
+  /** `POST` dynamic client registration. */
+  oauthRegister: "/api/oauth/register",
+} as const;

package/src/server/action-tool.ts

@@ -0,0 +1,64 @@
+// A server action as a write tool: the tool's arguments become the form the action reads, so the tool
+// and the form share one validation path, and the action's error state becomes a tool error.
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import { describeCode, toolError, toolResult, withToolErrors, type ToolErrorHints } from "./tools.js";
+
+/** The action, called with the form. A `useActionState` action is passed as `(form) => action(INITIAL, form)`. */
+export type FormActionHandler = (formData: FormData) => unknown;
+
+export interface ActionToolOptions {
+  /** The answer on success: a text, or a text built from the action's state. Default: the state as JSON. */
+  readonly message?: string | ((state: unknown) => string);
+  /** Texts per error code, as in `withToolErrors`. */
+  readonly hints?: ToolErrorHints;
+  /** The tool's name in the log line. */
+  readonly label?: string;
+}
+
+/** The tool callback for `server.registerTool(name, { inputSchema }, actionTool(handler))`. */
+export function actionTool(handler: FormActionHandler, options: ActionToolOptions = {}): (args: Readonly<Record<string, unknown>>) => Promise<CallToolResult> {
+  const hints = options.hints ?? {};
+  return (args) =>
+    withToolErrors(
+      async () => {
+        const state = await handler(toFormData(args));
+        const error = readErrorCode(state);
+        if (error !== null) return toolError(describeCode(error, hints));
+        if (options.message === undefined) return toolResult(state);
+        return toolResult(typeof options.message === "string" ? options.message : options.message(state));
+      },
+      { hints, ...(options.label === undefined ? {} : { label: options.label }) },
+    );
+}
+
+/**
+ * Arguments as a submitted form: strings as they are, numbers as text, `true` as `"on"` (a checked
+ * checkbox) and `false`, `null` and `undefined` left out (an unchecked one), arrays one entry per item,
+ * dates as ISO text, objects as JSON.
+ */
+export function toFormData(args: Readonly<Record<string, unknown>>): FormData {
+  const form = new FormData();
+  for (const [name, value] of Object.entries(args)) {
+    for (const item of Array.isArray(value) ? (value as unknown[]) : [value]) {
+      const field = toFieldValue(item);
+      if (field !== null) form.append(name, field);
+    }
+  }
+  return form;
+}
+
+function toFieldValue(value: unknown): string | null {
+  if (value === undefined || value === null || value === false) return null;
+  if (value === true) return "on";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return value.toString();
+  if (value instanceof Date) return value.toISOString();
+  return JSON.stringify(value);
+}
+
+/** The error code of an action state: `{ ok: false, error }` (core's result) or `{ status: "error", error }` (a form state). */
+function readErrorCode(state: unknown): string | null {
+  if (typeof state !== "object" || state === null || !("error" in state) || typeof state.error !== "string") return null;
+  const isFailure = ("ok" in state && state.ok === false) || ("status" in state && state.status === "error");
+  return isFailure ? state.error : null;
+}

package/src/server/index.ts

@@ -10,6 +10,7 @@ export {
   type McpEndpointOptions,
   type McpServerFactory,
 } from "./endpoint.js";
+export { actionTool, toFormData, type ActionToolOptions, type FormActionHandler } from "./action-tool.js";
 export { createMcpAccessContext } from "./context.js";
 export { checkAccessTokensTable } from "./health.js";
 export {
@@ -68,6 +69,7 @@ export type { OAuthClientRow, OAuthTokenEndpointAuthMethod } from "../schema.js"
 export { describeRedirectUri, isAllowedRedirectUri, MAX_CLIENT_NAME_LENGTH, parseClientRegistration, type ClientRegistrationResult, type RegistrationError } from "./oauth-validation.js";
 export { getCodeChallenge, isPkceVerifierValid, isValidCodeChallenge, PKCE_METHOD } from "./pkce.js";
 export { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl, type McpAccessRoutes } from "./options.js";
+export { pruneMcpAccess, type PrunedMcpAccessRecords } from "./prune.js";
 export {
   deleteMcpAccessUserData,
   exportMcpAccessUserData,
@@ -90,3 +92,4 @@ export {
   type RevokeAccessTokenInput,
   type VerifiedAccessToken,
 } from "./tokens.js";
+export { toolError, toolResult, withToolErrors, type ToolErrorHints, type ToolErrorOptions } from "./tools.js";

package/src/server/prune.ts

@@ -0,0 +1,14 @@
+// The module's scheduled cleanup: expired access tokens and dead OAuth records of every account, in
+// one call for a daily job (`softure-mcp prune`, a deploy `maintain` hook) instead of inline on requests.
+import { pruneOAuthRecords, type PrunedOAuthRecords } from "./oauth.js";
+import { pruneAccessTokens, type McpAccessContext } from "./tokens.js";
+
+export interface PrunedMcpAccessRecords extends PrunedOAuthRecords {
+  readonly accessTokens: number;
+}
+
+/** Runs `pruneAccessTokens`, then `pruneOAuthRecords`, and counts what each removed. */
+export async function pruneMcpAccess(ctx: McpAccessContext): Promise<PrunedMcpAccessRecords> {
+  const accessTokens = await pruneAccessTokens(ctx);
+  return { accessTokens, ...(await pruneOAuthRecords(ctx)) };
+}