@happyvertical/smrt-core 0.30.0

package/dist/generators/mcp.d.ts

@@ -0,0 +1,231 @@
+/**
+ * MCP (Model Context Protocol) server generator for smrt objects
+ *
+ * Exposes smrt objects as AI tools for Claude, GPT, and other AI models
+ */
+export interface MCPConfig {
+    name?: string;
+    version?: string;
+    description?: string;
+    server?: {
+        name: string;
+        version: string;
+    };
+}
+export interface MCPContext {
+    db?: any;
+    ai?: any;
+    user?: {
+        id: string;
+        roles?: string[];
+    };
+    /**
+     * Tenant the calling principal is scoped to (#1554). When set, tenant-scoped
+     * tools run inside this tenant's context. Hosts that authenticate a principal
+     * (e.g. `@happyvertical/smrt-app-mcp`) should derive it from the principal —
+     * the MCP analogue of the SvelteKit auth hook setting `locals.tenantId`.
+     */
+    tenantId?: string;
+    /**
+     * Explicit operator opt-in to cross-tenant access for tenant-scoped tools
+     * (#1554). Only set for trusted operator/admin callers. Without a `tenantId`
+     * or this flag, tenant-scoped tool calls fail closed when tenancy is enabled.
+     */
+    allowCrossTenant?: boolean;
+}
+export interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+export interface MCPRequest {
+    method: string;
+    params: {
+        name: string;
+        arguments: Record<string, any>;
+    };
+}
+export interface MCPResponse {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}
+/**
+ * Generate MCP server from smrt objects
+ */
+export declare class MCPGenerator {
+    private config;
+    private context;
+    private collections;
+    constructor(config?: MCPConfig, context?: MCPContext);
+    /**
+     * Get server name
+     */
+    get name(): string | undefined;
+    /**
+     * Get server version
+     */
+    get version(): string | undefined;
+    /**
+     * Generate all available tools from registered objects
+     */
+    generateTools(): Promise<MCPTool[]>;
+    /**
+     * Generate tools for a specific object
+     */
+    private generateObjectTools;
+    /**
+     * Validate that a custom method exists on a class
+     */
+    private validateCustomMethod;
+    /**
+     * Convert field definition to MCP schema
+     */
+    private fieldToMCPSchema;
+    /**
+     * Handle MCP tool calls
+     */
+    handleToolCall(request: MCPRequest): Promise<MCPResponse>;
+    /**
+     * Get or create collection for an object
+     */
+    private getCollection;
+    /**
+     * Serialize a tool-response payload, excluding sensitive fields (#1540).
+     * Recurses through arrays and plain objects so a SmrtObject nested inside a
+     * custom-action result (e.g. `{ item }`) is also stripped — `JSON.stringify`
+     * would otherwise call its `toJSON()`. Non-plain instances (Date, etc.) and
+     * primitives pass through unchanged; a cycle guard prevents infinite loops.
+     */
+    private toPublicData;
+    /**
+     * Mass-assignment guard (#1540): strip framework/server-managed and
+     * `@field({ readonly: true })` fields from a create/update body, and — when an
+     * `@smrt({ api: { writable: [...] } })` allowlist is set — intersect with it.
+     */
+    private applyWritablePolicy;
+    /**
+     * Execute action on collection
+     */
+    /**
+     * Fail-closed authorization for tool calls (#1540). Mutating tools
+     * (create/update/delete + custom actions) require an authenticated principal
+     * (`context.user`) unless the object opts out via `@smrt({ api: { public } })`.
+     * Reads are allowed when `public` is `true` or `'read'`.
+     */
+    private requireToolAuth;
+    private executeAction;
+    /**
+     * Derive the set of tenant-scoped object names (lowercased simple names) from
+     * a generated tool list, for the emitted runtime template's tenant gate
+     * (#1554). Tool names are `objectname_action`.
+     *
+     * Detection uses ONLY tenancy's `isTenantScopedClass` (the authoritative
+     * source the interceptor uses; covers `@TenantScoped`), consulted via an
+     * optional dynamic import. We deliberately do NOT fall back to core's
+     * `ObjectRegistry.isTenantScoped`: a `@smrt({ tenantScoped })` model can exist
+     * in an app that has NOT installed `@happyvertical/smrt-tenancy`, and emitting
+     * the static `import { runTenantScopedEntryPoint } from '@happyvertical/smrt-tenancy'`
+     * gate for it would crash the generated server at import time. When tenancy is
+     * absent there is also nothing to enforce, so emitting no gate is correct.
+     */
+    private tenantScopedObjectNames;
+    /**
+     * Execute a resolved MCP action (CRUD or custom) against a collection. Always
+     * invoked inside the tenant gate established by {@link executeAction}.
+     */
+    private runAction;
+    /**
+     * Execute a custom action on a collection/object
+     */
+    private executeCustomAction;
+    /**
+     * Generate MCP server info
+     */
+    getServerInfo(): {
+        name: string | undefined;
+        version: string | undefined;
+        description: string | undefined;
+    };
+    /**
+     * Generate complete MCP server with stdio transport
+     *
+     * Creates a runnable Node.js script that exposes SMRT objects as MCP tools.
+     * The generated server includes:
+     * - Stdio transport integration
+     * - Tool registration from ObjectRegistry
+     * - Error handling and logging
+     * - Graceful shutdown
+     *
+     * @param options - Server generation options
+     * @returns Promise that resolves when all files are written
+     *
+     * @example
+     * ```typescript
+     * const generator = new MCPGenerator({
+     *   name: 'my-app',
+     *   version: '1.0.0'
+     * });
+     *
+     * await generator.generateServer({
+     *   outputPath: '.smrt/mcp-server/index.js',
+     *   serverName: 'my-app-mcp',
+     *   debug: true
+     * });
+     * ```
+     */
+    generateServer(options?: {
+        /** Path to output server file (relative or absolute) */
+        outputPath?: string;
+        /** Server name for configuration */
+        serverName?: string;
+        /** Server version */
+        serverVersion?: string;
+        /** Enable debug logging */
+        debug?: boolean;
+        /** Generate Claude Desktop configuration example */
+        generateClaudeConfigFile?: boolean;
+        /** Generate README documentation */
+        generateReadme?: boolean;
+        /** Generate modular directory structure (tools/, handlers/, config.ts) */
+        modular?: boolean;
+    }): Promise<void>;
+    /**
+     * Generate modular MCP server structure
+     *
+     * Creates separate files for tools, handlers, configuration, and main entry point.
+     * This makes the generated server easier to customize and extend.
+     *
+     * @param outputDir - Directory to generate files in
+     * @param serverName - Server name
+     * @param serverVersion - Server version
+     * @param debug - Enable debug logging
+     */
+    private generateModularServer;
+    /**
+     * Generate configuration file for modular server
+     */
+    private generateConfigFile;
+    /**
+     * Generate tools definitions file for modular server
+     */
+    private generateToolsFile;
+    /**
+     * Generate switch cases for tool execution
+     */
+    private generateToolSwitchCases;
+    /**
+     * Generate handlers file for modular server
+     */
+    private generateHandlersFile;
+    /**
+     * Generate modular index file (main entry point)
+     */
+    private generateModularIndex;
+}
+//# sourceMappingURL=mcp.d.ts.map

package/dist/generators/mcp.d.ts.map

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