@vantageos/vantage-crm-mcp 0.1.0

package/dist/mcp-server/transport/http.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * VantageCRM MCP — HTTP Transport (Cloud Railway)
+ *
+ * OAuth Bearer token authentication via validateAccessToken (convex/lib/oauth.ts).
+ * Scopes extracted from token → filter visible tools + enforce per-call.
+ *
+ * Endpoints:
+ *   GET  /mcp/tools        — list tools visible to this token's scopes
+ *   POST /mcp/call         — call a tool (scope enforced)
+ *   GET  /health           — liveness probe
+ *
+ * Environment variables:
+ *   PORT                  — HTTP port (default 3001)
+ *   CONVEX_URL            — Convex deployment URL
+ *   VANTAGE_MCP_MODE      — set to 'http' to enable this transport
+ *
+ * Auth header: Authorization: Bearer <access_token>
+ * Token validation is proxied to Convex via the validateToken action.
+ *
+ * Ref: spec §3.1, convex/lib/oauth.ts
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startHttpServer = startHttpServer;
+const http = __importStar(require("http"));
+const browser_1 = require("convex/browser");
+const registry_1 = require("../registry");
+const scopeEnforcement_1 = require("../lib/scopeEnforcement");
+const server_1 = require("convex/server");
+// ---------------------------------------------------------------------------
+// Multi-tenant workspace isolation helper (BL-1)
+// ---------------------------------------------------------------------------
+/**
+ * Cross-check that the token's bound workspaceId matches any workspaceId
+ * supplied in the tool args. Prevents IDOR cross-tenant access where a
+ * caller holds a valid token for workspace A but passes workspace B's ID.
+ *
+ * Must be called before every tool dispatch in HTTP transport.
+ */
+function requireWorkspaceMatchesToken(tokenContext, args) {
+    const tokenWorkspaceId = tokenContext.workspaceId ?? tokenContext.orgId;
+    const argsWorkspaceId = args['workspaceId'];
+    if (argsWorkspaceId !== undefined &&
+        argsWorkspaceId !== null &&
+        tokenWorkspaceId !== null &&
+        argsWorkspaceId !== tokenWorkspaceId) {
+        throw new WorkspaceMismatchError(`Token workspace (${tokenWorkspaceId}) does not match args.workspaceId (${String(argsWorkspaceId)}). Cross-tenant access denied.`);
+    }
+}
+class WorkspaceMismatchError extends Error {
+    code = 'FORBIDDEN_WORKSPACE_MISMATCH';
+    constructor(message) {
+        super(message);
+        this.name = 'WorkspaceMismatchError';
+    }
+}
+async function validateBearerToken(authHeader) {
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        throw new Error('Missing or malformed Authorization header. Expected: Bearer <token>');
+    }
+    const rawToken = authHeader.slice('Bearer '.length).trim();
+    if (!rawToken) {
+        throw new Error('Empty Bearer token');
+    }
+    const convexUrl = process.env.CONVEX_URL;
+    if (!convexUrl) {
+        throw new Error('CONVEX_URL not configured');
+    }
+    const client = new browser_1.ConvexHttpClient(convexUrl);
+    // Use the Convex validateToken query that wraps oauth.ts validateAccessToken.
+    // anyApi is used since oauthActions.ts is new and not in generated API yet.
+    const result = await client.query(server_1.anyApi.lib.oauthActions.validateToken, { rawToken }).catch(() => null);
+    if (!result) {
+        throw new Error('Invalid, expired, or revoked access token');
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Request helpers
+// ---------------------------------------------------------------------------
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.on('data', (chunk) => { body += chunk.toString(); });
+        req.on('end', () => resolve(body));
+        req.on('error', reject);
+    });
+}
+function sendJson(res, status, data) {
+    const body = JSON.stringify(data);
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+    });
+    res.end(body);
+}
+// ---------------------------------------------------------------------------
+// HTTP server
+// ---------------------------------------------------------------------------
+async function startHttpServer() {
+    const port = parseInt(process.env.PORT ?? '3001', 10);
+    const server = http.createServer(async (req, res) => {
+        // CORS headers
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Health probe — no auth required
+        if (req.url === '/health' && req.method === 'GET') {
+            sendJson(res, 200, { status: 'ok', tools: registry_1.ALL_TOOL_DEFINITIONS.length, version: '0.1.0' });
+            return;
+        }
+        // All other endpoints require auth
+        let token;
+        try {
+            token = await validateBearerToken(req.headers.authorization);
+        }
+        catch (err) {
+            sendJson(res, 401, {
+                error: 'UNAUTHORIZED',
+                message: err instanceof Error ? err.message : 'Authentication failed',
+            });
+            return;
+        }
+        // GET /mcp/tools — list tools visible for this token's scopes
+        if (req.url === '/mcp/tools' && req.method === 'GET') {
+            const visible = (0, scopeEnforcement_1.filterToolsByScope)(registry_1.ALL_TOOL_DEFINITIONS, token.scopes);
+            sendJson(res, 200, {
+                tools: visible.map((def) => ({
+                    name: def.name,
+                    description: def.description,
+                    requiredScope: def.requiredScope,
+                    inputSchema: def.inputSchema,
+                })),
+                totalVisible: visible.length,
+                totalAvailable: registry_1.ALL_TOOL_DEFINITIONS.length,
+                scopes: token.scopes,
+            });
+            return;
+        }
+        // POST /mcp/call — call a tool
+        if (req.url === '/mcp/call' && req.method === 'POST') {
+            let body;
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                sendJson(res, 400, { error: 'INVALID_JSON', message: 'Request body must be valid JSON' });
+                return;
+            }
+            const toolName = body.tool;
+            if (!toolName || typeof toolName !== 'string') {
+                sendJson(res, 400, { error: 'MISSING_TOOL', message: 'Request body must include "tool" field' });
+                return;
+            }
+            const toolDef = registry_1.ALL_TOOL_DEFINITIONS.find((d) => d.name === toolName);
+            if (!toolDef) {
+                sendJson(res, 404, { error: 'TOOL_NOT_FOUND', message: `Unknown tool: ${toolName}` });
+                return;
+            }
+            // Scope enforcement
+            try {
+                (0, scopeEnforcement_1.requireScope)(token.scopes, toolDef.requiredScope, toolName);
+            }
+            catch (err) {
+                if (err instanceof scopeEnforcement_1.ScopeError) {
+                    sendJson(res, 403, {
+                        error: 'INSUFFICIENT_SCOPE',
+                        message: err.message,
+                        required: err.required,
+                        provided: err.provided,
+                    });
+                    return;
+                }
+                throw err;
+            }
+            const handler = registry_1.TOOL_HANDLERS[toolName];
+            if (!handler) {
+                sendJson(res, 500, { error: 'HANDLER_MISSING', message: `No handler for tool: ${toolName}` });
+                return;
+            }
+            // BL-1: Multi-tenant workspace isolation — cross-check token vs args before dispatch
+            const rawArgs = (body.arguments ?? {});
+            try {
+                requireWorkspaceMatchesToken(token, rawArgs);
+            }
+            catch (err) {
+                if (err instanceof WorkspaceMismatchError) {
+                    sendJson(res, 403, {
+                        success: false,
+                        error: {
+                            code: err.code,
+                            message: err.message,
+                        },
+                    });
+                    return;
+                }
+                throw err;
+            }
+            try {
+                const result = await handler(rawArgs);
+                sendJson(res, 200, result);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                sendJson(res, 500, { error: 'HANDLER_ERROR', message });
+            }
+            return;
+        }
+        // 404 for unknown routes
+        sendJson(res, 404, { error: 'NOT_FOUND', message: `${req.method} ${req.url} not found` });
+    });
+    await new Promise((resolve, reject) => {
+        server.on('error', reject);
+        server.listen(port, () => {
+            process.stderr.write(`[VantageCRM MCP] HTTP server started on port ${port} — 60 tools, OAuth Bearer\n`);
+            resolve();
+        });
+    });
+}

