@happyvertical/smrt-app-mcp 0.30.0

package/AGENTS.md

@@ -0,0 +1,22 @@
+# @happyvertical/smrt-app-mcp
+
+Application-scoped MCP server wrapper for SMRT apps.
+
+## Purpose
+
+- Wraps `@happyvertical/smrt-core` MCP generation with app-level tool allow-lists.
+- Filters unauthenticated tool visibility to public read-only tools.
+- Provides workflow assertions so app servers can reject unsafe or incomplete tool calls before dispatch.
+
+## Patterns
+
+- Generate tools from core, then filter by allowed class-name prefixes.
+- Treat list/get tools as read-only; mutating tools require authentication unless the app deliberately wraps them with stronger policy.
+- Keep app policy outside generated tool schemas. The wrapper owns auth, allow-list, and workflow assertion behavior.
+- Return 404 for tools outside the app allow-list so private generated tools are not enumerated by mistake.
+
+## Gotchas
+
+- Public tool patterns are still constrained by read-only detection.
+- Workflow assertions run before generated tool dispatch and should be deterministic.
+- This package is runtime app infrastructure, not the development MCP. Use `@happyvertical/smrt-dev-mcp` for agentic development knowledge, review, and architecture tooling.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+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

@@ -0,0 +1,47 @@
+# @happyvertical/smrt-app-mcp
+
+App-runtime MCP server scaffolding for SMRT apps. Provides:
+
+- **Core** — `createMcpAppServer({ smrtOptions, serverInfo, allowedClassNames, publicToolPatterns?, workflowAssertions? })` returning `{ listTools, callTool }` wired to `@happyvertical/smrt-core/generators/mcp`.
+- **SvelteKit adapters** (`./sveltekit`) — `mountMcpToolsRoute` / `mountMcpCallRoute` for `/api/mcp/{tools,call}/+server.ts`.
+
+For piping a deployed app's MCP surface to a local stdio MCP client, see `@happyvertical/smrt-app-cli` — the client-side runtime CLI exposes a `startMcpBridge()` default and a generic `smrt-mcp-bridge` bin.
+
+```ts
+// src/lib/server/mcp.ts
+import { createMcpAppServer, McpAccessError } from '@happyvertical/smrt-app-mcp';
+import { adminResources } from '$lib/admin/resources';
+import { getDbConfig } from './db';
+
+export const mcpServer = createMcpAppServer({
+  smrtOptions: () => ({ db: getDbConfig() }),
+  serverInfo: { name: 'my-app', version: '0.1.0' },
+  allowedClassNames: adminResources.map((r) => r.className),
+  publicToolPatterns: () =>
+    (process.env.MY_APP_PUBLIC_MCP_TOOLS ?? '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+  workflowAssertions: {
+    application_update: (args, user) => {
+      if (!user?.id) throw new McpAccessError(401, 'sign in first');
+      args.approvedByUserId = user.id;
+    },
+  },
+});
+```
+
+```ts
+// src/routes/api/mcp/tools/+server.ts
+import { mountMcpToolsRoute } from '@happyvertical/smrt-app-mcp/sveltekit';
+import { mcpServer } from '$lib/server/mcp';
+export const GET = mountMcpToolsRoute(mcpServer);
+```
+
+```ts
+// src/routes/api/mcp/call/+server.ts
+import { mountMcpCallRoute } from '@happyvertical/smrt-app-mcp/sveltekit';
+import { mcpServer } from '$lib/server/mcp';
+export const POST = mountMcpCallRoute(mcpServer);
+```
+

package/dist/chunks/errors-W_2Xu9nk.js

@@ -0,0 +1,12 @@
+class McpAccessError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "McpAccessError";
+  }
+  status;
+}
+export {
+  McpAccessError as M
+};
+//# sourceMappingURL=errors-W_2Xu9nk.js.map

