@modyo/mcp 0.1.0

package/build/shared/ResourceBase.js

@@ -0,0 +1,235 @@
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { getRepositoryOrThrow } from "./helpers/getRepositoryOrThrow.js";
+/**
+ * Abstract base class for MCP resources
+ *
+ * Provides a structured, class-based approach to creating resources with:
+ * - Type-safe parameter validation via Zod schemas
+ * - Consistent error handling patterns
+ * - Logging integration
+ * - Repository access helpers
+ * - Support for both dynamic (API-based) and static (file-based) resources
+ *
+ * @example Dynamic Resource (API Data)
+ * ```typescript
+ * class ListSpacesResource extends ResourceBase<{ spaceId: number }> {
+ *   protected config: ResourceConfig = {
+ *     name: "modyo-spaces-list",
+ *     uriTemplate: "modyo-spaces://{spaceId}",
+ *     description: "Fetches spaces from Modyo platform",
+ *     mimeType: "application/json",
+ *     annotations: { readOnlyHint: true }
+ *   };
+ *
+ *   protected getParamsSchema() {
+ *     return z.object({ spaceId: z.number() });
+ *   }
+ *
+ *   async read(uri: URL, params: { spaceId: number }): Promise<ReadResourceResult> {
+ *     const repo = await this.getRepository(SpacesRepository);
+ *     const response = await repo.getSpace(params.spaceId);
+ *     return this.success(uri, response);
+ *   }
+ * }
+ * ```
+ *
+ * @example Static Resource (File Content)
+ * ```typescript
+ * class DocResource extends ResourceBase<void> {
+ *   protected config: ResourceConfig = {
+ *     name: "docs-site-create",
+ *     uriTemplate: "docs://tools/site-create",  // No parameters
+ *     description: "Documentation for site-create tool",
+ *     mimeType: "text/markdown",
+ *     annotations: { readOnlyHint: true }
+ *   };
+ *
+ *   protected getParamsSchema() {
+ *     return z.void();  // No parameters
+ *   }
+ *
+ *   async read(uri: URL): Promise<ReadResourceResult> {
+ *     const content = readFileSync("docs/site-create.md", "utf-8");
+ *     return this.successText(uri, content, "text/markdown");
+ *   }
+ * }
+ * ```
+ */
+export class ResourceBase {
+    server;
+    logger;
+    /**
+     * Initializes the resource with MCP server context
+     * Called automatically during registration
+     */
+    initialize(server, logger) {
+        this.server = server;
+        this.logger = logger;
+    }
+    /**
+     * Registers this resource with the MCP server
+     * Called by McpServerBase during setup
+     * Can be overridden by subclasses to support async initialization (e.g., filesystem discovery)
+     */
+    registerResource(server, logger) {
+        this.initialize(server, logger);
+        const schema = this.getParamsSchema();
+        const rawInputSchema = this.extractRawSchema(schema);
+        // Determine if this is a template resource (has parameters) or static resource
+        const hasParams = Object.keys(rawInputSchema).length > 0;
+        const resourceConfig = {
+            description: this.config.description,
+            ...(this.config.mimeType
+                ? {
+                    mimeType: this.config.mimeType,
+                }
+                : {}),
+            ...(hasParams
+                ? {
+                    inputSchema: rawInputSchema,
+                }
+                : {}),
+            ...(this.config.annotations
+                ? {
+                    annotations: this.config.annotations,
+                }
+                : {}),
+        };
+        const readCallback = async (uri, params) => {
+            try {
+                const validatedParams = hasParams
+                    ? schema.parse(params)
+                    : undefined;
+                return await this.read(uri, validatedParams);
+            }
+            catch (error) {
+                // If catchErrors is enabled, return error as resource content
+                if (this.config.catchErrors) {
+                    return this.errorResponse(uri, error, {
+                        params,
+                    });
+                }
+                // Otherwise, log and re-throw (default behavior)
+                this.logger(`Resource ${this.config.name} failed`, {
+                    uri: uri.href,
+                    params,
+                    error,
+                }, "error");
+                throw error;
+            }
+        };
+        // Register with appropriate overload based on whether we have parameters
+        if (hasParams) {
+            server.registerResource(this.config.name, new ResourceTemplate(this.config.uriTemplate, {
+                list: undefined,
+            }), resourceConfig, readCallback);
+        }
+        else {
+            server.registerResource(this.config.name, this.config.uriTemplate, resourceConfig, readCallback);
+        }
+    }
+    /**
+     * Returns whether this resource requires authentication
+     */
+    get isPublic() {
+        return this.config.isPublic ?? false;
+    }
+    /**
+     * Helper: Gets a repository instance using the configured platform
+     * Uses SinglePlatformProvider to get platform config from environment variables
+     *
+     * @param RepositoryClass - Repository constructor
+     * @returns Repository instance
+     * @throws Error if platform not configured
+     */
+    async getRepository(RepositoryClass) {
+        return getRepositoryOrThrow(RepositoryClass, this.logger);
+    }
+    /**
+     * Helper: Formats successful JSON response
+     * Use for API-based resources that return JSON data
+     */
+    success(uri, data) {
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: this.config.mimeType ?? "application/json",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    }
+    /**
+     * Helper: Formats successful text response
+     * Use for file-based resources like markdown docs
+     */
+    successText(uri, text, mimeType) {
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: mimeType ?? this.config.mimeType ?? "text/plain",
+                    text,
+                },
+            ],
+        };
+    }
+    /**
+     * Helper: Formats error response as resource content
+     * Returns a properly formatted error response without throwing
+     */
+    errorResponse(uri, error, context) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorDetails = {
+            error: errorMessage,
+            ...(error instanceof Error && error.stack
+                ? {
+                    stack: error.stack,
+                }
+                : {}),
+            ...context,
+        };
+        this.logger("Resource read failed", errorDetails, "error");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(errorDetails, null, 2),
+                },
+            ],
+        };
+    }
+    /**
+     * Helper: Logs debug information
+     */
+    debug(message, data) {
+        this.logger(message, data, "debug");
+    }
+    /**
+     * Helper: Logs info
+     */
+    info(message, data) {
+        this.logger(message, data, "info");
+    }
+    /**
+     * Helper: Logs error
+     */
+    logError(message, data) {
+        this.logger(message, data, "error");
+    }
+    /**
+     * Extracts raw schema shape for MCP registration
+     * Handles Zod object schemas
+     */
+    extractRawSchema(schema) {
+        // For ZodObject, extract the shape
+        if ("shape" in schema && typeof schema.shape === "object") {
+            return schema.shape;
+        }
+        // For ZodVoid or other schemas without shape, return empty object
+        return {};
+    }
+}
+//# sourceMappingURL=ResourceBase.js.map

