@softure-ai/mcp-access 0.0.0-stage → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+Newest first. Each version lists what changed for an app that uses `@softure-ai/mcp-access`. When an app has run a version in
+production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
+"Definition of done"). Versions before the first one below are described in their GitHub Releases (`mcp-access@x.y.z`).
+
+## 0.1.6
+
+- Adapters use the configured database handle; `@softure-ai/ui` is a peer dependency.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOFTURE
+
+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

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# @softure-ai/mcp-access
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lets the users of a Next.js app connect an AI assistant (Claude Code, Claude Desktop, Cursor) to
+their own data over MCP: hashed, scoped, expiring access tokens, a rate-limited Bearer endpoint
+around the app's own MCP server, and a token page with ready setup instructions. Built from
+FIRE_TRACKER's assistant access (`src/db/access-tokens.ts`, `src/lib/{mcp-auth,access-token-status,mcp-client-config}.ts`,
+`src/app/api/mcp/route.ts`, `src/app/actions/{manage-tokens,tokens,tokens-contract}.ts`), with the
+domain server left to the app and the limit check made race-free.
+
+## 1. What it provides
+
+- The table `mcp.access_tokens`: name, read or write access, expiry, last use; **only the sha256** of
+  each token. A token is `sftmcp_` and 32 random bytes; the plaintext is shown once and stored nowhere.
+- `POST /api/mcp`: identifies the client and counts the request (bucket `mcp`), verifies the
+  `Authorization: Bearer` token, then hands the request to a **fresh server from the app's factory**
+  with `{ userId, canWrite, tokenId }`. Unknown, revoked, expired and malformed tokens all get the
+  same `401 invalid_token` with a `WWW-Authenticate: Bearer` challenge.
+- **Writes need two consents:** the app's `allowWrites` option and a token issued with write
+  access. `canWrite` is decided on every request, so turning `allowWrites` off makes every token
+  read-only at once.
+- A token page for the signed-in user: the app's tool catalog, an issue form, the new token with its
+  setup (a prompt for Claude Code and a `claude-cli://` link, the `claude mcp add` command, an
+  `mcpServers` file, Claude Desktop through `mcp-remote`, the header), and the user's tokens with
+  their status (active, expiring in n days, expired), last use and a revoke button.
+- Server functions for scripts and other hosts, and a health check for `GET /api/health`.
+
+OAuth for MCP (discovery, dynamic client registration) is not part of this module: clients that
+send a static header cover the personal-token case.
+
+## 2. Installation
+
+```bash
+npm install @softure-ai/mcp-access @softure-ai/auth @softure-ai/security @softure-ai/core @softure-ai/db @softure-ai/ui @modelcontextprotocol/server drizzle-orm zod
+```
+
+Peer dependencies: `@modelcontextprotocol/server` `^2.0.0` (the app's factory and the endpoint
+must use one copy of the SDK), `next` 16, `react` 19, `drizzle-orm`. The module depends on `auth`
+and `security`; a configuration without them fails at startup.
+
+## 3. Configuration
+
+```ts
+import { auth, AUTH_RATE_LIMIT_BUCKETS } from "@softure-ai/auth";
+import { MCP_RATE_LIMIT_BUCKETS, mcpAccess } from "@softure-ai/mcp-access";
+import { cloudflareIp, security } from "@softure-ai/security";
+import { en } from "./messages/en";
+import { pl } from "./messages/pl";
+
+// in defineSoftureConfig({ modules: [...] }):
+security({ clientIp: cloudflareIp(), buckets: { ...AUTH_RATE_LIMIT_BUCKETS, ...MCP_RATE_LIMIT_BUCKETS } }),
+auth({ ... }),
+mcpAccess({
+  serverName: "acme",
+  allowWrites: true,
+  tools: [
+    { name: "list_orders", access: "read", description: { en: en.mcp.listOrders, pl: pl.mcp.listOrders } },
+    { name: "cancel_order", access: "write", description: { en: en.mcp.cancelOrder, pl: pl.mcp.cancelOrder } },
+  ],
+}),
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `serverName` | `string` | required | The name clients list the server under (lowercase, digits, inner dashes; no quotes needed in a shell). |
+| `tools` | `{ name, access: "read" \| "write", description: { en, pl? } }[]` | `[]` | The catalog the token page shows. Keep it next to the factory; the example app tests that both list the same tools. |
+| `allowWrites` | `boolean` | `false` | Lets write tokens be issued and used. Off, the page offers no write tokens and every token reads only. |
+| `tokenLifetimeDays` | `integer` 1–365 | `90` | How long a token works. There is no renewal: the user issues a new one. |
+| `maxTokensPerUser` | `integer` 1–100 | `20` | Unexpired tokens one account may hold. Counted under a per-user lock, so parallel requests cannot overshoot. |
+| `expiryWarningDays` | `integer` 0–60 | `14` | From how many calendar days before the expiry the list warns. |
+| `routes` | `{ page?, endpoint? }` | `/account/mcp`, `/api/mcp` | Move the page or the endpoint; the endpoint URL in the setup is `appOrigin` + `endpoint`. |
+| `messages` | partial `en` / `pl` | — | Copy overrides. |
+
+`MCP_RATE_LIMIT_BUCKETS` is `{ mcp: { limit: 200, windowMinutes: 15 } }` per client address. Every
+request counts, valid or not, and before the token lookup; assistants behind one address share it.
+
+## 4. Mounting
+
+```ts
+// app/api/mcp/route.ts
+import { createMcpRoute } from "@softure-ai/mcp-access/next";
+import { createServer } from "../../../lib/mcp-server";
+
+export const POST = createMcpRoute({ createServer });
+```
+
+```ts
+// app/account/mcp/page.tsx
+export { McpAccessPage as default } from "@softure-ai/mcp-access/next";
+export const dynamic = "force-dynamic";
+```
+
+The factory is the app's own MCP server, built per request:
+
+```ts
+// lib/mcp-server.ts
+import { McpServer } from "@modelcontextprotocol/server";
+import type { McpServerIdentity } from "@softure-ai/mcp-access";
+
+export function createServer({ userId, canWrite }: McpServerIdentity): McpServer {
+  const server = new McpServer({ name: "acme", version: "1.0.0" });
+  server.registerTool("list_orders", { description: "Lists your orders." }, () => listOrders(userId));
+  if (canWrite) server.registerTool("cancel_order", { ... }, (input) => cancelOrder(userId, input));
+  return server;
+}
+```
+
+Every query of the server must be scoped to `userId`; register write tools only when `canWrite`
+is true. GET and DELETE are not exported, so Next answers them with 405: the endpoint is stateless.
+Answers to 2025-era clients come as one SSE `message` event, to 2026-07-28 clients as plain JSON;
+mid-call notifications (progress, logging) are dropped. Keep `/api/mcp` out of a proxy guard that
+redirects to the login page: the endpoint authenticates by token, not by cookie.
+
+`TokenManager` (`@softure-ai/mcp-access/ui`) takes the actions `issueTokenAction` and
+`revokeTokenAction` (`/next`) as props for an app that composes its own page.
+
+## 5. Migrations and tables
+
+`migrations/0001_create_access_tokens.sql` creates `mcp.access_tokens`:
+
+| Column | Meaning |
+| --- | --- |
+| `id uuid` | The token's id: what the list and the revoke action name, and what logs may carry. |
+| `user_id uuid` | The owner, `REFERENCES auth.users ON DELETE CASCADE`: deleting an account deletes its tokens. |
+| `name text` | 1–60 characters, trimmed. |
+| `token_hash text` | sha256 hex, unique. |
+| `can_write boolean` | Issued with write access (still needs `allowWrites`). |
+| `created_at`, `expires_at` | `expires_at > created_at`; a token works while `expires_at > now`. |
+| `last_used_at` | Written on verification at most once a minute; informational only. |
+
+Issuing deletes the issuer's expired tokens; `pruneAccessTokens(ctx)` (`/server`) deletes every
+expired token, for a scheduled job. Rollback: in the migration header.
+
+## 6. Environment variables
+
+None of its own. The endpoint URL comes from `appOrigin` in `softure.config.ts`.
+
+## 7. Switches
+
+None. `allowWrites` is configuration, not a runtime switch: changing who may write is a deploy.
+
+## 8. Appearance
+
+`TokenManager` slots: `root`, `section`, `heading`, `text`, `list`, `item`, `itemHeader`, `badge`,
+`details`, `snippet`, `code`; `unstyled` renders structure only. Styling comes from
+`@softure-ai/ui` classes on the `--sft-*` tokens; the module ships no CSS of its own.
+
+## 9. Copy
+
+`mcpAccessMessages.{en,pl}`: `page`, `tools`, `issue`, `issued`, `setup.assistantPrompt`
+(placeholders `{serverName}` and `{command}`), `list`, and `errors` for the codes
+`mcp-access.name_required`, `name_too_long`, `token_limit_reached`, `token_not_found`,
+`auth.unauthenticated`, `core.database_failed` and `core.unexpected`. Tool descriptions come from
+the `tools` option, per locale.
+
+## 10. Hooks
+
+The MCP server factory passed to `createMcpRoute` is the module's only hook. `/server` also exports
+`createMcpEndpoint({ createServer })`, a `(ctx, request) => Response` for hosts other than Next, and
+`issueAccessToken`, `listAccessTokens`, `revokeAccessToken`, `verifyAccessToken` and
+`pruneAccessTokens` for scripts.
+
+## 11. GDPR
+
+The rows hold no personal data beyond the owner's id and the token names. The module contributes
+to `@softure-ai/privacy` (`privacy` flags on):
+
+- **Export** (`exportMcpAccessUserData`): `accessTokens`, each token's name, write flag and
+  created, expiry and last-use dates. Never the token hash.
+- **Deletion** (`deleteMcpAccessUserData`): every token of the user, before auth deletes the
+  account (the foreign key's cascade would remove them too).
+
+## 12. Limitations / known gaps
+
+- No OAuth for MCP: clients without a header field use `mcp-remote` (Claude Desktop) or another
+  bridge.
+- Write access is per token, not per tool; finer scopes would be a new option.
+- The rate limit is per client address, not per token.
+- `responseMode: "json"` drops mid-call notifications; a streaming tool would need a different mode.

package/dist/client-setup.d.ts

@@ -0,0 +1,32 @@
+import type { McpClientSetup } from "./contract.js";
+export interface McpClientSetupInput {
+    readonly serverName: string;
+    readonly endpointUrl: string;
+    readonly token: string;
+    /** The assistant prompt template from the messages: `{serverName}` and `{command}`. */
+    readonly promptTemplate: string;
+}
+/**
+ * The `Authorization` value, with its scheme. Clients with a header field send it verbatim, and
+ * the endpoint refuses a header without `Bearer `.
+ */
+export declare function getAuthorizationHeader(token: string): string;
+/**
+ * `claude mcp add` with the token in it, not a placeholder: the plaintext is shown once, so this
+ * is the only moment a working command can be built for the user. `--scope user` connects the
+ * server everywhere, not only in the folder the terminal happens to be in.
+ */
+export declare function getClaudeCodeCommand(serverName: string, endpointUrl: string, token: string): string;
+/** The `mcpServers` block for clients configured by a file. */
+export declare function getJsonConfig(serverName: string, endpointUrl: string, token: string): string;
+/**
+ * Claude Desktop's file runs local servers only, so a remote one goes through `mcp-remote`. The
+ * header sits in `args` without a space (`Authorization:${AUTH_HEADER}`) and its value in `env`:
+ * Claude Desktop on Windows splits arguments on spaces. `${AUTH_HEADER}` is a literal that
+ * `mcp-remote` substitutes. `-y` keeps `npx` from waiting for a confirmation nobody can give.
+ */
+export declare function getDesktopConfig(serverName: string, endpointUrl: string, token: string): string;
+/** Opens Claude Code with the prompt; Claude Code shows it and waits for Enter, it runs nothing alone. */
+export declare function getClaudeCodeLink(prompt: string): string;
+export declare function getMcpClientSetup({ serverName, endpointUrl, token, promptTemplate }: McpClientSetupInput): McpClientSetup;
+//# sourceMappingURL=client-setup.d.ts.map

package/dist/client-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-setup.d.ts","sourceRoot":"","sources":["../src/client-setup.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnG;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG5F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/F;AAED,0GAA0G;AAC1G,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,iBAAiB,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,mBAAmB,GAAG,cAAc,CAazH"}

package/dist/client-setup.js

@@ -0,0 +1,57 @@
+// Ready-to-paste MCP client setup, built around the plaintext token (FIRE_TRACKER
+// `src/lib/mcp-client-config.ts`, generalised to the app's server name and URL). Pure functions:
+// the issue action calls them once, while the plaintext exists.
+import { formatMessage } from "@softure-ai/core";
+/**
+ * The `Authorization` value, with its scheme. Clients with a header field send it verbatim, and
+ * the endpoint refuses a header without `Bearer `.
+ */
+export function getAuthorizationHeader(token) {
+    return `Bearer ${token.trim()}`;
+}
+/**
+ * `claude mcp add` with the token in it, not a placeholder: the plaintext is shown once, so this
+ * is the only moment a working command can be built for the user. `--scope user` connects the
+ * server everywhere, not only in the folder the terminal happens to be in.
+ */
+export function getClaudeCodeCommand(serverName, endpointUrl, token) {
+    return ["claude mcp add --transport http --scope user", serverName, endpointUrl, `--header "Authorization: ${getAuthorizationHeader(token)}"`].join(" ");
+}
+/** The `mcpServers` block for clients configured by a file. */
+export function getJsonConfig(serverName, endpointUrl, token) {
+    const server = { type: "http", url: endpointUrl, headers: { Authorization: getAuthorizationHeader(token) } };
+    return JSON.stringify({ mcpServers: { [serverName]: server } }, null, 2);
+}
+/**
+ * Claude Desktop's file runs local servers only, so a remote one goes through `mcp-remote`. The
+ * header sits in `args` without a space (`Authorization:${AUTH_HEADER}`) and its value in `env`:
+ * Claude Desktop on Windows splits arguments on spaces. `${AUTH_HEADER}` is a literal that
+ * `mcp-remote` substitutes. `-y` keeps `npx` from waiting for a confirmation nobody can give.
+ */
+export function getDesktopConfig(serverName, endpointUrl, token) {
+    const server = {
+        command: "npx",
+        args: ["-y", "mcp-remote", endpointUrl, "--header", "Authorization:${AUTH_HEADER}"],
+        env: { AUTH_HEADER: getAuthorizationHeader(token) },
+    };
+    return JSON.stringify({ mcpServers: { [serverName]: server } }, null, 2);
+}
+/** Opens Claude Code with the prompt; Claude Code shows it and waits for Enter, it runs nothing alone. */
+export function getClaudeCodeLink(prompt) {
+    return `claude-cli://open?q=${encodeURIComponent(prompt)}`;
+}
+export function getMcpClientSetup({ serverName, endpointUrl, token, promptTemplate }) {
+    const claudeCodeCommand = getClaudeCodeCommand(serverName, endpointUrl, token);
+    const assistantPrompt = formatMessage(promptTemplate, { serverName, command: claudeCodeCommand });
+    return {
+        serverName,
+        endpointUrl,
+        claudeCodeCommand,
+        assistantPrompt,
+        claudeCodeLink: getClaudeCodeLink(assistantPrompt),
+        jsonConfig: getJsonConfig(serverName, endpointUrl, token),
+        desktopConfig: getDesktopConfig(serverName, endpointUrl, token),
+        authorizationHeader: getAuthorizationHeader(token),
+    };
+}
+//# sourceMappingURL=client-setup.js.map