package/dist/chunks/errors-W_2Xu9nk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-W_2Xu9nk.js","sources":["../../src/errors.ts"],"sourcesContent":["/**\n * Error returned by the MCP app server when a caller tries to use a tool\n * they are not allowed to access. The HTTP layer should map `status` onto\n * the response status code.\n */\nexport class McpAccessError extends Error {\n  constructor(\n    readonly status: number,\n    message: string,\n  ) {\n    super(message);\n    this.name = 'McpAccessError';\n  }\n}\n"],"names":[],"mappings":"AAKO,MAAM,uBAAuB,MAAM;AAAA,EACxC,YACW,QACT,SACA;AACA,UAAM,OAAO;AAHJ,SAAA,SAAA;AAIT,SAAK,OAAO;AAAA,EACd;AAAA,EALW;AAMb;"}

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * `@happyvertical/smrt-app-mcp` — app-runtime MCP server scaffolding for
+ * SMRT apps. Exposes a SMRT app's MCP surface over HTTP, regardless of how
+ * the app is deployed.
+ *
+ * - **Core** (this module): `createMcpAppServer` wraps
+ *   `@happyvertical/smrt-core/generators/mcp` with allow-listing, a public
+ *   tool policy, and per-tool workflow assertions. Returns
+ *   `{ listTools, callTool }` you can mount however you like.
+ *
+ * - **SvelteKit** (`@happyvertical/smrt-app-mcp/sveltekit`): thin route
+ *   adapters that turn an `McpAppServer` into the GET/POST handlers a
+ *   SvelteKit `+server.ts` expects. Additional transport adapters
+ *   (standalone Node HTTP, serverless, Express/Hono/Fastify) can be added
+ *   as sibling subpaths without changes to the core.
+ *
+ * For piping a deployed app's MCP surface to a local stdio MCP client
+ * (e.g. for editor/AI client integration), see
+ * `@happyvertical/smrt-app-cli` — the client-side counterpart owns the
+ * stdio bridge.
+ *
+ * @packageDocumentation
+ */
+
+import { MCPConfig } from '@happyvertical/smrt-core/generators/mcp';
+import { MCPResponse } from '@happyvertical/smrt-core/generators/mcp';
+import { MCPTool } from '@happyvertical/smrt-core/generators/mcp';
+
+/** Tool call inputs. */
+export declare interface CallToolInput {
+    name: string;
+    arguments?: Record<string, unknown>;
+    /** Authenticated user; null/undefined means unauthenticated. */
+    user?: McpAppUser | null;
+}
+
+/**
+ * Lower-case `<class>_` prefixes the app considers "allowed core tools"
+ * given a list of SMRT class names. Used to build the allow-list for
+ * `McpAppServer.listTools`.
+ */
+export declare function classNamePrefixes(classNames: readonly string[]): ReadonlySet<string>;
+
+/**
+ * Build the app-runtime MCP server core. The returned object is intentionally
+ * framework-agnostic: HTTP wrappers live in `@happyvertical/smrt-app-mcp/sveltekit`
+ * and a stdio bridge lives in `@happyvertical/smrt-app-mcp/bin/smrt-mcp-bridge`.
+ */
+export declare function createMcpAppServer(options: CreateMcpAppServerOptions): McpAppServer;
+
+/**
+ * Options for `createMcpAppServer`.
+ */
+export declare interface CreateMcpAppServerOptions {
+    /** SMRT context bag (db, etc.) passed to MCPGenerator per call. */
+    smrtOptions: McpSmrtOptionsThunk;
+    /** Server identity surfaced in the MCP protocol. */
+    serverInfo: Required<Pick<MCPConfig, 'name' | 'version'>> & Pick<MCPConfig, 'description'>;
+    /**
+     * SMRT class names the app wants to publish. Tools whose name does not
+     * start with any of these classes (lowercased + underscore) are filtered
+     * out, even if SMRT generated them.
+     */
+    allowedClassNames: readonly string[];
+    /**
+     * Optional thunk returning glob-ish patterns for read-only tools that
+     * unauthenticated callers are allowed to use. Defaults to an empty list
+     * (everything requires auth).
+     */
+    publicToolPatterns?: McpPublicToolPatternsThunk;
+    /**
+     * Optional per-tool guards. Keyed by tool name. The assertion runs after
+     * tool resolution and before `MCPGenerator.handleToolCall`; throwing
+     * `McpAccessError` aborts the call with the error's status. Implementations
+     * may mutate `args` to inject trusted fields.
+     */
+    workflowAssertions?: Record<string, McpWorkflowAssertion>;
+}
+
+/**
+ * Whether a given tool name starts with any of the configured class
+ * prefixes.
+ */
+export declare function isAllowedCoreTool(toolName: string, prefixes: ReadonlySet<string>): boolean;
+
+/**
+ * Check whether a tool name is currently allowed for unauthenticated callers
+ * given the configured public-tool patterns. Only read-only tools may ever
+ * be public, regardless of pattern.
+ */
+export declare function isPublicToolName(toolName: string, patterns: readonly string[]): boolean;
+
+/**
+ * Read-only tool detection. Generated SMRT MCP tools follow the naming
+ * convention `<class>_<verb>`; we treat `_list` and `_get` as read-only.
+ */
+export declare function isReadOnlyToolName(toolName: string): boolean;
+
+/** Tool listing inputs. */
+export declare interface ListToolsInput {
+    /** Whether the calling principal is authenticated. */
+    authenticated: boolean;
+}
+
+/**
+ * Match a tool name against a glob-ish pattern with `*` wildcards.
+ *
+ * - Empty pattern → never matches.
+ * - `*` → matches everything.
+ * - `prefix_*` → matches anything starting with `prefix_`.
+ * - `*_suffix` → matches anything ending with `_suffix`.
+ * - `a_*_b` → matches any name containing `a_`, then any text, then `_b`.
+ *
+ * No regex characters are special besides `*` — the input is treated as a
+ * literal string with star wildcards.
+ */
+export declare function matchesToolPattern(toolName: string, pattern: string): boolean;
+
+/**
+ * Error returned by the MCP app server when a caller tries to use a tool
+ * they are not allowed to access. The HTTP layer should map `status` onto
+ * the response status code.
+ */
+export declare class McpAccessError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+/** Shape returned by `createMcpAppServer`. */
+export declare interface McpAppServer {
+    listTools(input: ListToolsInput): Promise<MCPTool[]>;
+    callTool(input: CallToolInput): Promise<MCPResponse>;
+    /** Read-only view of the configured server identity. */
+    readonly serverInfo: CreateMcpAppServerOptions['serverInfo'];
+}
+
+/** Minimal user shape used for tool-call attribution. */
+export declare interface McpAppUser {
+    id: string;
+    roles?: string[];
+}
+
+/** Public-tool patterns thunk — same lazy-evaluation rationale. */
+export declare type McpPublicToolPatternsThunk = () => readonly string[];
+
+/**
+ * SMRT options thunk — returns the `{ db }` (and similar) bag to pass into
+ * MCPGenerator's per-request context. A function is used so apps can lazily
+ * resolve env vars at call time.
+ */
+export declare type McpSmrtOptionsThunk = () => Record<string, unknown>;
+
+/**
+ * Workflow assertion hook signature. Throw `McpAccessError` to reject the
+ * call. Implementations may mutate `args` in place to inject server-trusted
+ * fields (e.g. clamping `approvedByUserId` to the authenticated user's id).
+ */
+export declare type McpWorkflowAssertion = (args: Record<string, unknown>, user: McpAppUser | null) => void;
+
+export { }

