genudo-mcp-client 1.0.0

package/.env.example

@@ -0,0 +1,13 @@
+# Genudo MCP Client Configuration
+
+# Your Genudo API Key (REQUIRED)
+# Get this from your Genudo account settings
+GENUDO_API_KEY=your_api_key_here
+
+# Base URL (OPTIONAL - defaults to https://api.genudo.ai)
+# For self-hosted instances or local development
+# GENUDO_BASE_URL=https://your-instance.com
+
+# Allow insecure SSL (OPTIONAL - defaults to false)
+# Only use for local development with self-signed certificates
+# GENUDO_ALLOW_INSECURE_SSL=true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Genudo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# Genudo MCP Client
+
+[![npm version](https://img.shields.io/npm/v/genudo-mcp-client)](https://www.npmjs.com/package/genudo-mcp-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+
+A lightweight bridge that connects [Claude Code](https://code.claude.com) to Genudo's Model Context Protocol (MCP) server, enabling AI-powered workflow automation directly from your Claude Code interface.
+
+## Overview
+
+Genudo MCP Client bridges the communication gap between Claude Code's stdio-based MCP implementation and Genudo's HTTP/SSE-based MCP server. This allows you to leverage Genudo's powerful business automation tools directly within your Claude Code conversations.
+
+## Features
+
+Access Genudo's business automation tools directly from Claude Code. The server exposes 21 tools across five areas:
+
+- **📊 Analytics** — account summary, messaging volume stats, AI performance & cost (`get_account_summary`, `get_messaging_stats`, `get_ai_performance`)
+- **🔎 Read your workspace** — list pipelines, stages, contacts, messages, opportunities, and variables (`list_pipelines`, `list_pipeline_stages`, `list_contacts`, `list_messages`, `list_opportunities`, `list_variables`)
+- **🚀 Build pipelines** — a guided step-by-step builder plus direct create/update (`start_pipeline_journey`, `get_pipeline_options`, `create_pipeline`, `update_pipeline`)
+- **🧩 Stages & actions** — configure pipeline stages and external-integration actions/webhooks (`create_stage`, `update_stage`, `create_action`, `update_action`)
+- **⚙️ Variables & opportunities** — manage pipeline variables and update opportunities (`create_variable`, `update_variable`, `delete_variable`, `update_opportunities`)
+
+### Three workflows to start with
+
+1. **Audit my AI business operations** — Claude pulls your account, messaging, and AI-cost stats and surfaces the top fixes.
+2. **Analyze my agent performance** — spot expensive agents, low-completion stages, and actions that aren't triggering.
+3. **Create or improve a pipeline** — e.g. "Create a Messenger sales agent for a summer camp; collect name, phone, branch, child age; escalate on special-needs questions."
+
+## Quick Start
+
+One command — no clone, no manual config:
+
+```bash
+claude mcp add --env GENUDO_API_KEY=YOUR_KEY --transport stdio genudo -- npx -y genudo-mcp-client
+```
+
+Replace `YOUR_KEY` with your Genudo API key (Settings → API Keys). Restart Claude Code and start using Genudo tools!
+
+## Prerequisites
+
+- Node.js 18.0.0 or higher
+- A Genudo account with API access
+- Your Genudo API key
+
+## Installation
+
+### Recommended: one command
+
+```bash
+claude mcp add --env GENUDO_API_KEY=YOUR_KEY --transport stdio genudo -- npx -y genudo-mcp-client
+```
+
+`npx` fetches and runs the published package — no clone, no local path. Get your API key from Settings → API Keys, then restart Claude Code.
+
+### Alternative: from source
+
+For local development or contributions:
+
+```bash
+git clone https://github.com/genudo-ai/genudo_mcp.git
+cd genudo_mcp
+npm install
+```
+
+Then configure Claude Code manually (see Configuration section below).
+
+## Configuration
+
+### Step 1: Get Your API Key
+
+1. Log in to your [Genudo account](https://genudo.ai)
+2. Navigate to **Settings** → **API Keys**
+3. Click **Generate New API Key**
+4. Copy your API key (keep it secure!)
+
+### Step 2: Connect your MCP client
+
+**Recommended — Claude Code, one command:**
+
+```bash
+claude mcp add --env GENUDO_API_KEY=YOUR_KEY --transport stdio genudo -- npx -y genudo-mcp-client
+```
+
+**Other clients (Codex, Cursor, Windsurf, Claude Desktop):** same package, add this block to the client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "genudo": {
+      "command": "npx",
+      "args": ["-y", "genudo-mcp-client"],
+      "env": {
+        "GENUDO_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+<details>
+<summary>Running from source instead (contributors)</summary>
+
+If you cloned the repo rather than using the published package, point at your local `index.js`:
+
+```json
+{
+  "mcpServers": {
+    "genudo": {
+      "command": "node",
+      "args": ["/absolute/path/to/genudo_mcp/index.js"],
+      "env": { "GENUDO_API_KEY": "your_api_key_here" }
+    }
+  }
+}
+```
+
+Replace the path with where you cloned the repo.
+</details>
+
+### Step 3: Restart Claude Code
+
+Exit your current Claude Code session and start a new one:
+
+```bash
+# Exit current session
+exit
+
+# Start new session
+claude
+```
+
+## Usage
+
+Once configured, Claude Code will automatically have access to your Genudo tools. You can use them in your conversations:
+
+**Example:**
+```
+User: "Show me my account summary"
+Claude: [Uses get_account_summary tool to fetch your data]
+
+User: "Create a new sales pipeline using GPT-4"
+Claude: [Uses get_pipeline_options and create_pipeline tools]
+```
+
+## Testing the Connection
+
+You can test the bridge manually:
+
+```bash
+# Set your API key
+export GENUDO_API_KEY="your_api_key_here"
+
+# Run the bridge
+node index.js
+
+# Send a test message (paste this and press Enter):
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
+
+# You should receive a response with server info
+```
+
+## Troubleshooting
+
+### "GENUDO_API_KEY environment variable is required"
+- Make sure you've set the API key in your Claude Code config
+- Verify the API key is valid in your Genudo account
+
+### "Timeout waiting for endpoint from SSE"
+- Check that `GENUDO_BASE_URL` is correct (defaults to `https://api.genudo.ai`)
+- Verify your server is running and accessible
+- Check firewall/network settings
+
+### "HTTP 401: Unauthorized"
+- Your API key is invalid or expired
+- Generate a new API key in your Genudo account settings
+
+### Connection Issues with Self-Signed Certificates
+- The bridge is configured to accept self-signed certificates for local development
+- For production, use proper SSL certificates
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `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) |
+
+## Development
+
+### Project Structure
+```
+genudo-mcp-client/
+├── index.js           # Main bridge script
+├── package.json       # Node.js project config
+├── .env.example       # Environment variables template
+└── README.md          # This file
+```
+
+### How It Works
+
+1. Bridge connects to SSE endpoint to get the message POST URL
+2. Reads JSON-RPC requests from stdin (from Claude Code)
+3. Forwards requests as HTTP POST to the Genudo server
+4. Returns responses via stdout back to Claude Code
+
+```
+Claude Code → (stdin) → Bridge → (HTTPS) → Genudo MCP Server
+                ↑                              ↓
+                └─────── (stdout) ←────────────┘
+```
+
+## Security Notes
+
+- **Never commit your API key** to version control
+- Store API keys securely (environment variables, secrets manager)
+- Rotate API keys regularly
+- Use HTTPS in production
+- Limit API key permissions to minimum required access
+
+## License
+
+MIT
+
+## Support
+
+Need help? We're here for you:
+
+- 📖 [Documentation](https://docs.genudo.ai)
+- 💬 [Community Forum](https://community.genudo.ai)
+- 🐛 [Report an Issue](https://github.com/genudo-ai/genudo_mcp/issues)
+- 📧 [Email Support](mailto:support@genudo.ai)
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
+
+Quick overview:
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Changelog
+
+See the [GitHub Releases](https://github.com/genudo-ai/genudo_mcp/releases) page for changes and version history.
+
+## Related Projects
+
+- [Genudo](https://genudo.ai) - The main Genudo automation platform
+- [Model Context Protocol](https://modelcontextprotocol.io) - Learn more about MCP
+- [Claude Code](https://code.claude.com) - The Claude AI coding assistant

package/index.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+const EventSource = require('eventsource');
+const fetch = require('node-fetch');
+const readline = require('readline');
+const https = require('https');
+
+// Configuration from environment variables
+const BASE_URL = process.env.GENUDO_BASE_URL || 'https://api.genudo.ai';
+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';
+
+// HTTPS agent configuration
+// For local development with self-signed certificates, set GENUDO_ALLOW_INSECURE_SSL=true
+const httpsAgent = new https.Agent({
+  rejectUnauthorized: !ALLOW_INSECURE_SSL
+});
+
+// Validate configuration
+if (!API_KEY) {
+  console.error('ERROR: GENUDO_API_KEY environment variable is required');
+  process.exit(1);
+}
+
+// Global state
+let messageEndpoint = null;
+let isInitialized = false;
+
+/**
+ * Log debug messages to stderr (won't interfere with stdout JSON-RPC)
+ */
+function debug(...args) {
+  console.error('[Genudo MCP Bridge]', ...args);
+}
+
+/**
+ * Connect to SSE endpoint to get the message endpoint URL
+ */
+function connectSSE() {
+  return new Promise((resolve, reject) => {
+    debug('Connecting to SSE endpoint:', SSE_URL);
+
+    const eventSource = new EventSource(SSE_URL, {
+      headers: {
+        'Api-Key': API_KEY
+      },
+      https: { rejectUnauthorized: !ALLOW_INSECURE_SSL }
+    });
+
+    eventSource.addEventListener('endpoint', (event) => {
+      messageEndpoint = event.data;
+      debug('Received message endpoint:', messageEndpoint);
+      isInitialized = true;
+      resolve(messageEndpoint);
+    });
+
+    eventSource.onerror = (error) => {
+      debug('SSE connection error:', error);
+      // Don't reject - SSE will auto-reconnect
+    };
+
+    // Timeout if no endpoint received within 10 seconds
+    setTimeout(() => {
+      if (!isInitialized) {
+        eventSource.close();
+        reject(new Error('Timeout waiting for endpoint from SSE'));
+      }
+    }, 10000);
+  });
+}
+
+/**
+ * Forward JSON-RPC request to the Laravel MCP server
+ */
+async function forwardRequest(jsonRpcRequest) {
+  if (!messageEndpoint) {
+    throw new Error('Message endpoint not initialized');
+  }
+
+  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
+  });
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+
+  // Handle 204 No Content (for notifications)
+  if (response.status === 204) {
+    return null;
+  }
+
+  return await response.json();
+}
+
+/**
+ * Process a single line of input (JSON-RPC request)
+ */
+async function processInput(line) {
+  try {
+    const request = JSON.parse(line);
+    debug('Received request:', request.method);
+
+    const response = await forwardRequest(request);
+
+    // Only write response if there is one (notifications don't get responses)
+    if (response !== null) {
+      // Write response to stdout for Claude Code to read
+      console.log(JSON.stringify(response));
+    }
+  } catch (error) {
+    debug('Error processing request:', error.message);
+
+    // Try to extract ID from the line if possible
+    let id = null;
+    try {
+      const parsed = JSON.parse(line);
+      id = parsed.id;
+    } catch (e) {
+      // Ignore
+    }
+
+    // Send error response
+    const errorResponse = {
+      jsonrpc: '2.0',
+      id: id,
+      error: {
+        code: -32603,
+        message: error.message
+      }
+    };
+    console.log(JSON.stringify(errorResponse));
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  try {
+    debug('Starting Genudo MCP Bridge...');
+
+    // Connect to SSE and get message endpoint
+    await connectSSE();
+    debug('Bridge initialized successfully');
+
+    // Set up readline to process stdin line by line
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false
+    });
+
+    // Process each line of input
+    rl.on('line', async (line) => {
+      if (line.trim()) {
+        await processInput(line);
+      }
+    });
+
+    // Handle EOF
+    rl.on('close', () => {
+      debug('Input stream closed, exiting...');
+      process.exit(0);
+    });
+
+  } catch (error) {
+    debug('Fatal error:', error.message);
+    process.exit(1);
+  }
+}
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+  debug('Received SIGINT, shutting down...');
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  debug('Received SIGTERM, shutting down...');
+  process.exit(0);
+});
+
+// Start the bridge
+main();

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "genudo-mcp-client",
+  "version": "1.0.0",
+  "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",
+  "bin": {
+    "genudo-mcp-client": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "genudo",
+    "ai",
+    "automation",
+    "bridge",
+    "stdio",
+    "sse",
+    "http"
+  ],
+  "author": {
+    "name": "Genudo",
+    "email": "support@genudo.ai",
+    "url": "https://genudo.ai"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/genudo-ai/genudo_mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/genudo-ai/genudo_mcp/issues",
+    "email": "support@genudo.ai"
+  },
+  "homepage": "https://github.com/genudo-ai/genudo_mcp#readme",
+  "dependencies": {
+    "eventsource": "^2.0.2",
+    "node-fetch": "^2.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ]
+}