package/dist/mcp-server/transport/stdio.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * VantageCRM MCP — Stdio Transport (self-host CLI)
+ *
+ * Used when mode=stdio (default for local/self-hosted deployments).
+ * Full local access — no OAuth token, no scope filtering.
+ * Trust model: user runs the CLI on their own machine/server.
+ *
+ * Usage: node mcp-server/server.js --mode stdio
+ *   or:  VANTAGE_MCP_MODE=stdio node mcp-server/server.js
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startStdioServer = startStdioServer;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const registry_1 = require("../registry");
+async function startStdioServer() {
+    const server = new index_js_1.Server({
+        name: 'vantageos-crm',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // ListTools — return all 60 tools (stdio = full access, no scope filter)
+    // ---------------------------------------------------------------------------
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+        return {
+            tools: registry_1.ALL_TOOL_DEFINITIONS.map((def) => ({
+                name: def.name,
+                description: def.description,
+                inputSchema: def.inputSchema,
+            })),
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // CallTool — dispatch to handler, wrap in envelope
+    // ---------------------------------------------------------------------------
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const handler = registry_1.TOOL_HANDLERS[name];
+        if (!handler) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: { code: 'TOOL_NOT_FOUND', message: `Unknown tool: ${name}` },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const result = await handler(args ?? {});
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: { code: 'HANDLER_ERROR', message },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    // Signal ready on stderr (not stdout — stdout is used for MCP protocol)
+    process.stderr.write('[VantageCRM MCP] stdio server started — 60 tools available\n');
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@vantageos/vantage-crm-mcp",
+  "version": "0.1.0",
+  "description": "VantageCRM MCP Server — agents-first CRM over Model Context Protocol",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "main": "dist/server.js",
+  "bin": {
+    "vantage-crm-mcp": "dist/server.js"
+  },
+  "types": "dist/server.d.ts",
+  "files": [
+    "dist/",
+    "README.md",
+    "../../LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "mcp",
+    "crm",
+    "model-context-protocol",
+    "vantageos",
+    "agents"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "convex": "^1.29.3",
+    "zod": "^4.3.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elpiarthera/vantageos-crm.git"
+  },
+  "homepage": "https://github.com/elpiarthera/vantageos-crm/tree/main/mcp-server#readme"
+}