package/dist/client-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-setup.js","sourceRoot":"","sources":["../src/client-setup.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,iGAAiG;AACjG,gEAAgE;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAWjD;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,OAAO,UAAU,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAkB,EAAE,WAAmB,EAAE,KAAa;IACzF,OAAO,CAAC,8CAA8C,EAAE,UAAU,EAAE,WAAW,EAAE,4BAA4B,sBAAsB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3J,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,WAAmB,EAAE,KAAa;IAClF,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,sBAAsB,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;IAC7G,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,WAAmB,EAAE,KAAa;IACrF,MAAM,MAAM,GAAG;QACb,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,8BAA8B,CAAC;QACnF,GAAG,EAAE,EAAE,WAAW,EAAE,sBAAsB,CAAC,KAAK,CAAC,EAAE;KACpD,CAAC;IACF,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO,uBAAuB,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAuB;IACvG,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,UAAU,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;IAC/E,MAAM,eAAe,GAAG,aAAa,CAAC,cAAc,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC,CAAC;IAClG,OAAO;QACL,UAAU;QACV,WAAW;QACX,iBAAiB;QACjB,eAAe;QACf,cAAc,EAAE,iBAAiB,CAAC,eAAe,CAAC;QAClD,UAAU,EAAE,aAAa,CAAC,UAAU,EAAE,WAAW,EAAE,KAAK,CAAC;QACzD,aAAa,EAAE,gBAAgB,CAAC,UAAU,EAAE,WAAW,EAAE,KAAK,CAAC;QAC/D,mBAAmB,EAAE,sBAAsB,CAAC,KAAK,CAAC;KACnD,CAAC;AACJ,CAAC"}