package/dist/index.js

@@ -0,0 +1,90 @@
+import { M as McpAccessError } from "./chunks/errors-W_2Xu9nk.js";
+import { MCPGenerator } from "@happyvertical/smrt-core/generators/mcp";
+function matchesToolPattern(toolName, pattern) {
+  if (!pattern) return false;
+  if (pattern === "*") return true;
+  const parts = pattern.split("*");
+  if (parts.length === 1) return toolName === pattern;
+  let cursor = 0;
+  if (parts[0] && !toolName.startsWith(parts[0])) return false;
+  for (const part of parts) {
+    if (!part) continue;
+    const index = toolName.indexOf(part, cursor);
+    if (index < 0) return false;
+    cursor = index + part.length;
+  }
+  const last = parts.at(-1);
+  return !last || toolName.endsWith(last);
+}
+function isReadOnlyToolName(toolName) {
+  return toolName.endsWith("_list") || toolName.endsWith("_get");
+}
+function isPublicToolName(toolName, patterns) {
+  return isReadOnlyToolName(toolName) && patterns.some((pattern) => matchesToolPattern(toolName, pattern));
+}
+function classNamePrefixes(classNames) {
+  return new Set(classNames.map((className) => `${className.toLowerCase()}_`));
+}
+function isAllowedCoreTool(toolName, prefixes) {
+  for (const prefix of prefixes) {
+    if (toolName.startsWith(prefix)) return true;
+  }
+  return false;
+}
+function createMcpAppServer(options) {
+  const allowedPrefixes = classNamePrefixes(options.allowedClassNames);
+  const getPublicPatterns = options.publicToolPatterns ?? (() => []);
+  const workflowAssertions = options.workflowAssertions ?? {};
+  function makeGenerator(user) {
+    return new MCPGenerator(options.serverInfo, {
+      ...options.smrtOptions(),
+      user: user?.id ? { id: user.id, roles: user.roles } : void 0
+    });
+  }
+  async function listTools(input) {
+    const tools = await makeGenerator().generateTools();
+    const allowed = tools.filter(
+      (tool) => isAllowedCoreTool(tool.name, allowedPrefixes)
+    );
+    if (input.authenticated) return allowed;
+    const patterns = getPublicPatterns();
+    return allowed.filter((tool) => isPublicToolName(tool.name, patterns));
+  }
+  async function callTool(input) {
+    const args = input.arguments ?? {};
+    const user = input.user ?? null;
+    const tools = await listTools({ authenticated: true });
+    if (!tools.some((tool) => tool.name === input.name)) {
+      throw new McpAccessError(404, `Unknown MCP tool: ${input.name}`);
+    }
+    if (!user && !isPublicToolName(input.name, getPublicPatterns())) {
+      throw new McpAccessError(
+        401,
+        `Authentication is required for MCP tool: ${input.name}`
+      );
+    }
+    const assertion = workflowAssertions[input.name];
+    if (assertion) {
+      assertion(args, user);
+    }
+    return makeGenerator(user).handleToolCall({
+      method: "tools/call",
+      params: { arguments: args, name: input.name }
+    });
+  }
+  return {
+    listTools,
+    callTool,
+    serverInfo: options.serverInfo
+  };
+}
+export {
+  McpAccessError,
+  classNamePrefixes,
+  createMcpAppServer,
+  isAllowedCoreTool,
+  isPublicToolName,
+  isReadOnlyToolName,
+  matchesToolPattern
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/tools.ts","../src/server.ts"],"sourcesContent":["/**\n * Tool-name policy helpers — used by `McpAppServer` to filter the full set\n * of generated tools down to what the calling principal is allowed to see,\n * and to decide whether an unauthenticated tool call should be permitted.\n *\n * @packageDocumentation\n */\n\n/**\n * Match a tool name against a glob-ish pattern with `*` wildcards.\n *\n * - Empty pattern → never matches.\n * - `*` → matches everything.\n * - `prefix_*` → matches anything starting with `prefix_`.\n * - `*_suffix` → matches anything ending with `_suffix`.\n * - `a_*_b` → matches any name containing `a_`, then any text, then `_b`.\n *\n * No regex characters are special besides `*` — the input is treated as a\n * literal string with star wildcards.\n */\nexport function matchesToolPattern(toolName: string, pattern: string): boolean {\n  if (!pattern) return false;\n  if (pattern === '*') return true;\n\n  const parts = pattern.split('*');\n  if (parts.length === 1) return toolName === pattern;\n\n  let cursor = 0;\n  if (parts[0] && !toolName.startsWith(parts[0])) return false;\n  for (const part of parts) {\n    if (!part) continue;\n    const index = toolName.indexOf(part, cursor);\n    if (index < 0) return false;\n    cursor = index + part.length;\n  }\n\n  const last = parts.at(-1);\n  return !last || toolName.endsWith(last);\n}\n\n/**\n * Read-only tool detection. Generated SMRT MCP tools follow the naming\n * convention `<class>_<verb>`; we treat `_list` and `_get` as read-only.\n */\nexport function isReadOnlyToolName(toolName: string): boolean {\n  return toolName.endsWith('_list') || toolName.endsWith('_get');\n}\n\n/**\n * Check whether a tool name is currently allowed for unauthenticated callers\n * given the configured public-tool patterns. Only read-only tools may ever\n * be public, regardless of pattern.\n */\nexport function isPublicToolName(\n  toolName: string,\n  patterns: readonly string[],\n): boolean {\n  return (\n    isReadOnlyToolName(toolName) &&\n    patterns.some((pattern) => matchesToolPattern(toolName, pattern))\n  );\n}\n\n/**\n * Lower-case `<class>_` prefixes the app considers \"allowed core tools\"\n * given a list of SMRT class names. Used to build the allow-list for\n * `McpAppServer.listTools`.\n */\nexport function classNamePrefixes(\n  classNames: readonly string[],\n): ReadonlySet<string> {\n  return new Set(classNames.map((className) => `${className.toLowerCase()}_`));\n}\n\n/**\n * Whether a given tool name starts with any of the configured class\n * prefixes.\n */\nexport function isAllowedCoreTool(\n  toolName: string,\n  prefixes: ReadonlySet<string>,\n): boolean {\n  for (const prefix of prefixes) {\n    if (toolName.startsWith(prefix)) return true;\n  }\n  return false;\n}\n","/**\n * `createMcpAppServer` returns the framework-agnostic core that backs an\n * app's HTTP MCP endpoints and stdio bridge. It wraps `MCPGenerator` from\n * `@happyvertical/smrt-core` with:\n *\n *  - an allow-list of SMRT class names (so apps publish a subset of their\n *    objects, not everything decorated with `@smrt()`),\n *  - a public-tool policy for unauthenticated callers (read-only patterns\n *    via `publicToolPatterns`),\n *  - a pluggable `workflowAssertions` hook so apps can guard their own\n *    domain-specific tool calls (e.g. \"approval requires an authenticated\n *    user\") without that policy living in this package.\n *\n * @packageDocumentation\n */\n\nimport type {\n  MCPConfig,\n  MCPResponse,\n  MCPTool,\n} from '@happyvertical/smrt-core/generators/mcp';\nimport { MCPGenerator } from '@happyvertical/smrt-core/generators/mcp';\nimport { McpAccessError } from './errors.js';\nimport {\n  classNamePrefixes,\n  isAllowedCoreTool,\n  isPublicToolName,\n} from './tools.js';\n\n/** Minimal user shape used for tool-call attribution. */\nexport interface McpAppUser {\n  id: string;\n  roles?: string[];\n}\n\n/**\n * Workflow assertion hook signature. Throw `McpAccessError` to reject the\n * call. Implementations may mutate `args` in place to inject server-trusted\n * fields (e.g. clamping `approvedByUserId` to the authenticated user's id).\n */\nexport type McpWorkflowAssertion = (\n  args: Record<string, unknown>,\n  user: McpAppUser | null,\n) => void;\n\n/**\n * SMRT options thunk — returns the `{ db }` (and similar) bag to pass into\n * MCPGenerator's per-request context. A function is used so apps can lazily\n * resolve env vars at call time.\n */\nexport type McpSmrtOptionsThunk = () => Record<string, unknown>;\n\n/** Public-tool patterns thunk — same lazy-evaluation rationale. */\nexport type McpPublicToolPatternsThunk = () => readonly string[];\n\n/**\n * Options for `createMcpAppServer`.\n */\nexport interface CreateMcpAppServerOptions {\n  /** SMRT context bag (db, etc.) passed to MCPGenerator per call. */\n  smrtOptions: McpSmrtOptionsThunk;\n  /** Server identity surfaced in the MCP protocol. */\n  serverInfo: Required<Pick<MCPConfig, 'name' | 'version'>> &\n    Pick<MCPConfig, 'description'>;\n  /**\n   * SMRT class names the app wants to publish. Tools whose name does not\n   * start with any of these classes (lowercased + underscore) are filtered\n   * out, even if SMRT generated them.\n   */\n  allowedClassNames: readonly string[];\n  /**\n   * Optional thunk returning glob-ish patterns for read-only tools that\n   * unauthenticated callers are allowed to use. Defaults to an empty list\n   * (everything requires auth).\n   */\n  publicToolPatterns?: McpPublicToolPatternsThunk;\n  /**\n   * Optional per-tool guards. Keyed by tool name. The assertion runs after\n   * tool resolution and before `MCPGenerator.handleToolCall`; throwing\n   * `McpAccessError` aborts the call with the error's status. Implementations\n   * may mutate `args` to inject trusted fields.\n   */\n  workflowAssertions?: Record<string, McpWorkflowAssertion>;\n}\n\n/** Tool listing inputs. */\nexport interface ListToolsInput {\n  /** Whether the calling principal is authenticated. */\n  authenticated: boolean;\n}\n\n/** Tool call inputs. */\nexport interface CallToolInput {\n  name: string;\n  arguments?: Record<string, unknown>;\n  /** Authenticated user; null/undefined means unauthenticated. */\n  user?: McpAppUser | null;\n}\n\n/** Shape returned by `createMcpAppServer`. */\nexport interface McpAppServer {\n  listTools(input: ListToolsInput): Promise<MCPTool[]>;\n  callTool(input: CallToolInput): Promise<MCPResponse>;\n  /** Read-only view of the configured server identity. */\n  readonly serverInfo: CreateMcpAppServerOptions['serverInfo'];\n}\n\n/**\n * Build the app-runtime MCP server core. The returned object is intentionally\n * framework-agnostic: HTTP wrappers live in `@happyvertical/smrt-app-mcp/sveltekit`\n * and a stdio bridge lives in `@happyvertical/smrt-app-mcp/bin/smrt-mcp-bridge`.\n */\nexport function createMcpAppServer(\n  options: CreateMcpAppServerOptions,\n): McpAppServer {\n  const allowedPrefixes = classNamePrefixes(options.allowedClassNames);\n  const getPublicPatterns =\n    options.publicToolPatterns ?? ((): readonly string[] => []);\n  const workflowAssertions = options.workflowAssertions ?? {};\n\n  function makeGenerator(user?: McpAppUser | null): MCPGenerator {\n    return new MCPGenerator(options.serverInfo as MCPConfig, {\n      ...options.smrtOptions(),\n      user: user?.id ? { id: user.id, roles: user.roles } : undefined,\n    });\n  }\n\n  async function listTools(input: ListToolsInput): Promise<MCPTool[]> {\n    const tools = await makeGenerator().generateTools();\n    const allowed = tools.filter((tool) =>\n      isAllowedCoreTool(tool.name, allowedPrefixes),\n    );\n    if (input.authenticated) return allowed;\n    const patterns = getPublicPatterns();\n    return allowed.filter((tool) => isPublicToolName(tool.name, patterns));\n  }\n\n  async function callTool(input: CallToolInput): Promise<MCPResponse> {\n    const args = input.arguments ?? {};\n    const user = input.user ?? null;\n    const tools = await listTools({ authenticated: true });\n    if (!tools.some((tool) => tool.name === input.name)) {\n      throw new McpAccessError(404, `Unknown MCP tool: ${input.name}`);\n    }\n\n    if (!user && !isPublicToolName(input.name, getPublicPatterns())) {\n      throw new McpAccessError(\n        401,\n        `Authentication is required for MCP tool: ${input.name}`,\n      );\n    }\n\n    const assertion = workflowAssertions[input.name];\n    if (assertion) {\n      assertion(args, user);\n    }\n\n    return makeGenerator(user).handleToolCall({\n      method: 'tools/call',\n      params: { arguments: args, name: input.name },\n    });\n  }\n\n  return {\n    listTools,\n    callTool,\n    serverInfo: options.serverInfo,\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/manifest.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.0.0",
+  "timestamp": 1782177067289,
+  "packageName": "@happyvertical/smrt-app-mcp",
+  "packageVersion": "0.30.0",
+  "objects": {},
+  "moduleType": "smrt",
+  "smrtDependencies": [
+    "@happyvertical/smrt-core"
+  ]
+}

package/dist/smrt-knowledge.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-06-23T01:11:08.388Z",
+  "packageName": "@happyvertical/smrt-app-mcp",
+  "packageVersion": "0.30.0",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "4a8ec60d5f8af35f27c15d4ef0713d0931026d05f93cd7b6a29b8c5c9f563bc0",
+    "packageJson": "8324f7bf966036f890661be6ebebabd0d4fec45afca13d494eb0e010a75e61f1",
+    "agents": "fd1dc36d1530f81aae49e6efa2e2f5011a8a62d30816f25649d4cb597fc5662a"
+  },
+  "exports": [
+    ".",
+    "./sveltekit"
+  ],
+  "dependencies": {
+    "@happyvertical/smrt-core": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@types/node": "25.0.9",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-core"
+  ],
+  "sdkDependencies": [],
+  "tags": [],
+  "risks": [],
+  "objects": [],
+  "surfaces": [],
+  "prompts": [],
+  "relationshipsV2": {
+    "foreignKeyFields": 0,
+    "crossPackageRefFields": 0,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 0
+  },
+  "agentDoc": "# @happyvertical/smrt-app-mcp\n\nApplication-scoped MCP server wrapper for SMRT apps.\n\n## Purpose\n\n- Wraps `@happyvertical/smrt-core` MCP generation with app-level tool allow-lists.\n- Filters unauthenticated tool visibility to public read-only tools.\n- Provides workflow assertions so app servers can reject unsafe or incomplete tool calls before dispatch.\n\n## Patterns\n\n- Generate tools from core, then filter by allowed class-name prefixes.\n- Treat list/get tools as read-only; mutating tools require authentication unless the app deliberately wraps them with stronger policy.\n- Keep app policy outside generated tool schemas. The wrapper owns auth, allow-list, and workflow assertion behavior.\n- Return 404 for tools outside the app allow-list so private generated tools are not enumerated by mistake.\n\n## Gotchas\n\n- Public tool patterns are still constrained by read-only detection.\n- Workflow assertions run before generated tool dispatch and should be deterministic.\n- This package is runtime app infrastructure, not the development MCP. Use `@happyvertical/smrt-dev-mcp` for agentic development knowledge, review, and architecture tooling.\n"
+}

