refactor: align tool types with MCP SDK schema and extract McpInputSchema type

Author: MQ37

src/mcp/server.ts

@@ -272,8 +272,10 @@ export class ActorsMcpServer {
                     const clonedWrap = cloneToolEntry(wrap);
 
                     // Add Skyfire instructions to description if not already present
-                    if (!clonedWrap.tool.description.includes(SKYFIRE_TOOL_INSTRUCTIONS)) {
+                    if (clonedWrap.tool.description && !clonedWrap.tool.description.includes(SKYFIRE_TOOL_INSTRUCTIONS)) {
                         clonedWrap.tool.description += `\n\n${SKYFIRE_TOOL_INSTRUCTIONS}`;
+                    } else if (!clonedWrap.tool.description) {
+                        clonedWrap.tool.description = SKYFIRE_TOOL_INSTRUCTIONS;
                     }
                     // Add skyfire-pay-id property if not present
                     if (clonedWrap.tool.inputSchema && 'properties' in clonedWrap.tool.inputSchema) {

src/tools/actor.ts

@@ -19,7 +19,7 @@ import { getActorMCPServerPath, getActorMCPServerURL } from '../mcp/actors.js';
 import { connectMCPClient } from '../mcp/client.js';
 import { getMCPServerTools } from '../mcp/proxy.js';
 import { actorDefinitionPrunedCache } from '../state.js';
-import type { ActorDefinitionStorage, ActorInfo, ApifyToken, DatasetItem, ToolEntry } from '../types.js';
+import type { ActorDefinitionStorage, ActorInfo, ApifyToken, DatasetItem, McpInputSchema, ToolEntry } from '../types.js';
 import { ensureOutputWithinCharLimit, getActorDefinitionStorageFieldNames, getActorMcpUrlCached } from '../utils/actor.js';
 import { fetchActorDetails } from '../utils/actor-details.js';
 import { buildActorResponseContent } from '../utils/actor-response.js';
@@ -196,7 +196,7 @@ Actor description: ${actorDefinitionPruned.description}`;
                 name: actorNameToToolName(actorDefinitionPruned.actorFullName),
                 actorFullName: actorDefinitionPruned.actorFullName,
                 description,
-                inputSchema,
+                inputSchema: inputSchema as McpInputSchema,
                 ajvValidate,
                 memoryMbytes,
             },
@@ -358,7 +358,7 @@ Step 2: Call Actor (step="call")
 
 EXAMPLES:
 - user_input: Get instagram posts using apify/instagram-scraper`,
-        inputSchema: zodToJsonSchema(callActorArgs),
+        inputSchema: zodToJsonSchema(callActorArgs) as McpInputSchema,
         ajvValidate: ajv.compile({
             ...zodToJsonSchema(callActorArgs),
             // Additional props true to allow skyfire-pay-id

src/types.ts

@@ -1,13 +1,14 @@
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import type { Notification, Prompt, Request } from '@modelcontextprotocol/sdk/types.js';
+import type { Notification, Prompt, Request, ToolSchema } from '@modelcontextprotocol/sdk/types.js';
 import type { ValidateFunction } from 'ajv';
 import type { ActorDefaultRunOptions, ActorDefinition, ActorStoreList, PricingInfo } from 'apify-client';
 
 import type { ACTOR_PRICING_MODEL } from './const.js';
 import type { ActorsMcpServer } from './mcp/server.js';
 import type { toolCategories } from './tools/index.js';
 import type { ProgressTracker } from './utils/progress.js';
+import z from 'zod';
 
 export interface ISchemaProperties {
     type: string;
@@ -60,19 +61,22 @@ export type ActorDefinitionPruned = Pick<ActorDefinitionWithDesc,
 
 /**
  * Base interface for all tools in the MCP server.
- * Contains common properties shared by all tool types.
+ * Extends the MCP SDK's Tool schema, which requires inputSchema to have type: "object".
+ * Adds ajvValidate for runtime validation.
  */
-export interface ToolBase {
-    /** Unique name/identifier for the tool */
-    name: string;
-    /** Description of what the tool does */
-    description: string;
-    /** JSON schema defining the tool's input parameters */
-    inputSchema: object;
+export interface ToolBase extends z.infer<typeof ToolSchema> {
     /** AJV validation function for the input schema */
     ajvValidate: ValidateFunction;
 }
 
+/**
+ * Type for MCP SDK's inputSchema constraint.
+ * Extracted directly from the MCP SDK's ToolSchema to ensure alignment with the specification.
+ * The MCP SDK requires inputSchema to have type: "object" (literal) at the top level.
+ * Use this type when casting schemas that have type: string to the strict MCP format.
+ */
+export type McpInputSchema = z.infer<typeof ToolSchema>['inputSchema'];
+
 /**
  * Interface for Actor-based tools - tools that wrap Apify Actors.
  * Extends ToolBase with Actor-specific properties.