package/dist/contract.d.ts

@@ -0,0 +1,80 @@
+import type { CoreErrorCode } from "@softure-ai/core";
+export type McpAccessErrorCode = "mcp-access.name_required" | "mcp-access.name_too_long" | "mcp-access.token_limit_reached" | "mcp-access.token_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 the app's MCP server factory receives for one request. */
+export interface McpServerIdentity {
+    /** The auth user id of the token's owner: every query of the server is scoped to it. */
+    readonly userId: string;
+    /** Whether write tools may be registered: the app allows writes and the token was issued for them. */
+    readonly canWrite: boolean;
+    /** The token's id, for the server's own logs. Never the token. */
+    readonly tokenId: string;
+}
+/** A stored token as its owner sees it. The hash never leaves the server functions. */
+export interface AccessTokenView {
+    readonly id: string;
+    readonly name: string;
+    /** Issued with write access (it still writes only while the app allows writes). */
+    readonly canWrite: boolean;
+    readonly createdAt: Date;
+    readonly expiresAt: Date;
+    readonly lastUsedAt: Date | null;
+}
+/** Where a token stands on its expiry, for the list. */
+export type AccessTokenStatus = {
+    readonly kind: "active";
+}
+/** `daysLeft`: calendar days in the app's time zone, from 0 (today) to the warning threshold. */
+ | {
+    readonly kind: "expiring";
+    readonly daysLeft: number;
+} | {
+    readonly kind: "expired";
+};
+/** Ready-to-paste setup for MCP clients, built around the plaintext token. */
+export interface McpClientSetup {
+    readonly serverName: string;
+    readonly endpointUrl: string;
+    /** `claude mcp add …` for Claude Code, with the token in it. */
+    readonly claudeCodeCommand: string;
+    /** A prompt asking the assistant to run that command and confirm the connection. */
+    readonly assistantPrompt: string;
+    /** A `claude-cli://` link that opens Claude Code with the prompt (it runs nothing by itself). */
+    readonly claudeCodeLink: string;
+    /** `mcpServers` JSON for clients configured by file (Cursor, VS Code, Windsurf). */
+    readonly jsonConfig: string;
+    /** Claude Desktop's file, bridged through `mcp-remote` (it cannot send headers itself). */
+    readonly desktopConfig: string;
+    /** The `Authorization` header value, for clients with a header field. */
+    readonly authorizationHeader: string;
+}
+/** A token right after it was issued: the only moment its plaintext exists outside the client. */
+export interface IssuedToken {
+    readonly id: string;
+    readonly name: string;
+    readonly canWrite: boolean;
+    /** The expiry, already formatted in the app's locale and time zone. */
+    readonly expiresText: string;
+    readonly setup: McpClientSetup;
+}
+/** What the issue action returns to its form (`useActionState`). */
+export type IssueTokenFormState = {
+    readonly status: "idle";
+} | {
+    readonly status: "ok";
+    readonly issued: IssuedToken;
+} | {
+    readonly status: "error";
+    readonly error: TokenFormErrorCode;
+};
+/** What the revoke action returns to one token's form. */
+export type RevokeTokenFormState = {
+    readonly status: "idle";
+} | {
+    readonly status: "ok";
+} | {
+    readonly status: "error";
+    readonly error: TokenFormErrorCode;
+};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+export declare const MODULE_ID = "mcp-access";
+/**
+ * The rate limit bucket of `POST /api/mcp`, to spread into `security({ buckets })`: requests per
+ * client address, counted before the token is verified. Every request counts, so the limit is for
+ * the traffic behind one address (several assistants share it), not for one token.
+ */
+export declare const MCP_RATE_LIMIT_BUCKETS: {
+    readonly mcp: {
+        readonly limit: 200;
+        readonly windowMinutes: 15;
+    };
+};
+/**
+ * Enables MCP access in `softure.config.ts` (after `security` and `auth`):
+ * `mcpAccess({ serverName: "acme", tools: [{ name: "list_orders", access: "read", description: { en: "Lists your orders." } }] })`.
+ */
+export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
+    page: string;
+    endpoint: string;
+}, {
+    page: {
+        title: string;
+        lead: string;
+    };
+    tools: {
+        title: string;
+        empty: string;
+        read: string;
+        write: string;
+        writeUnavailable: string;
+    };
+    issue: {
+        title: string;
+        name: string;
+        nameHint: string;
+        canWrite: string;
+        canWriteHint: string;
+        submit: string;
+        pending: string;
+        limit: string;
+    };
+    issued: {
+        title: string;
+        once: string;
+        expires: string;
+        readOnly: string;
+        readWrite: string;
+        promptTitle: string;
+        promptHint: string;
+        openClaudeCode: string;
+        commandTitle: string;
+        jsonTitle: string;
+        desktopTitle: string;
+        headerTitle: string;
+        copy: string;
+        copied: string;
+        done: string;
+    };
+    setup: {
+        assistantPrompt: string;
+    };
+    list: {
+        title: string;
+        empty: string;
+        readOnly: string;
+        readWrite: string;
+        active: string;
+        expired: string;
+        expiresToday: string;
+        expiresTomorrow: string;
+        expiresInDays: string;
+        expiresOn: string;
+        expiredOn: string;
+        createdOn: string;
+        lastUsed: string;
+        neverUsed: string;
+        revoke: string;
+        revoking: string;
+    };
+    errors: {
+        "mcp-access": {
+            name_required: string;
+            name_too_long: string;
+            token_limit_reached: string;
+            token_not_found: string;
+        };
+        auth: {
+            unauthenticated: string;
+        };
+        core: {
+            database_failed: string;
+            unexpected: string;
+        };
+    };
+}, import("zod").ZodObject<{
+    serverName: import("zod").ZodString;
+    tools: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+        name: import("zod").ZodString;
+        access: import("zod").ZodEnum<{
+            read: "read";
+            write: "write";
+        }>;
+        description: import("zod").ZodRecord<import("zod").ZodEnum<{
+            en: "en";
+            pl: "pl";
+        }> & import("zod/v4/core").$partial, import("zod").ZodString>;
+    }, import("zod/v4/core").$strict>>>;
+    allowWrites: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    tokenLifetimeDays: import("zod").ZodDefault<import("zod").ZodInt>;
+    maxTokensPerUser: import("zod").ZodDefault<import("zod").ZodInt>;
+    expiryWarningDays: import("zod").ZodDefault<import("zod").ZodInt>;
+}, import("zod/v4/core").$strict>>;
+export { getAuthorizationHeader, getClaudeCodeCommand, getClaudeCodeLink, getDesktopConfig, getJsonConfig, getMcpClientSetup, type McpClientSetupInput, } from "./client-setup.js";
+export type { AccessTokenStatus, AccessTokenView, IssuedToken, IssueTokenFormState, McpAccessErrorCode, McpClientSetup, McpServerIdentity, RevokeTokenFormState, TokenFormErrorCode, } from "./contract.js";
+export { getTokenErrorMessage, mcpAccessMessages, type McpAccessMessages } from "./messages/index.js";
+export { MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, type McpAccessOptions, type McpAccessOptionsInput, type McpToolAccess, type McpToolDefinition, type McpToolDefinitionInput, } from "./options.js";
+export { accessTokens } from "./schema.js";
+export { getAccessTokenStatus, type AccessTokenStatusOptions } from "./token-status.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;CAEzB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAqBpB,CAAC;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,50 @@
+// Public API of @softure-ai/mcp-access: the module factory for softure.config.ts, its rate limit
+// bucket, types, messages, table and the pure helpers for token status and client setup. Database
+// 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 { mcpAccessMessages } from "./messages/index.js";
+import { mcpAccessOptionsSchema } from "./options.js";
+import { checkAccessTokensTable } from "./server/health.js";
+import { mcpAccessPrivacyContributor } from "./server/privacy.js";
+export const MODULE_ID = "mcp-access";
+/**
+ * The rate limit bucket of `POST /api/mcp`, to spread into `security({ buckets })`: requests per
+ * client address, counted before the token is verified. Every request counts, so the limit is for
+ * the traffic behind one address (several assistants share it), not for one token.
+ */
+export const MCP_RATE_LIMIT_BUCKETS = {
+    mcp: { limit: 200, windowMinutes: 15 },
+};
+/**
+ * Enables MCP access in `softure.config.ts` (after `security` and `auth`):
+ * `mcpAccess({ serverName: "acme", tools: [{ name: "list_orders", access: "read", description: { en: "Lists your orders." } }] })`.
+ */
+export const mcpAccess = defineModule({
+    manifest: {
+        id: MODULE_ID,
+        version: "0.1.6",
+        dependsOn: { security: "^0.1.0", auth: "^0.1.0" },
+        dbSchema: "mcp",
+        tables: ["access_tokens"],
+        env: [],
+        switches: [],
+        routes: { page: "/account/mcp", endpoint: "/api/mcp" },
+        mount: [
+            { kind: "page", path: "app/account/mcp/page.tsx", export: "McpAccessPage" },
+            { kind: "route-handler", path: "app/api/mcp/route.ts", export: "createMcpRoute" },
+        ],
+        privacy: { exports: true, deletes: true },
+    },
+    messages: mcpAccessMessages,
+    options: mcpAccessOptionsSchema,
+    migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
+    privacy: mcpAccessPrivacyContributor,
+    health: checkAccessTokensTable,
+});
+export { getAuthorizationHeader, getClaudeCodeCommand, getClaudeCodeLink, getDesktopConfig, getJsonConfig, getMcpClientSetup, } from "./client-setup.js";
+export { getTokenErrorMessage, mcpAccessMessages } from "./messages/index.js";
+export { MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, } from "./options.js";
+export { accessTokens } from "./schema.js";
+export { getAccessTokenStatus } from "./token-status.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,kGAAkG;AAClG,kGAAkG;AAClG,mDAAmD;AACnD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAElE,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC;AAEtC;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE;CAC9B,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC;IACpC,QAAQ,EAAE;QACR,EAAE,EAAE,SAAS;QACb,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;QACjD,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,CAAC,eAAe,CAAC;QACzB,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE;QACtD,KAAK,EAAE;YACL,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,EAAE,MAAM,EAAE,eAAe,EAAE;YAC3E,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,gBAAgB,EAAE;SAClF;QACD,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE;KAC1C;IACD,QAAQ,EAAE,iBAAiB;IAC3B,OAAO,EAAE,sBAAsB;IAC/B,UAAU,EAAE,EAAE,GAAG,EAAE,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE;IAC5E,OAAO,EAAE,2BAA2B;IACpC,MAAM,EAAE,sBAAsB;CAC/B,CAAC,CAAC;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAElB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAA0B,MAAM,qBAAqB,CAAC;AACtG,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,GAMlB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAiC,MAAM,mBAAmB,CAAC"}