package/dist/sveltekit.d.ts

@@ -0,0 +1,127 @@
+import { MCPConfig } from '@happyvertical/smrt-core/generators/mcp';
+import { MCPResponse } from '@happyvertical/smrt-core/generators/mcp';
+import { MCPTool } from '@happyvertical/smrt-core/generators/mcp';
+
+/** Tool call inputs. */
+declare interface CallToolInput {
+    name: string;
+    arguments?: Record<string, unknown>;
+    /** Authenticated user; null/undefined means unauthenticated. */
+    user?: McpAppUser | null;
+}
+
+/**
+ * Options for `createMcpAppServer`.
+ */
+declare interface CreateMcpAppServerOptions {
+    /** SMRT context bag (db, etc.) passed to MCPGenerator per call. */
+    smrtOptions: McpSmrtOptionsThunk;
+    /** Server identity surfaced in the MCP protocol. */
+    serverInfo: Required<Pick<MCPConfig, 'name' | 'version'>> & Pick<MCPConfig, 'description'>;
+    /**
+     * SMRT class names the app wants to publish. Tools whose name does not
+     * start with any of these classes (lowercased + underscore) are filtered
+     * out, even if SMRT generated them.
+     */
+    allowedClassNames: readonly string[];
+    /**
+     * Optional thunk returning glob-ish patterns for read-only tools that
+     * unauthenticated callers are allowed to use. Defaults to an empty list
+     * (everything requires auth).
+     */
+    publicToolPatterns?: McpPublicToolPatternsThunk;
+    /**
+     * Optional per-tool guards. Keyed by tool name. The assertion runs after
+     * tool resolution and before `MCPGenerator.handleToolCall`; throwing
+     * `McpAccessError` aborts the call with the error's status. Implementations
+     * may mutate `args` to inject trusted fields.
+     */
+    workflowAssertions?: Record<string, McpWorkflowAssertion>;
+}
+
+/** Tool listing inputs. */
+declare interface ListToolsInput {
+    /** Whether the calling principal is authenticated. */
+    authenticated: boolean;
+}
+
+/**
+ * Error returned by the MCP app server when a caller tries to use a tool
+ * they are not allowed to access. The HTTP layer should map `status` onto
+ * the response status code.
+ */
+export declare class McpAccessError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+/** Shape returned by `createMcpAppServer`. */
+export declare interface McpAppServer {
+    listTools(input: ListToolsInput): Promise<MCPTool[]>;
+    callTool(input: CallToolInput): Promise<MCPResponse>;
+    /** Read-only view of the configured server identity. */
+    readonly serverInfo: CreateMcpAppServerOptions['serverInfo'];
+}
+
+/** Minimal user shape used for tool-call attribution. */
+declare interface McpAppUser {
+    id: string;
+    roles?: string[];
+}
+
+/** Public-tool patterns thunk — same lazy-evaluation rationale. */
+declare type McpPublicToolPatternsThunk = () => readonly string[];
+
+/**
+ * SMRT options thunk — returns the `{ db }` (and similar) bag to pass into
+ * MCPGenerator's per-request context. A function is used so apps can lazily
+ * resolve env vars at call time.
+ */
+declare type McpSmrtOptionsThunk = () => Record<string, unknown>;
+
+/** Locals reader used to pull the authenticated user out of `event.locals`. */
+export declare type McpUserResolver = (event: SvelteKitRequestEvent) => McpAppUser | null | undefined;
+
+/**
+ * Workflow assertion hook signature. Throw `McpAccessError` to reject the
+ * call. Implementations may mutate `args` in place to inject server-trusted
+ * fields (e.g. clamping `approvedByUserId` to the authenticated user's id).
+ */
+declare type McpWorkflowAssertion = (args: Record<string, unknown>, user: McpAppUser | null) => void;
+
+/**
+ * Mount `server.callTool` as a `POST` handler that expects
+ * `{ name, arguments }` in the JSON body.
+ */
+export declare function mountMcpCallRoute(server: McpAppServer, options?: MountMcpRouteOptions): SvelteKitHandler;
+
+/** Options shared by both route mounts. */
+export declare interface MountMcpRouteOptions {
+    /**
+     * Resolve the authenticated user from `event.locals`. Defaults to
+     * `event.locals.user`.
+     */
+    resolveUser?: McpUserResolver;
+    /**
+     * Resolve whether the request is authenticated. Defaults to
+     * `Boolean(event.locals.user)`.
+     */
+    resolveAuthenticated?: (event: SvelteKitRequestEvent) => boolean;
+}
+
+/**
+ * Mount `server.listTools` as a `GET` handler. Returns the tool list shape
+ * `{ tools }` for compatibility with the stock MCP bridge.
+ */
+export declare function mountMcpToolsRoute(server: McpAppServer, options?: MountMcpRouteOptions): SvelteKitHandler;
+
+declare type SvelteKitHandler = (event: SvelteKitRequestEvent) => Promise<Response>;
+
+/** Minimal subset of a SvelteKit RequestEvent we actually touch. */
+declare type SvelteKitRequestEvent = {
+    locals?: Record<string, unknown>;
+    request: Request;
+    url: URL;
+};
+
+export { }

