@frigear-nu/mcp 0.0.0-stage → 0.0.2

package/dist/module.d.mts

@@ -0,0 +1,17 @@
+import * as _nuxt_schema from '@nuxt/schema';
+export { addMcpDefinitions } from '../dist/runtime/utils/build.js';
+
+interface ModuleOptions {
+    /** Route of the MCP endpoint. */
+    route?: string;
+}
+
+declare module 'nuxt/schema' {
+    interface NuxtConfig {
+        mcpModules?: ModuleOptions;
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/mcp",
+  "configKey": "mcpModules",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,34 @@
+import { defineNuxtModule, createResolver, addServerImportsDir, addServerPlugin } from '@nuxt/kit';
+export { addMcpDefinitions } from '../dist/runtime/utils/build.js';
+
+const DEFAULT_INSTRUCTIONS = [
+  "You act as the signed-in user, limited to the scopes of the API token in use. You only see the tools that token and the user are allowed to use.",
+  'Personal data of other people (names, emails, form answers) is withheld unless the token carries the matching "*:pii" scope. Responses say when something was withheld; report that to the user instead of looking for another way to get it.',
+  "Some settings are deliberately not available here, for example where form submissions are delivered, because changing them could be used to exfiltrate data. When a tool refuses for that reason, tell the user to make the change in the admin UI."
+].join("\n");
+const module$1 = defineNuxtModule({
+  // Not `mcp`: that key belongs to @nuxtjs/mcp-toolkit.
+  meta: { name: "@frigear-nu/mcp", configKey: "mcpModules" },
+  defaults: {},
+  moduleDependencies: {
+    "@frigear-nu/auth": { version: ">=0.0.1" },
+    "@nuxtjs/mcp-toolkit": {
+      version: ">=0.24.0",
+      defaults: {}
+    }
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.nitro.experimental = { ...nuxt.options.nitro.experimental, asyncContext: true };
+    const host = nuxt.options;
+    host.mcp = {
+      ...host.mcp,
+      ...options.route ? { route: options.route } : {},
+      instructions: host.mcp?.instructions ?? DEFAULT_INSTRUCTIONS
+    };
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    addServerPlugin(resolver.resolve("./runtime/server/plugins/mcp"));
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/server/plugins/mcp.d.ts

@@ -0,0 +1,23 @@
+import type { H3Event } from 'h3';
+import type { CallToolResult, McpResolvedConfig } from '@nuxtjs/mcp-toolkit/server';
+declare module 'nitropack' {
+    interface NitroRuntimeHooks {
+        'mcp:config:resolved': (ctx: {
+            config: McpResolvedConfig;
+            event: H3Event;
+        }) => void | Promise<void>;
+        'mcp:tool:called': (ctx: {
+            name: string;
+            result: CallToolResult;
+            durationMs: number;
+            event: H3Event;
+        }) => void | Promise<void>;
+    }
+}
+/**
+ * Defence in depth around the scoped definers:
+ * - fail closed: a definition that was not created through `defineScopedMcp*` (no marker) is dropped;
+ * - audit: who called which tool, never the arguments or the result.
+ */
+declare const _default: import("nitropack").NitroAppPlugin;
+export default _default;

package/dist/runtime/server/plugins/mcp.js

@@ -0,0 +1,31 @@
+import { defineNitroPlugin } from "nitropack/runtime";
+import { z } from "zod";
+import { SCOPED_META_KEY } from "../../utils/access.js";
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook("mcp:config:resolved", ({ config }) => {
+    const scoped = (definition) => definition._meta?.[SCOPED_META_KEY] === true;
+    const serializable = (tool) => {
+      if (!tool.inputSchema) return true;
+      try {
+        z.toJSONSchema(z.object(tool.inputSchema), { io: "input" });
+        return true;
+      } catch (error) {
+        console.error(`[mcp] dropping tool "${tool.name}": its input schema is not JSON Schema compatible`, error);
+        return false;
+      }
+    };
+    config.tools = config.tools.filter(scoped).filter(serializable);
+    config.resources = config.resources.filter(scoped);
+    config.prompts = config.prompts.filter(scoped);
+  });
+  nitroApp.hooks.hook("mcp:tool:called", ({ name, result, durationMs, event }) => {
+    const principal = event.context.auth;
+    console.info("[mcp] tool called", JSON.stringify({
+      tool: name,
+      userId: principal?.user.id ?? null,
+      credential: principal?.kind ?? null,
+      outcome: result.isError ? "error" : "success",
+      durationMs
+    }));
+  });
+});

package/dist/runtime/server/utils/define.d.ts

@@ -0,0 +1,46 @@
+import type { H3Event } from 'h3';
+import type { ZodRawShape, z } from 'zod';
+import type { McpPromptCallbackResult, McpPromptDefinition, McpRequestExtra, McpToolCallbackResult, McpToolDefinition, StandardMcpResourceDefinition } from '@nuxtjs/mcp-toolkit/server';
+import type { AuthPrincipal, AuthUser } from '@frigear-nu/auth/utils';
+import type { ScopedAccess } from '../../utils/access.js';
+type ShapeOutput<Shape extends ZodRawShape> = z.output<z.ZodObject<Shape>>;
+export interface ScopedMcpContext {
+    event: H3Event;
+    principal: AuthPrincipal;
+    /** The authenticated user. "My …" tools must use this and never take a user id as an argument. */
+    user: AuthUser;
+    /** Whether the credential carries `scope` (e.g. an opt-in `*:pii` scope). */
+    hasScope: (scope: string) => boolean;
+}
+/**
+ * Extra, module-specific check layered on the scopes, typically the module's `*:authorize` policy
+ * hook. It runs on every listing and every call, so a caller the host does not allow never sees
+ * the definition. Identify the caller from `principal.user.id`, never from the session on `event`.
+ */
+export type ScopedGate = (event: H3Event, principal: AuthPrincipal) => boolean | Promise<boolean>;
+export interface ScopedOptions extends ScopedAccess {
+    gate?: ScopedGate;
+}
+/**
+ * Authorises the in-flight request. Listing-time hiding is not authorisation (sessions freeze the
+ * list), so every handler re-checks. Failures are 401/403 errors the toolkit turns into `isError`.
+ */
+export declare function authorizeMcp(options: ScopedOptions): Promise<ScopedMcpContext>;
+export type ScopedMcpToolDefinition<Shape extends ZodRawShape = ZodRawShape> = Omit<McpToolDefinition<Shape>, 'handler' | 'enabled' | 'inputSchema'> & ScopedOptions & {
+    tags?: string[];
+    inputSchema?: Shape;
+    handler: (args: ShapeOutput<Shape>, ctx: ScopedMcpContext, extra: McpRequestExtra) => McpToolCallbackResult | Promise<McpToolCallbackResult>;
+};
+/** An MCP tool that is listed and callable only within the scopes (and gate) the caller satisfies. */
+export declare function defineScopedMcpTool<const Shape extends ZodRawShape = Record<string, never>>(definition: ScopedMcpToolDefinition<Shape>): McpToolDefinition<Shape, Readonly<{
+    [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}>>;
+export type ScopedMcpResourceDefinition = Omit<StandardMcpResourceDefinition, 'handler' | 'enabled'> & ScopedOptions & {
+    handler: (ctx: ScopedMcpContext, ...args: Parameters<StandardMcpResourceDefinition['handler']>) => ReturnType<StandardMcpResourceDefinition['handler']>;
+};
+export declare function defineScopedMcpResource(definition: ScopedMcpResourceDefinition): import("@nuxtjs/mcp-toolkit/server").McpResourceDefinition;
+export type ScopedMcpPromptDefinition<Shape extends ZodRawShape | undefined = undefined> = Omit<McpPromptDefinition<Shape>, 'handler' | 'enabled'> & ScopedOptions & {
+    handler: (args: Shape extends ZodRawShape ? ShapeOutput<Shape> : Record<string, never>, ctx: ScopedMcpContext) => McpPromptCallbackResult | Promise<McpPromptCallbackResult>;
+};
+export declare function defineScopedMcpPrompt<const Shape extends ZodRawShape | undefined = undefined>(definition: ScopedMcpPromptDefinition<Shape>): McpPromptDefinition<Shape>;
+export { pick, piiNotice, redactPii } from '../../utils/access.js';

package/dist/runtime/server/utils/define.js

@@ -0,0 +1,90 @@
+import { defineMcpPrompt, defineMcpResource, defineMcpTool } from "@nuxtjs/mcp-toolkit/server";
+import { hasScopes } from "@frigear-nu/auth/utils";
+import { SCOPED_META_KEY, isPrincipalAllowed, scopeTags } from "../../utils/access.js";
+async function isAllowed(event, options) {
+  const principal = await getAuth(event);
+  if (!isPrincipalAllowed(principal, options)) return null;
+  if (!options.gate) return principal;
+  try {
+    return await options.gate(event, principal) ? principal : null;
+  } catch (error) {
+    console.error("[mcp] gate failed, hiding definition", error);
+    return null;
+  }
+}
+function toContext(event, principal) {
+  return {
+    event,
+    principal,
+    user: principal.user,
+    hasScope: (scope) => hasScopes(principal.scopes, [scope])
+  };
+}
+export async function authorizeMcp(options) {
+  const event = useEvent();
+  const principal = await getAuth(event);
+  if (!principal) throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  if (options.sessionOnly && principal.kind !== "session") {
+    throw createError({ statusCode: 403, statusMessage: "Forbidden", data: { error: "session_required" } });
+  }
+  if (!hasScopes(principal.scopes, options.scopes)) {
+    throw createError({ statusCode: 403, statusMessage: "Forbidden", data: { error: "insufficient_scope", scopes: options.scopes } });
+  }
+  if (options.gate && !await options.gate(event, principal)) {
+    throw createError({ statusCode: 403, statusMessage: "Forbidden" });
+  }
+  return toContext(event, principal);
+}
+function assertScoped(kind, options) {
+  if (!options.scopes?.length) {
+    throw new Error(`[mcp] A ${kind} must declare at least one scope; unscoped definitions are never exposed.`);
+  }
+}
+function guarded(options, meta) {
+  return {
+    tags: scopeTags(options),
+    _meta: { ...meta, [SCOPED_META_KEY]: true, "frigear-nu/scopes": options.scopes },
+    enabled: async (event) => await isAllowed(event, options) !== null
+  };
+}
+export function defineScopedMcpTool(definition) {
+  assertScoped("tool", definition);
+  const { scopes: _scopes, sessionOnly: _sessionOnly, gate: _gate, handler, tags, _meta, inputSchema, ...rest } = definition;
+  const base = guarded(definition, _meta);
+  return defineMcpTool({
+    ...rest,
+    inputSchema: inputSchema ?? {},
+    tags: [...base.tags, ...tags ?? []],
+    _meta: base._meta,
+    enabled: base.enabled,
+    handler: (async (args, extra) => handler(args, await authorizeMcp(definition), extra))
+  });
+}
+export function defineScopedMcpResource(definition) {
+  assertScoped("resource", definition);
+  const { scopes: _scopes, sessionOnly: _sessionOnly, gate: _gate, handler, tags, _meta, ...rest } = definition;
+  const base = guarded(definition, _meta);
+  return defineMcpResource({
+    ...rest,
+    tags: [...base.tags, ...tags ?? []],
+    _meta: base._meta,
+    enabled: base.enabled,
+    handler: (async (...args) => handler(await authorizeMcp(definition), ...args))
+  });
+}
+export function defineScopedMcpPrompt(definition) {
+  assertScoped("prompt", definition);
+  const { scopes: _scopes, sessionOnly: _sessionOnly, gate: _gate, handler, tags, _meta, ...rest } = definition;
+  const base = guarded(definition, _meta);
+  return defineMcpPrompt({
+    ...rest,
+    tags: [...base.tags, ...tags ?? []],
+    _meta: base._meta,
+    enabled: base.enabled,
+    handler: (async (...args) => {
+      const ctx = await authorizeMcp(definition);
+      return handler(definition.inputSchema ? args[0] : {}, ctx);
+    })
+  });
+}
+export { pick, piiNotice, redactPii } from "../../utils/access.js";

package/dist/runtime/utils/access.d.ts

@@ -0,0 +1,33 @@
+import type { AuthPrincipal } from '@frigear-nu/auth/utils';
+/** Marker set on every definition created through the scoped definers; anything without it is dropped. */
+export declare const SCOPED_META_KEY = "frigear-nu/scoped";
+export interface ScopedAccess {
+    /** Scopes the caller's credential must carry. Required: a definition without scopes is never exposed. */
+    scopes: string[];
+    /** Never exposed to bearer credentials (API tokens, OAuth); only to a cookie session. */
+    sessionOnly?: boolean;
+}
+/**
+ * Pure part of the access decision: is there a principal, does it carry the scopes, is the
+ * credential kind allowed. Module-specific gates (e.g. `events:authorize`) layer on top.
+ */
+export declare function isPrincipalAllowed(principal: AuthPrincipal | null | undefined, access: ScopedAccess): principal is AuthPrincipal;
+export declare function scopeTags(access: ScopedAccess): string[];
+export interface RedactOptions<T extends object> {
+    /** Whether the caller may see identifying fields. */
+    allow: boolean;
+    /** Fields that identify a person or hold their answers. */
+    fields: ReadonlyArray<keyof T>;
+}
+/**
+ * Removes identifying fields unless explicitly allowed. Use together with an explicit allow-list of
+ * output fields: never pass a raw database row through.
+ */
+export declare function redactPii<T extends object>(row: T, options: RedactOptions<T>): Partial<T>;
+/** Picks an explicit allow-list of keys, so a new database column is never exposed by accident. */
+export declare function pick<T extends object, K extends keyof T>(row: T, keys: readonly K[]): Pick<T, K>;
+/**
+ * Message for the agent when identifying fields were withheld, so it can tell the user why instead
+ * of guessing or retrying. Undefined when nothing was withheld.
+ */
+export declare function piiNotice(allowed: boolean, scope: string, fields: string): string | undefined;

package/dist/runtime/utils/access.js

@@ -0,0 +1,25 @@
+import { hasScopes } from "@frigear-nu/auth/utils";
+export const SCOPED_META_KEY = "frigear-nu/scoped";
+export function isPrincipalAllowed(principal, access) {
+  if (!principal) return false;
+  if (!access.scopes.length) return false;
+  if (access.sessionOnly && principal.kind !== "session") return false;
+  return hasScopes(principal.scopes, access.scopes);
+}
+export function scopeTags(access) {
+  return [...access.scopes.map((scope) => `scope:${scope}`), ...access.sessionOnly ? ["session-only"] : []];
+}
+export function redactPii(row, options) {
+  if (options.allow) return { ...row };
+  const hidden = new Set(options.fields);
+  return Object.fromEntries(Object.entries(row).filter(([key]) => !hidden.has(key)));
+}
+export function pick(row, keys) {
+  const result = {};
+  for (const key of keys) result[key] = row[key];
+  return result;
+}
+export function piiNotice(allowed, scope, fields) {
+  if (allowed) return void 0;
+  return `${fields} are withheld because this credential lacks the "${scope}" scope. This is intentional privacy protection; do not look for another way to obtain them. If the user needs them, ask them to create an API token that also has the "${scope}" scope.`;
+}

package/dist/runtime/utils/build.d.ts

@@ -0,0 +1,23 @@
+import type { Nuxt } from '@nuxt/schema';
+export type McpDefinitionKind = 'tools' | 'resources' | 'prompts';
+interface McpDefinitionPaths {
+    tools: string[];
+    resources: string[];
+    prompts: string[];
+    handlers: string[];
+}
+declare module '@nuxt/schema' {
+    interface NuxtHooks {
+        'mcp:definitions:paths': (paths: McpDefinitionPaths) => void | Promise<void>;
+    }
+}
+/**
+ * Register a module's MCP definitions. `dir` is an absolute directory laid out like a project's
+ * `server/mcp`: `tools/`, `resources/` and `prompts/` subfolders (each optional). Subfolders of
+ * `tools/` become tool groups, so `tools/admin/…` is grouped as `admin`.
+ *
+ * Every definition must be created with `defineScopedMcpTool` / `defineScopedMcpResource` /
+ * `defineScopedMcpPrompt` so it carries the scopes it requires; anything else is dropped at runtime.
+ */
+export declare function addMcpDefinitions(nuxt: Nuxt, dir: string): void;
+export {};

package/dist/runtime/utils/build.js

@@ -0,0 +1,10 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export function addMcpDefinitions(nuxt, dir) {
+  nuxt.hook("mcp:definitions:paths", (paths) => {
+    for (const kind of ["tools", "resources", "prompts"]) {
+      const path = join(dir, kind);
+      if (existsSync(path) && !paths[kind].includes(path)) paths[kind].push(path);
+    }
+  });
+}

package/dist/runtime/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { addMcpDefinitions } from './build.js';
+export type { McpDefinitionKind } from './build.js';
+export { SCOPED_META_KEY, isPrincipalAllowed, pick, piiNotice, redactPii, scopeTags } from './access.js';
+export type { RedactOptions, ScopedAccess } from './access.js';

package/dist/runtime/utils/index.js

@@ -0,0 +1,2 @@
+export { addMcpDefinitions } from "./build.js";
+export { SCOPED_META_KEY, isPrincipalAllowed, pick, piiNotice, redactPii, scopeTags } from "./access.js";

package/dist/types.d.mts

@@ -0,0 +1,5 @@
+export { type addMcpDefinitions } from '../dist/runtime/utils/build.js'
+
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@frigear-nu/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "Scoped, PII-safe MCP tools for the frigear ecosystem: modules contribute tools, resources and prompts that are only listed and callable within the scopes the caller holds.",
+  "homepage": "https://docs.frigear.dev/modules/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frigear-nu/frigear-nu.git",
+    "directory": "packages/mcp"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs",
+      "default": "./dist/module.mjs"
+    },
+    "./utils": {
+      "types": "./dist/runtime/utils/index.d.ts",
+      "import": "./dist/runtime/utils/index.js",
+      "default": "./dist/runtime/utils/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "playground"
+  ],
+  "dependencies": {
+    "@frigear-nu/auth": "0.0.2",
+    "@frigear-nu/module-kit": "0.1.6",
+    "@nuxt/kit": "^4.6.0",
+    "@nuxtjs/mcp-toolkit": "^0.24.1",
+    "agents": "^0.28.0",
+    "h3": "^1.15.11",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@libsql/client": "^0.18.0",
+    "@nuxt/devtools": "^3.4.2",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.6.0",
+    "@nuxt/test-utils": "^4.3.2",
+    "@nuxthub/core": "^0.10.8",
+    "@types/node": "latest",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.3",
+    "eslint": "^10.10.0",
+    "nuxt": "^4.6.1",
+    "nuxt-auth-utils": "^0.5.30",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1",
+    "vue-tsc": "^3.3.11"
+  },
+  "scripts": {
+    "postinstall": "nuxt-module-build build --stub && nuxt prepare",
+    "build": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.