kntor-mcp 1.0.0

package/README.md

@@ -0,0 +1,179 @@
+# Kntor MCP Server
+
+Model Context Protocol (MCP) server for Kntor.io Healthcare ERP. Allows AI agents (Claude, n8n, WhatsApp bots) to interact with the ERP system.
+
+## Claude Desktop Setup
+
+### Option 1: Using npx (Recommended)
+
+Add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "kntor-erp": {
+      "command": "npx",
+      "args": ["-y", "kntor-mcp"],
+      "env": {
+        "KNTOR_API_KEY": "kntor_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Option 2: Using local installation
+
+```json
+{
+  "mcpServers": {
+    "kntor-erp": {
+      "command": "node",
+      "args": ["C:\\path\\to\\kntor-mcp-server\\bin\\kntor-mcp.mjs"],
+      "env": {
+        "KNTOR_API_KEY": "kntor_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+After saving the config, restart Claude Desktop.
+
+## Server Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Set up secrets
+wrangler secret put SUPABASE_URL
+wrangler secret put SUPABASE_ANON_KEY
+wrangler secret put SUPABASE_SERVICE_ROLE_KEY
+
+# Run locally
+pnpm run dev
+
+# Deploy
+pnpm run deploy
+```
+
+## Authentication
+
+The server uses a 3-layer authentication model:
+
+1. **API Key** (`x-api-key` header) - Identifies the brand/tenant
+2. **JWT** (in tool calls) - Identifies the user, preserves `auth.uid()`
+3. **RBAC** - Verifies permissions before executing
+
+### Getting an API Key
+
+API keys are created by brand admins in the Kntor.io dashboard:
+1. Go to Settings → MCP Integration
+2. Click "Create API Key"
+3. Save the key (shown only once)
+
+## Available Tools
+
+### `get_availability`
+Check professional availability for appointment scheduling.
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "get_availability",
+    "arguments": {
+      "jwt": "eyJhbGciOiJS...",
+      "date": "2025-01-20",
+      "professional_id": "uuid-optional",
+      "profession_type": "psychologist"
+    }
+  }
+}
+```
+
+### `schedule_appointment`
+Schedule a new appointment.
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "schedule_appointment",
+    "arguments": {
+      "jwt": "eyJhbGciOiJS...",
+      "patient_id": "patient-uuid",
+      "professional_id": "prof-uuid",
+      "appointment_date": "2025-01-20",
+      "start_time": "10:00",
+      "duration_minutes": 60
+    }
+  }
+}
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Health check |
+| `/health` | GET | Health check |
+| `/mcp` | POST | MCP JSON-RPC endpoint |
+| `/messages` | POST | MCP JSON-RPC endpoint (alias) |
+
+## Example Request
+
+```bash
+curl -X POST https://mcp.kntor.io/mcp \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: kntor_your_api_key_here" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/list"
+  }'
+```
+
+## Pricing Tiers
+
+| Tier | Monthly Limit | Price |
+|------|--------------|-------|
+| free | 100 calls | $0 |
+| starter | 1,000 calls | $29/mo |
+| pro | 10,000 calls | $99/mo |
+| enterprise | Unlimited | Custom |
+
+## Development
+
+```bash
+# Type check
+pnpm run typecheck
+
+# Run locally
+pnpm run dev
+
+# Deploy to production
+pnpm run deploy
+```
+
+## Architecture
+
+```
+mcp-server/
+├── src/
+│   ├── index.ts           # Worker entry point
+│   ├── types.ts           # TypeScript types
+│   ├── auth/
+│   │   ├── api-key.ts     # API key validation
+│   │   └── jwt.ts         # JWT validation + user client
+│   ├── tools/
+│   │   ├── index.ts       # Tool registry
+│   │   ├── get-availability.ts
+│   │   └── schedule-appointment.ts
+│   └── utils/
+│       ├── supabase.ts    # Supabase client factory
+│       └── metering.ts    # Usage logging
+├── wrangler.toml          # Cloudflare config
+└── package.json
+```

package/bin/kntor-mcp.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * Kntor MCP Client
+ *
+ * Stdio proxy that connects Claude Desktop to Kntor.io ERP.
+ * Handles MCP protocol communication over stdin/stdout.
+ *
+ * Usage:
+ *   KNTOR_API_KEY=kntor_xxx npx kntor-mcp
+ *
+ * Configuration for Claude Desktop (claude_desktop_config.json):
+ * {
+ *   "mcpServers": {
+ *     "kntor-erp": {
+ *       "command": "npx",
+ *       "args": ["-y", "kntor-mcp"],
+ *       "env": {
+ *         "KNTOR_API_KEY": "kntor_your_api_key_here"
+ *       }
+ *     }
+ *   }
+ * }
+ */
+
+const SERVER_URL = process.env.KNTOR_MCP_URL || 'https://mcp.kntor.io/mcp';
+const API_KEY = process.env.KNTOR_API_KEY;
+
+// Validate API key
+if (!API_KEY) {
+  const error = {
+    jsonrpc: '2.0',
+    id: null,
+    error: {
+      code: -32600,
+      message: 'KNTOR_API_KEY environment variable is required. Get your API key at https://kntor.io/settings/mcp'
+    }
+  };
+  console.log(JSON.stringify(error));
+  process.exit(1);
+}
+
+if (!API_KEY.startsWith('kntor_')) {
+  const error = {
+    jsonrpc: '2.0',
+    id: null,
+    error: {
+      code: -32600,
+      message: 'Invalid API key format. Key should start with "kntor_"'
+    }
+  };
+  console.log(JSON.stringify(error));
+  process.exit(1);
+}
+
+// Buffer for incomplete JSON messages
+let buffer = '';
+
+// Process stdin data
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', async (chunk) => {
+  buffer += chunk;
+
+  // Process complete lines
+  const lines = buffer.split('\n');
+  buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+
+    try {
+      const message = JSON.parse(line);
+      await handleMessage(message);
+    } catch (parseError) {
+      // Log parse errors to stderr (won't interfere with protocol)
+      console.error('[kntor-mcp] Parse error:', parseError.message);
+    }
+  }
+});
+
+// Handle a single MCP message
+async function handleMessage(message) {
+  // Preserve the request id (use 0 as fallback, not null - Claude Desktop requires string/number)
+  const requestId = message.id !== undefined ? message.id : 0;
+
+  try {
+    console.error(`[kntor-mcp] Sending: ${message.method}`);
+
+    const response = await fetch(SERVER_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': API_KEY
+      },
+      body: JSON.stringify(message)
+    });
+
+    const responseText = await response.text();
+    console.error(`[kntor-mcp] Response (${response.status}): ${responseText.substring(0, 200)}`);
+
+    if (!response.ok) {
+      let errorData;
+      try {
+        errorData = JSON.parse(responseText);
+      } catch {
+        errorData = { message: responseText };
+      }
+
+      const errorResponse = {
+        jsonrpc: '2.0',
+        id: requestId,
+        error: {
+          code: -32000,
+          message: `Server error (${response.status}): ${errorData.error?.message || errorData.message || responseText}`
+        }
+      };
+      console.log(JSON.stringify(errorResponse));
+      return;
+    }
+
+    let result;
+    try {
+      result = JSON.parse(responseText);
+    } catch {
+      const errorResponse = {
+        jsonrpc: '2.0',
+        id: requestId,
+        error: {
+          code: -32603,
+          message: `Invalid JSON response: ${responseText.substring(0, 100)}`
+        }
+      };
+      console.log(JSON.stringify(errorResponse));
+      return;
+    }
+
+    // Ensure the response has the correct id
+    if (result.id === null || result.id === undefined) {
+      result.id = requestId;
+    }
+
+    console.log(JSON.stringify(result));
+
+  } catch (networkError) {
+    console.error(`[kntor-mcp] Network error: ${networkError.message}`);
+    const errorResponse = {
+      jsonrpc: '2.0',
+      id: requestId,
+      error: {
+        code: -32603,
+        message: `Network error: ${networkError.message}`
+      }
+    };
+    console.log(JSON.stringify(errorResponse));
+  }
+}
+
+// Handle stdin close
+process.stdin.on('end', () => {
+  process.exit(0);
+});
+
+// Handle process signals
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+
+// Keep process alive
+process.stdin.resume();
+
+// Log startup to stderr (doesn't interfere with protocol)
+console.error('[kntor-mcp] Connected to Kntor.io ERP');

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "kntor-mcp",
+  "version": "1.0.0",
+  "description": "MCP client for Kntor.io ERP - Connect AI agents to your business management system",
+  "type": "module",
+  "bin": {
+    "kntor-mcp": "./bin/kntor-mcp.mjs"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "kntor",
+    "healthcare",
+    "erp",
+    "ai",
+    "claude"
+  ],
+  "author": "Kntor.io",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/edgargomero/kntor-mcp-server"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241127.0",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "typescript": "^5.8.3",
+    "wrangler": "^4.59.2",
+    "zod": "^3.22.4"
+  }
+}