genudo-mcp-client 1.0.0 → 1.0.2

package/README.md

@@ -185,6 +185,8 @@ node index.js
 | `GENUDO_API_KEY` | **Yes** | - | Your Genudo API key from account settings |
 | `GENUDO_BASE_URL` | No | `https://api.genudo.ai` | Base URL for self-hosted Genudo instances |
 | `GENUDO_ALLOW_INSECURE_SSL` | No | `false` | Allow self-signed SSL certificates (local development only) |
+| `GENUDO_REQUEST_TIMEOUT` | No | `8000` | Per-attempt request timeout in ms before retrying |
+| `GENUDO_REQUEST_RETRIES` | No | `4` | Number of attempts for a request before giving up |
 
 ## Development
 

package/index.js

@@ -11,6 +11,36 @@ const SSE_URL = `${BASE_URL}/api/user/mcp/sse`;
 const API_KEY = process.env.GENUDO_API_KEY;
 const ALLOW_INSECURE_SSL = process.env.GENUDO_ALLOW_INSECURE_SSL === 'true';
 
+// The Genudo backend can be slow to answer the first request after connecting
+// (cold start — observed 1s to 30s+). Rather than let one slow attempt hang the
+// whole MCP handshake, we time out each attempt fast and retry.
+const REQUEST_TIMEOUT = parseInt(process.env.GENUDO_REQUEST_TIMEOUT || '8000', 10);
+const REQUEST_RETRIES = parseInt(process.env.GENUDO_REQUEST_RETRIES || '4', 10);
+
+// Server-level guidance returned in the `initialize` handshake. MCP clients
+// (Claude Code, Codex, Cursor, ...) inject this into the model's context, so it
+// teaches any client how to get value fast and avoid the common failure modes —
+// without the user having to write prompts. Keep it concise and high-signal.
+const SERVER_INSTRUCTIONS = [
+  'Genudo MCP: control + analytics for AI sales/support pipelines (pipelines, stages, actions/webhooks, variables, contacts, opportunities, messages, analytics). 21 tools, read + write.',
+  '',
+  'PICK A PATTERN:',
+  '- Audit a pipeline: list_pipelines -> list_pipeline_stages -> list_variables -> list_opportunities -> list_contacts -> list_messages',
+  '- Build from scratch: start_pipeline_journey (ALWAYS first) -> get_pipeline_options (valid IDs) -> create_pipeline -> create_stage (xN) -> create_variable -> create_action',
+  '- Add an integration: list_pipelines -> list_pipeline_stages -> list_variables -> create_variable -> create_action',
+  '- Report activity: get_account_summary -> get_ai_performance -> list_opportunities -> get_messaging_stats',
+  '',
+  'RULES THAT PREVENT FAILURES:',
+  '1. Discover IDs before writing: get_pipeline_options (agent_type_id, ai_model_id, language_id, channel_id); list_pipelines (pipeline_id); list_pipeline_stages (stage_id); list_variables (variable_id).',
+  '2. Actions CANNOT use raw system placeholders. Never put {{opportunity.contact_email}} in an action url/headers/payload. Instead create_variable {type:"from_system", value:"opportunity.contact_email"} and reference {{its_name}}. Variable types: fixed | from_system | from_action | from_ai.',
+  '3. create_pipeline: if is_model_routing_enabled=true, model_pool is required with exactly 4 tiers (router, simple, moderate, complex). persona + instructions drive quality — ask the user for a 1-2 sentence business description, then offer to write them.',
+  '4. create_stage nature in {neutral, won, lost}. create_action fixed_trigger in {stage_started, on_any_message, on_user_message, custom}; omit stage_id for a pipeline-wide action.',
+  '5. Immutable after create: pipeline agent_type; action fixed_trigger can only change to on_user_message/custom on update; update_opportunities stage moves must stay within the same pipeline.',
+  '6. Not exposed (do not attempt): listing actions, deleting actions/stages/pipelines, KB management, sending manual messages, reading plan limits.',
+  '',
+  'Confirm before bulk writes (update_opportunities is bulk). The backend can be slow on the first call — retries are automatic.'
+].join('\n');
+
 // HTTPS agent configuration
 // For local development with self-signed certificates, set GENUDO_ALLOW_INSECURE_SSL=true
 const httpsAgent = new https.Agent({
@@ -80,26 +110,46 @@ async function forwardRequest(jsonRpcRequest) {
 
   debug('Forwarding request:', jsonRpcRequest.method, 'id:', jsonRpcRequest.id);
 
-  const response = await fetch(messageEndpoint, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Api-Key': API_KEY
-    },
-    body: JSON.stringify(jsonRpcRequest),
-    agent: httpsAgent
-  });
+  let lastError;
+  for (let attempt = 1; attempt <= REQUEST_RETRIES; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT);
+    try {
+      const response = await fetch(messageEndpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Api-Key': API_KEY
+        },
+        body: JSON.stringify(jsonRpcRequest),
+        agent: httpsAgent,
+        signal: controller.signal
+      });
+      clearTimeout(timer);
 
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-  }
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
 
-  // Handle 204 No Content (for notifications)
-  if (response.status === 204) {
-    return null;
-  }
+      // Handle 204 No Content (for notifications)
+      if (response.status === 204) {
+        return null;
+      }
 
-  return await response.json();
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timer);
+      lastError = error;
+      const reason = error.name === 'AbortError'
+        ? `timeout after ${REQUEST_TIMEOUT}ms`
+        : error.message;
+      debug(`Attempt ${attempt}/${REQUEST_RETRIES} failed (${reason})`);
+      if (attempt < REQUEST_RETRIES) {
+        await new Promise((r) => setTimeout(r, 500));
+      }
+    }
+  }
+  throw lastError;
 }
 
 /**
@@ -110,6 +160,31 @@ async function processInput(line) {
     const request = JSON.parse(line);
     debug('Received request:', request.method);
 
+    // Answer the MCP handshake locally so Claude's startup never blocks on
+    // backend cold-start latency. The Genudo server accepts tool calls without a
+    // forwarded initialize (verified), so we synthesize the response and warm the
+    // backend in the background for the first real request.
+    if (request.method === 'initialize') {
+      console.log(JSON.stringify({
+        jsonrpc: '2.0',
+        id: request.id,
+        result: {
+          protocolVersion: (request.params && request.params.protocolVersion) || '2024-11-05',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'Genudo', version: '1.0.2' },
+          instructions: SERVER_INSTRUCTIONS
+        }
+      }));
+      forwardRequest({ jsonrpc: '2.0', id: 'warmup', method: 'tools/list', params: {} })
+        .catch(() => {});
+      return;
+    }
+
+    // Handshake is handled locally, so there is no server session to notify.
+    if (request.method === 'notifications/initialized') {
+      return;
+    }
+
     const response = await forwardRequest(request);
 
     // Only write response if there is one (notifications don't get responses)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genudo-mcp-client",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A lightweight bridge connecting Claude Code to Genudo's Model Context Protocol (MCP) server for AI-powered workflow automation",
   "mcpName": "io.github.genudo-ai/genudo_mcp",
   "main": "index.js",