package/dist/sveltekit.js

@@ -0,0 +1,53 @@
+import { M as McpAccessError } from "./chunks/errors-W_2Xu9nk.js";
+const defaultResolveUser = (event) => event.locals?.user ?? null;
+const defaultResolveAuthenticated = (event) => Boolean(event.locals?.user);
+function mountMcpToolsRoute(server, options = {}) {
+  const resolveAuthenticated = options.resolveAuthenticated ?? defaultResolveAuthenticated;
+  return async (event) => {
+    try {
+      const tools = await server.listTools({
+        authenticated: resolveAuthenticated(event)
+      });
+      return jsonResponse({ tools });
+    } catch (error) {
+      if (error instanceof McpAccessError) {
+        return jsonResponse({ error: error.message }, error.status);
+      }
+      throw error;
+    }
+  };
+}
+function mountMcpCallRoute(server, options = {}) {
+  const resolveUser = options.resolveUser ?? defaultResolveUser;
+  return async (event) => {
+    const body = await event.request.json().catch(() => null);
+    if (!body?.name) {
+      return jsonResponse({ error: "name is required." }, 400);
+    }
+    const input = {
+      arguments: body.arguments ?? {},
+      name: body.name,
+      user: resolveUser(event) ?? null
+    };
+    try {
+      return jsonResponse(await server.callTool(input));
+    } catch (error) {
+      if (error instanceof McpAccessError) {
+        return jsonResponse({ error: error.message }, error.status);
+      }
+      throw error;
+    }
+  };
+}
+function jsonResponse(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" }
+  });
+}
+export {
+  McpAccessError,
+  mountMcpCallRoute,
+  mountMcpToolsRoute
+};
+//# sourceMappingURL=sveltekit.js.map