package/build/shared/ResourceBase.js.map

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

package/build/shared/ToolBase.d.ts

@@ -0,0 +1,174 @@
+import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { z } from "zod";
+import type { DeprecationMetadata } from "./helpers/deprecation.js";
+import type { Logger } from "./types/Logger.js";
+/**
+ * Tool configuration metadata
+ */
+export interface ToolConfig {
+    /** Unique tool identifier (e.g., "modyo-mcp-space-create") */
+    name: string;
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** MCP annotations for the tool */
+    annotations?: ToolAnnotations;
+    /** Whether this tool is available without authentication */
+    isPublic?: boolean;
+    /** If false, re-throws errors instead of returning structured CallToolResult with isError: true (default: true) */
+    catchErrors?: boolean;
+    /** If true, this tool is deprecated and should be filtered out unless MODYO_SHOW_DEPRECATED=true */
+    isDeprecated?: boolean;
+    /** Deprecation metadata (required if isDeprecated is true) */
+    deprecationMetadata?: DeprecationMetadata;
+}
+/**
+ * Abstract base class for MCP tools
+ *
+ * Provides a structured, class-based approach to creating tools with:
+ * - Type-safe parameter validation via Zod schemas
+ * - Consistent error handling patterns
+ * - Logging integration
+ * - Repository access helpers
+ *
+ * @example
+ * ```typescript
+ * class CreateSpaceTool extends ToolBase<CreateSpaceParams> {
+ *   protected config: ToolConfig = {
+ *     name: "space-create",
+ *     description: "Creates a new space",
+ *     annotations: { destructiveHint: true }
+ *   };
+ *
+ *   protected getParamsSchema() {
+ *     return z.object({
+ *       name: z.string().min(2).max(100),
+ *     });
+ *   }
+ *
+ *   async execute(params: CreateSpaceParams): Promise<CallToolResult> {
+ *     const repo = await this.getRepository(SpacesRepository);
+ *     const response = await repo.createSpace(params);
+ *     return this.success(response);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class ToolBase<TParams = unknown> {
+    protected server: any;
+    protected serverName: string;
+    protected logger: Logger;
+    /**
+     * Tool configuration - must be defined by subclasses
+     */
+    protected abstract config: ToolConfig;
+    /**
+     * Returns the Zod schema for validating tool parameters
+     * Override to provide custom validation
+     */
+    protected abstract getParamsSchema(): z.ZodType<TParams>;
+    /**
+     * Executes the tool logic
+     * @param params - Validated parameters
+     * @returns MCP CallToolResult
+     */
+    protected abstract execute(params: TParams): Promise<CallToolResult>;
+    /**
+     * Initializes the tool with MCP server context
+     * Called automatically during registration
+     */
+    private initialize;
+    /**
+     * Registers this tool with the MCP server
+     * Called by McpServerBase during setup
+     */
+    registerTool(server: any, serverName: string, logger: Logger): void;
+    /**
+     * Returns whether this tool requires authentication
+     */
+    get isPublic(): boolean;
+    /**
+     * Returns whether this tool is deprecated
+     */
+    get isDeprecated(): boolean;
+    /**
+     * Returns the deprecation metadata for this tool (if deprecated)
+     */
+    get deprecationMetadata(): DeprecationMetadata | undefined;
+    /**
+     * Helper: Gets a repository instance using the configured platform
+     * Uses SinglePlatformProvider to get platform config from environment variables
+     *
+     * @param RepositoryClass - Repository constructor
+     * @returns Repository instance
+     * @throws Error if platform not configured
+     */
+    protected getRepository<T>(RepositoryClass: new (url: string, token: string, logger: Logger) => T): Promise<T>;
+    /**
+     * Helper: Formats successful response as MCP result
+     */
+    protected success(data: unknown, message?: string): CallToolResult;
+    /**
+     * Helper: Formats error response as MCP result
+     * Returns a properly formatted error response without throwing
+     */
+    protected errorResponse(error: unknown, context?: Record<string, unknown>): CallToolResult;
+    /**
+     * Helper: Logs debug information
+     */
+    protected debug(message: string, data?: unknown): void;
+    /**
+     * Helper: Logs info
+     */
+    protected info(message: string, data?: unknown): void;
+    /**
+     * Helper: Logs error
+     */
+    protected logError(message: string, data?: unknown): void;
+    /**
+     * Helper: Request user confirmation via MCP elicitation
+     *
+     * Use this for sensitive operations like password changes, email updates, etc.
+     * Returns the user's response or null if client doesn't support elicitation.
+     *
+     * @param message - Message to display to the user
+     * @param fields - Optional form fields to collect (for form-based elicitation)
+     * @returns User response with action ('accept'|'decline'|'cancel') and optional content
+     *
+     * @example
+     * ```typescript
+     * // Simple confirmation
+     * const result = await this.elicit("Are you sure you want to change the password?");
+     * if (result?.action !== 'accept') {
+     *   return this.errorResponse(new Error("Password change cancelled by user"));
+     * }
+     *
+     * // With form fields
+     * const result = await this.elicit("Confirm email change", {
+     *   confirm: { type: 'boolean', description: 'I confirm this change' }
+     * });
+     * ```
+     */
+    protected elicit(message: string, fields?: Record<string, {
+        type: "boolean";
+        description?: string;
+    } | {
+        type: "string";
+        description?: string;
+    } | {
+        type: "number";
+        description?: string;
+    } | {
+        type: "string";
+        enum: string[];
+        description?: string;
+    }>): Promise<{
+        action: "accept" | "decline" | "cancel";
+        content?: Record<string, unknown>;
+    } | null>;
+    /**
+     * Extracts raw schema shape for MCP registration
+     * Handles Zod object schemas
+     */
+    private extractRawSchema;
+}
+//# sourceMappingURL=ToolBase.d.ts.map

