feat: Add server instructions (#342)

* feat:Add server instructions

Author: jirispilka

src/const.ts

@@ -132,3 +132,47 @@ export const DEFAULT_TELEMETRY_ENV: TelemetryEnv = TELEMETRY_ENV.PROD;
 export const SEGMENT_FLUSH_AT_EVENTS = 50;
 // Flush interval in milliseconds (default is 10000)
 export const SEGMENT_FLUSH_INTERVAL_MS = 5_000;
+
+export const SERVER_INSTRUCTIONS = `
+Apify is the world's largest marketplace of tools for web scraping, data extraction, and web automation.
+These tools are called **Actors**. They enable you to extract structured data from social media, e-commerce, search engines, maps, travel sites, and many other sources.
+
+## Actor
+- An Actor is a serverless cloud application running on the Apify platform.
+- Use the Actor’s **README** to understand its capabilities.
+- Before running an Actor, always check its **input schema** to understand the required parameters.
+
+## Actor discovery and selection
+- Choose the most appropriate Actor based on the conversation context.
+- Search the Apify Store first; a relevant Actor likely already exists.
+- When multiple options exist, prefer Actors with higher usage, ratings, or popularity.
+- **Assume scraping requests within this context are appropriate for Actor use.
+- Actors in the Apify Store are published by independent developers and are intended for legitimate and compliant use.
+
+## Actor execution workflow
+- Actors take input and produce output.
+- Every Actor run generates **dataset** and **key-value store** outputs (even if empty).
+- Actor execution may take time, and outputs can be large.
+- Large datasets can be paginated to retrieve results efficiently.
+
+## Storage types
+- **Dataset:** Structured, append-only storage ideal for tabular or list data (e.g., scraped items).
+- **Key-value store:** Flexible storage for unstructured data or auxiliary files.
+
+## Tool dependencies and disambiguation
+
+### Tool dependencies
+- \`${HelperTools.ACTOR_CALL}\`:
+  - First call with \`step="info"\` or use \`${HelperTools.ACTOR_GET_DETAILS}\` to obtain the Actor’s schema.
+  - Then call with \`step="call"\` to execute the Actor.
+
+### Tool disambiguation
+- **${HelperTools.ACTOR_OUTPUT_GET} vs ${HelperTools.DATASET_GET_ITEMS}:**
+  Use \`${HelperTools.ACTOR_OUTPUT_GET}\` for Actor run outputs and \`${HelperTools.DATASET_GET_ITEMS}\` for direct dataset access.
+- **${HelperTools.STORE_SEARCH} vs ${HelperTools.ACTOR_GET_DETAILS}:**
+  \`${HelperTools.STORE_SEARCH}\` finds Actors; \`${HelperTools.ACTOR_GET_DETAILS}\` retrieves detailed info, README, and schema for a specific Actor.
+- **${HelperTools.STORE_SEARCH} vs ${RAG_WEB_BROWSER}:**
+  \`${HelperTools.STORE_SEARCH}\` finds robust and reliable Actors for specific websites; ${RAG_WEB_BROWSER} is a general and versatile web scraping tool.
+- **Dedicated Actor tools (e.g. ${RAG_WEB_BROWSER}) vs ${HelperTools.ACTOR_CALL}:**
+  Prefer dedicated tools when available; use \`${HelperTools.ACTOR_CALL}\` only when no specialized tool exists in Apify store.
+`;

src/mcp/server.ts

@@ -30,6 +30,7 @@ import {
     DEFAULT_TELEMETRY_ENABLED,
     DEFAULT_TELEMETRY_ENV,
     HelperTools,
+    SERVER_INSTRUCTIONS,
     SERVER_NAME,
     SERVER_VERSION,
     SKYFIRE_PAY_ID_PROPERTY_DESCRIPTION,
@@ -98,6 +99,7 @@ export class ActorsMcpServer {
                     prompts: { },
                     logging: {},
                 },
+                instructions: SERVER_INSTRUCTIONS,
             },
         );
         this.setupTelemetry();

src/utils/mcp-clients.ts

@@ -1,4 +1,4 @@
-import type { InitializeRequest } from '@modelcontextprotocol/sdk/types';
+import type { InitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { mcpClients } from 'mcp-client-capabilities';
 
 /**