package/dist/sveltekit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sveltekit.js","sources":["../src/sveltekit.ts"],"sourcesContent":["/**\n * SvelteKit route adapters for an `McpAppServer`. Mirrors the\n * `@happyvertical/smrt-users/sveltekit` pattern: minimal `HandleInput` type\n * so we never need `@sveltejs/kit` as a real dependency.\n *\n * @packageDocumentation\n *\n * @example\n * ```ts\n * // src/routes/api/mcp/tools/+server.ts\n * import { mountMcpToolsRoute } from '@happyvertical/smrt-app-mcp/sveltekit';\n * import { mcpServer } from '$lib/server/mcp';\n * export const GET = mountMcpToolsRoute(mcpServer);\n * ```\n */\n\nimport { McpAccessError } from './errors.js';\nimport type { CallToolInput, McpAppServer, McpAppUser } from './server.js';\n\n/** Minimal subset of a SvelteKit RequestEvent we actually touch. */\ntype SvelteKitRequestEvent = {\n  locals?: Record<string, unknown>;\n  request: Request;\n  url: URL;\n};\n\ntype SvelteKitHandler = (event: SvelteKitRequestEvent) => Promise<Response>;\n\n/** Locals reader used to pull the authenticated user out of `event.locals`. */\nexport type McpUserResolver = (\n  event: SvelteKitRequestEvent,\n) => McpAppUser | null | undefined;\n\nconst defaultResolveUser: McpUserResolver = (event) =>\n  (event.locals?.user ?? null) as McpAppUser | null;\n\nconst defaultResolveAuthenticated = (event: SvelteKitRequestEvent): boolean =>\n  Boolean(event.locals?.user);\n\n/** Options shared by both route mounts. */\nexport interface MountMcpRouteOptions {\n  /**\n   * Resolve the authenticated user from `event.locals`. Defaults to\n   * `event.locals.user`.\n   */\n  resolveUser?: McpUserResolver;\n  /**\n   * Resolve whether the request is authenticated. Defaults to\n   * `Boolean(event.locals.user)`.\n   */\n  resolveAuthenticated?: (event: SvelteKitRequestEvent) => boolean;\n}\n\n/**\n * Mount `server.listTools` as a `GET` handler. Returns the tool list shape\n * `{ tools }` for compatibility with the stock MCP bridge.\n */\nexport function mountMcpToolsRoute(\n  server: McpAppServer,\n  options: MountMcpRouteOptions = {},\n): SvelteKitHandler {\n  const resolveAuthenticated =\n    options.resolveAuthenticated ?? defaultResolveAuthenticated;\n\n  return async (event) => {\n    try {\n      const tools = await server.listTools({\n        authenticated: resolveAuthenticated(event),\n      });\n      return jsonResponse({ tools });\n    } catch (error) {\n      if (error instanceof McpAccessError) {\n        return jsonResponse({ error: error.message }, error.status);\n      }\n      throw error;\n    }\n  };\n}\n\n/**\n * Mount `server.callTool` as a `POST` handler that expects\n * `{ name, arguments }` in the JSON body.\n */\nexport function mountMcpCallRoute(\n  server: McpAppServer,\n  options: MountMcpRouteOptions = {},\n): SvelteKitHandler {\n  const resolveUser = options.resolveUser ?? defaultResolveUser;\n\n  return async (event) => {\n    const body = (await event.request.json().catch(() => null)) as {\n      arguments?: Record<string, unknown>;\n      name?: string;\n    } | null;\n\n    if (!body?.name) {\n      return jsonResponse({ error: 'name is required.' }, 400);\n    }\n\n    const input: CallToolInput = {\n      arguments: body.arguments ?? {},\n      name: body.name,\n      user: resolveUser(event) ?? null,\n    };\n\n    try {\n      return jsonResponse(await server.callTool(input));\n    } catch (error) {\n      if (error instanceof McpAccessError) {\n        return jsonResponse({ error: error.message }, error.status);\n      }\n      throw error;\n    }\n  };\n}\n\nfunction jsonResponse(body: unknown, status = 200): Response {\n  return new Response(JSON.stringify(body), {\n    status,\n    headers: { 'content-type': 'application/json' },\n  });\n}\n\nexport { McpAccessError } from './errors.js';\nexport type { McpAppServer } from './server.js';\n"],"names":[],"mappings":";AAiCA,MAAM,qBAAsC,CAAC,UAC1C,MAAM,QAAQ,QAAQ;AAEzB,MAAM,8BAA8B,CAAC,UACnC,QAAQ,MAAM,QAAQ,IAAI;AAoBrB,SAAS,mBACd,QACA,UAAgC,IACd;AAClB,QAAM,uBACJ,QAAQ,wBAAwB;AAElC,SAAO,OAAO,UAAU;AACtB,QAAI;AACF,YAAM,QAAQ,MAAM,OAAO,UAAU;AAAA,QACnC,eAAe,qBAAqB,KAAK;AAAA,MAAA,CAC1C;AACD,aAAO,aAAa,EAAE,OAAO;AAAA,IAC/B,SAAS,OAAO;AACd,UAAI,iBAAiB,gBAAgB;AACnC,eAAO,aAAa,EAAE,OAAO,MAAM,QAAA,GAAW,MAAM,MAAM;AAAA,MAC5D;AACA,YAAM;AAAA,IACR;AAAA,EACF;AACF;AAMO,SAAS,kBACd,QACA,UAAgC,IACd;AAClB,QAAM,cAAc,QAAQ,eAAe;AAE3C,SAAO,OAAO,UAAU;AACtB,UAAM,OAAQ,MAAM,MAAM,QAAQ,OAAO,MAAM,MAAM,IAAI;AAKzD,QAAI,CAAC,MAAM,MAAM;AACf,aAAO,aAAa,EAAE,OAAO,oBAAA,GAAuB,GAAG;AAAA,IACzD;AAEA,UAAM,QAAuB;AAAA,MAC3B,WAAW,KAAK,aAAa,CAAA;AAAA,MAC7B,MAAM,KAAK;AAAA,MACX,MAAM,YAAY,KAAK,KAAK;AAAA,IAAA;AAG9B,QAAI;AACF,aAAO,aAAa,MAAM,OAAO,SAAS,KAAK,CAAC;AAAA,IAClD,SAAS,OAAO;AACd,UAAI,iBAAiB,gBAAgB;AACnC,eAAO,aAAa,EAAE,OAAO,MAAM,QAAA,GAAW,MAAM,MAAM;AAAA,MAC5D;AACA,YAAM;AAAA,IACR;AAAA,EACF;AACF;AAEA,SAAS,aAAa,MAAe,SAAS,KAAe;AAC3D,SAAO,IAAI,SAAS,KAAK,UAAU,IAAI,GAAG;AAAA,IACxC;AAAA,IACA,SAAS,EAAE,gBAAgB,mBAAA;AAAA,EAAmB,CAC/C;AACH;"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@happyvertical/smrt-app-mcp",
+  "version": "0.30.0",
+  "description": "App-runtime MCP server scaffolding for SMRT apps — `createMcpAppServer` plus transport adapters (SvelteKit today) for exposing a SMRT app's MCP surface over HTTP.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sveltekit": {
+      "types": "./dist/sveltekit.d.ts",
+      "import": "./dist/sveltekit.js"
+    }
+  },
+  "files": [
+    "CLAUDE.md",
+    "README.md",
+    "dist",
+    "AGENTS.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/smrt-app-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/happyvertical/smrt/issues"
+  },
+  "homepage": "https://github.com/happyvertical/smrt/tree/main/packages/smrt-app-mcp#readme",
+  "license": "MIT",
+  "keywords": [
+    "smrt",
+    "mcp",
+    "model-context-protocol",
+    "sveltekit"
+  ],
+  "author": "HappyVertical",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@happyvertical/smrt-core": "0.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.9",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "vite build --mode library",
+    "build:watch": "vite build --mode library --watch",
+    "clean": "rm -rf dist",
+    "dev": "npm run build:watch",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "verify:pack": "node ../../scripts/verify-package-types-exports.js ."
+  }
+}