package/build/shared/ToolBase.d.ts.map

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

package/build/shared/ToolBase.js

@@ -0,0 +1,247 @@
+import { getRepositoryOrThrow } from "./helpers/getRepositoryOrThrow.js";
+/**
+ * Abstract base class for MCP tools
+ *
+ * Provides a structured, class-based approach to creating tools with:
+ * - Type-safe parameter validation via Zod schemas
+ * - Consistent error handling patterns
+ * - Logging integration
+ * - Repository access helpers
+ *
+ * @example
+ * ```typescript
+ * class CreateSpaceTool extends ToolBase<CreateSpaceParams> {
+ *   protected config: ToolConfig = {
+ *     name: "space-create",
+ *     description: "Creates a new space",
+ *     annotations: { destructiveHint: true }
+ *   };
+ *
+ *   protected getParamsSchema() {
+ *     return z.object({
+ *       name: z.string().min(2).max(100),
+ *     });
+ *   }
+ *
+ *   async execute(params: CreateSpaceParams): Promise<CallToolResult> {
+ *     const repo = await this.getRepository(SpacesRepository);
+ *     const response = await repo.createSpace(params);
+ *     return this.success(response);
+ *   }
+ * }
+ * ```
+ */
+export class ToolBase {
+    server; // McpServer instance - typed as any to avoid circular dependency
+    serverName; // Name of the MCP server (e.g., "mcp-content", "mcp-channels")
+    logger;
+    /**
+     * Initializes the tool with MCP server context
+     * Called automatically during registration
+     */
+    initialize(server, serverName, logger) {
+        this.server = server;
+        this.serverName = serverName;
+        this.logger = logger;
+    }
+    /**
+     * Registers this tool with the MCP server
+     * Called by McpServerBase during setup
+     */
+    registerTool(server, serverName, logger) {
+        this.initialize(server, serverName, logger);
+        const schema = this.getParamsSchema();
+        const rawInputSchema = this.extractRawSchema(schema);
+        server.registerTool(this.config.name, {
+            description: this.config.description,
+            inputSchema: rawInputSchema,
+            ...(this.config.annotations
+                ? {
+                    annotations: this.config.annotations,
+                }
+                : {}),
+        }, async (params) => {
+            try {
+                const validatedParams = schema.parse(params);
+                const result = await this.execute(validatedParams);
+                return result;
+            }
+            catch (error) {
+                // Return structured error by default so the LLM gets context
+                // Set catchErrors: false explicitly to re-throw instead
+                if (this.config.catchErrors !== false) {
+                    return this.errorResponse(error, {
+                        params,
+                    });
+                }
+                // Explicit opt-out: log and re-throw
+                this.logger(`Tool ${this.config.name} failed`, {
+                    params,
+                    error,
+                }, "error");
+                throw error;
+            }
+        });
+    }
+    /**
+     * Returns whether this tool requires authentication
+     */
+    get isPublic() {
+        return this.config.isPublic ?? false;
+    }
+    /**
+     * Returns whether this tool is deprecated
+     */
+    get isDeprecated() {
+        return this.config.isDeprecated ?? false;
+    }
+    /**
+     * Returns the deprecation metadata for this tool (if deprecated)
+     */
+    get deprecationMetadata() {
+        return this.config.deprecationMetadata;
+    }
+    /**
+     * Helper: Gets a repository instance using the configured platform
+     * Uses SinglePlatformProvider to get platform config from environment variables
+     *
+     * @param RepositoryClass - Repository constructor
+     * @returns Repository instance
+     * @throws Error if platform not configured
+     */
+    async getRepository(RepositoryClass) {
+        return getRepositoryOrThrow(RepositoryClass, this.logger);
+    }
+    /**
+     * Helper: Formats successful response as MCP result
+     */
+    success(data, message) {
+        const text = message
+            ? `${message}\n\n${JSON.stringify(data, null, 2)}`
+            : JSON.stringify(data, null, 2);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text,
+                },
+            ],
+            isError: false,
+        };
+    }
+    /**
+     * Helper: Formats error response as MCP result
+     * Returns a properly formatted error response without throwing
+     */
+    errorResponse(error, context) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorDetails = {
+            error: errorMessage,
+            ...(error instanceof Error && error.stack
+                ? {
+                    stack: error.stack,
+                }
+                : {}),
+            ...context,
+        };
+        this.logger("Tool execution failed", errorDetails, "error");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(errorDetails, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    /**
+     * Helper: Logs debug information
+     */
+    debug(message, data) {
+        this.logger(message, data, "debug");
+    }
+    /**
+     * Helper: Logs info
+     */
+    info(message, data) {
+        this.logger(message, data, "info");
+    }
+    /**
+     * Helper: Logs error
+     */
+    logError(message, data) {
+        this.logger(message, data, "error");
+    }
+    /**
+     * Helper: Request user confirmation via MCP elicitation
+     *
+     * Use this for sensitive operations like password changes, email updates, etc.
+     * Returns the user's response or null if client doesn't support elicitation.
+     *
+     * @param message - Message to display to the user
+     * @param fields - Optional form fields to collect (for form-based elicitation)
+     * @returns User response with action ('accept'|'decline'|'cancel') and optional content
+     *
+     * @example
+     * ```typescript
+     * // Simple confirmation
+     * const result = await this.elicit("Are you sure you want to change the password?");
+     * if (result?.action !== 'accept') {
+     *   return this.errorResponse(new Error("Password change cancelled by user"));
+     * }
+     *
+     * // With form fields
+     * const result = await this.elicit("Confirm email change", {
+     *   confirm: { type: 'boolean', description: 'I confirm this change' }
+     * });
+     * ```
+     */
+    async elicit(message, fields) {
+        // Check if server supports elicitation
+        if (!this.server?.server?.elicitInput) {
+            this.debug("Elicitation not supported by server");
+            return null;
+        }
+        try {
+            // Build the requested schema
+            const requestedSchema = {
+                type: "object",
+                properties: {},
+            };
+            if (fields) {
+                for (const [key, field] of Object.entries(fields)) {
+                    requestedSchema.properties[key] = field;
+                }
+            }
+            const result = await this.server.server.elicitInput({
+                message,
+                requestedSchema,
+            });
+            this.debug("Elicitation result", {
+                action: result.action,
+            });
+            return result;
+        }
+        catch (error) {
+            // Client may not support elicitation
+            this.debug("Elicitation failed", {
+                error,
+            });
+            return null;
+        }
+    }
+    /**
+     * Extracts raw schema shape for MCP registration
+     * Handles Zod object schemas
+     */
+    extractRawSchema(schema) {
+        // For ZodObject, extract the shape
+        if ("shape" in schema && typeof schema.shape === "object") {
+            return schema.shape;
+        }
+        // Fallback: return empty object (MCP will infer from runtime)
+        return {};
+    }
+}
+//# sourceMappingURL=ToolBase.js.map

package/build/shared/ToolBase.js.map

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