@vantageos/vantage-crm-mcp 0.1.0

package/README.md

@@ -0,0 +1,260 @@
+# VantageCRM MCP Server
+
+Model Context Protocol server for VantageCRM — 60 tools across 10 categories exposing the full CRM backend to AI agents.
+
+## Transports
+
+### stdio (local / Claude Desktop)
+
+Runs as a subprocess. Full tool access, no scope filtering (trusted local user).
+
+```bash
+CONVEX_URL=https://your-deployment.convex.cloud node dist/server.js
+# or explicitly:
+CONVEX_URL=https://... node dist/server.js --mode stdio
+```
+
+Claude Desktop `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vantageCRM": {
+      "command": "node",
+      "args": ["/path/to/vantageos-crm/mcp-server/dist/server.js"],
+      "env": {
+        "CONVEX_URL": "https://your-deployment.convex.cloud"
+      }
+    }
+  }
+}
+```
+
+### HTTP (multi-tenant / Railway)
+
+Runs as an HTTP server. OAuth Bearer tokens required. Tools filtered by token scope.
+
+```bash
+CONVEX_URL=https://your-deployment.convex.cloud \
+VANTAGE_MCP_MODE=http \
+PORT=3001 \
+node dist/server.js --mode http
+```
+
+Endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Liveness probe |
+| GET | `/mcp/tools` | List tools visible to token |
+| POST | `/mcp/call` | Call a tool |
+
+Request format:
+
+```http
+POST /mcp/call
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "tool": "create_contact",
+  "args": { "workspaceId": "ws_xxx", "firstName": "Jane", "lastName": "Doe" }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CONVEX_URL` | Yes | Convex deployment URL |
+| `VANTAGE_MCP_MODE` | No | `stdio` (default) or `http` |
+| `PORT` | No | HTTP port (default: 3001) |
+
+## Tool Catalog
+
+### Contacts (8 tools)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `create_contact` | write | Create a CRM contact |
+| `get_contact` | read | Retrieve contact by ID |
+| `update_contact` | write | Update contact fields |
+| `list_contacts` | read | List by workspace/type |
+| `search_contacts` | read | Full-text search |
+| `delete_contact` | write | Soft delete (30-day grace) |
+| `list_contacts_by_custom_field` | read | Filter by custom field value |
+| `restore_contact` | write | Restore soft-deleted contact |
+
+### Companies (6 tools)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `create_company` | write | Create company record |
+| `get_company` | read | Retrieve by ID |
+| `update_company` | write | Update fields |
+| `list_companies` | read | List by workspace/industry |
+| `search_companies` | read | Full-text search |
+| `delete_company` | write | Soft delete |
+
+### Deals (8 tools)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `create_deal` | write | Create deal in pipeline |
+| `get_deal` | read | Retrieve by ID |
+| `update_deal` | write | Update fields |
+| `list_deals` | read | List by workspace/stage/contact |
+| `search_deals` | read | Search by title |
+| `delete_deal` | write | Soft delete |
+| `move_deal_stage` | write | Move stage with optional probability override |
+| `forecast_pipeline` | read | Weighted pipeline value (Σ value × probability) |
+
+### Activities (5 tools — no delete per OQ-4)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `create_activity` | write | Create activity (call/email/meeting/note/task) |
+| `get_activity` | read | Retrieve by ID |
+| `update_activity` | write | Update mutable fields (description, dueAt, completedAt) |
+| `list_activities` | read | List by workspace/contact/deal |
+| `list_activities_by_type` | read | Filter by type with time range |
+
+Activities are immutable audit trail — subject and type cannot be changed after creation.
+
+### Custom Fields (5 tools)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `add_custom_field` | write | Define custom field for entity type |
+| `update_custom_field_definition` | write | Update label/options/validation |
+| `list_custom_fields` | read | List definitions by workspace |
+| `set_custom_field_value` | write | Set value on an entity |
+| `delete_custom_field` | admin | Delete definition (irreversible) |
+
+### Custom Objects (7 tools)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `add_custom_object` | admin | DDL: define new object type |
+| `list_custom_objects` | read | List object type definitions |
+| `create_record` | write | Create a custom object record |
+| `update_record` | write | Update record fields |
+| `delete_record` | write | Soft delete record |
+| `list_records` | read | List records by type |
+| `search_records` | read | Search records by field values |
+
+### Workflows (7 tools)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `create_workflow` | write | Create automation workflow |
+| `update_workflow` | write | Update workflow config |
+| `list_workflows` | read | List by workspace |
+| `pause_workflow` | write | Pause (disable) workflow |
+| `resume_workflow` | write | Resume (enable) workflow |
+| `list_executions` | read | List workflow execution history |
+| `replay_execution` | workflow-trigger | Re-run a failed execution |
+
+### Search / Analytics (4 tools)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `pipeline_value` | read | Weighted pipeline Σ value × probability |
+| `win_rate` | read | Deals won / total closed in period |
+| `conversion_rate` | read | Stage conversion rate |
+| `activity_summary` | read | Activity counts grouped by type |
+
+### Admin (5 tools)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `list_audit_log` | admin | Query audit event log |
+| `get_entity_history` | admin | Change history for an entity |
+| `get_actor_history` | admin | All actions by a user |
+| `purge_archived_records` | admin | Hard delete archived records (30+ days) |
+| `list_workspace_limits` | admin | Workspace plan limits |
+
+### RBAC (5 tools)
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `list_workspace_members` | read | List workspace members and roles |
+| `add_workspace_member` | admin | Add member with role |
+| `update_member_role` | admin | Change member role |
+| `remove_workspace_member` | admin | Remove member from workspace |
+| `update_member_permissions` | admin | Fine-grained permission overrides |
+
+## Scope Tier Matrix
+
+```
+cloud-admin  ──── satisfies all scopes
+    │
+   admin  ──────── satisfies read + write
+    │
+   write  ──────── satisfies read
+    │
+   read   ──────── base tier
+    
+workflow-trigger ── lateral tier (peer of write, different domain)
+```
+
+Token scopes are extracted from the Bearer token via `validateToken` Convex query. In stdio mode, all tools are always accessible.
+
+## Response Envelope
+
+All tool responses use the same envelope:
+
+```typescript
+// Success
+{ success: true, data: <result> }
+
+// Failure
+{ success: false, error: { code: string, message: string } }
+```
+
+Common error codes: `CONVEX_ERROR`, `SCOPE_ERROR`, `ZOD_VALIDATION_ERROR`, `NOT_IMPLEMENTED`.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Type check
+npx tsc --noEmit --skipLibCheck
+
+# Run in stdio mode (local dev)
+CONVEX_URL=https://... npx tsx mcp-server/server.ts
+```
+
+## Architecture
+
+```
+mcp-server/
+├── server.ts              # Entry point — mode detection
+├── registry.ts            # All 60 tools + handler map
+├── lib/
+│   ├── convexClient.ts    # ConvexHttpClient wrapper + ToolResult envelope
+│   └── scopeEnforcement.ts # 4-tier scope hierarchy
+├── transport/
+│   ├── stdio.ts           # MCP SDK stdio transport
+│   └── http.ts            # HTTP transport with OAuth
+├── tools/
+│   ├── contacts.ts        # 8 tools
+│   ├── companies.ts       # 6 tools
+│   ├── deals.ts           # 8 tools
+│   ├── activities.ts      # 5 tools
+│   ├── customFields.ts    # 5 tools
+│   ├── customObjects.ts   # 7 tools
+│   ├── workflows.ts       # 7 tools
+│   ├── search.ts          # 4 tools
+│   ├── admin.ts           # 5 tools
+│   └── rbac.ts            # 5 tools
+└── tests/
+    ├── tools.test.ts          # Zod validation + envelope per category
+    ├── scopeEnforcement.test.ts # Scope hierarchy coverage
+    └── registry.test.ts       # 60-tool count + integrity checks
+```

package/dist/convex/crm/_helpers.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * CRM Shared Helpers
+ *
+ * Search text builders for contacts, companies, and deals.
+ * Used by create/update mutations to populate searchableText fields.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildContactSearchText = buildContactSearchText;
+exports.buildCompanySearchText = buildCompanySearchText;
+exports.buildDealSearchText = buildDealSearchText;
+function buildContactSearchText(contact, companyName) {
+    return [contact.firstName, contact.lastName, contact.email, companyName]
+        .filter(Boolean)
+        .join(' ');
+}
+function buildCompanySearchText(company) {
+    return [company.name, company.domain, company.industry]
+        .filter(Boolean)
+        .join(' ');
+}
+function buildDealSearchText(deal, companyName, contactName) {
+    return [deal.title, companyName, contactName].filter(Boolean).join(' ');
+}

package/dist/convex/crm/activities.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * convex/crm/activities.ts
+ *
+ * V0.1.0 — Extended from T3 stub.
+ * Functions: createActivity, updateActivity, getActivity, listActivities.
+ * NO archive, NO delete — OQ-4 audit trail doctrine (Salesforce-grade).
+ * OQ-1: actorType includes 'agent:composio' via actorId override.
+ * Every create/update mutation creates audit_log entry.
+ *
+ * Ref: vantage-crm-spec-2026-05-20.md §2 + §5 OQ-1/OQ-4
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.update = exports.updateActivity = exports.list = exports.listActivities = exports.get = exports.getActivity = exports.create = exports.createActivity = void 0;
+const server_1 = require("../_generated/server");
+const values_1 = require("convex/values");
+const workspace_1 = require("../lib/workspace");
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+const activityTypeValidator = values_1.v.union(values_1.v.literal('call'), values_1.v.literal('email'), values_1.v.literal('meeting'), values_1.v.literal('note'), values_1.v.literal('task'), values_1.v.literal('stage-change'), values_1.v.literal('email-received'), values_1.v.literal('email-sent'), values_1.v.literal('calendar-event'), values_1.v.literal('workflow-action'));
+// ---------------------------------------------------------------------------
+// createActivity
+// ---------------------------------------------------------------------------
+exports.createActivity = (0, server_1.mutation)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        type: activityTypeValidator,
+        subject: values_1.v.string(),
+        description: values_1.v.optional(values_1.v.string()),
+        contactId: values_1.v.optional(values_1.v.id('contacts')),
+        companyId: values_1.v.optional(values_1.v.id('companies')),
+        dealId: values_1.v.optional(values_1.v.id('deals')),
+        dueAt: values_1.v.optional(values_1.v.number()),
+        occurredAt: values_1.v.optional(values_1.v.number()),
+        // OQ-1: actor tracking — 'agent:composio' supported via actorId
+        actorType: values_1.v.optional(values_1.v.union(values_1.v.literal('user'), values_1.v.literal('agent'), values_1.v.literal('system'))),
+        actorId: values_1.v.optional(values_1.v.string()), // clerkId | 'agent:composio' | 'system'
+        customFields: values_1.v.optional(values_1.v.record(values_1.v.string(), values_1.v.any())),
+    },
+    returns: values_1.v.id('activities'),
+    handler: async (ctx, args) => {
+        // Build actor — if actorId='agent:composio', auditActorType='agent'
+        const { clerkId, canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, args.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        // Normalize actorType for schema (schema accepts 'user'|'agent'|'system')
+        // 'agent:composio' collapses to 'agent' in the activities table
+        const schemaActorType = args.actorId === 'agent:composio'
+            ? 'agent'
+            : args.actorType ?? 'user';
+        const now = Date.now();
+        const activityId = await ctx.db.insert('activities', {
+            type: args.type,
+            subject: args.subject,
+            description: args.description,
+            contactId: args.contactId,
+            companyId: args.companyId,
+            dealId: args.dealId,
+            dueAt: args.dueAt,
+            occurredAt: args.occurredAt ?? now,
+            ownerId: clerkId,
+            workspaceId: args.workspaceId,
+            actorType: schemaActorType,
+            actorId: actor.actorId,
+            customFields: args.customFields,
+            createdAt: now,
+            updatedAt: now,
+        });
+        // Update lastActivityAt on the deal if linked
+        if (args.dealId) {
+            await ctx.db.patch(args.dealId, { lastActivityAt: now, updatedAt: now });
+        }
+        // Update lastContactedAt on the contact if linked (non-task/note only)
+        if (args.contactId && args.type !== 'task' && args.type !== 'note') {
+            await ctx.db.patch(args.contactId, { lastContactedAt: now, updatedAt: now });
+        }
+        // Audit log — note activities themselves ARE the audit trail,
+        // but we also log the mutation for compliance completeness.
+        await ctx.db.insert('audit_log', {
+            workspaceId: args.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'activity',
+            entityId: activityId,
+            action: 'create',
+            timestamp: Date.now(),
+        });
+        return activityId;
+    },
+});
+// Backward-compatible alias
+exports.create = exports.createActivity;
+// ---------------------------------------------------------------------------
+// getActivity / get
+// ---------------------------------------------------------------------------
+exports.getActivity = (0, server_1.query)({
+    args: {
+        activityId: values_1.v.id('activities'),
+    },
+    returns: values_1.v.union(values_1.v.null(), values_1.v.any()),
+    handler: async (ctx, args) => {
+        const activity = await ctx.db.get(args.activityId);
+        if (!activity)
+            return null;
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, activity.workspaceId);
+        return activity;
+    },
+});
+exports.get = exports.getActivity;
+// ---------------------------------------------------------------------------
+// listActivities / list
+// ---------------------------------------------------------------------------
+exports.listActivities = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        contactId: values_1.v.optional(values_1.v.id('contacts')),
+        companyId: values_1.v.optional(values_1.v.id('companies')),
+        dealId: values_1.v.optional(values_1.v.id('deals')),
+        type: values_1.v.optional(activityTypeValidator),
+        limit: values_1.v.optional(values_1.v.number()),
+    },
+    returns: values_1.v.array(values_1.v.any()),
+    handler: async (ctx, args) => {
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        const limit = args.limit ?? 20;
+        let activities;
+        if (args.dealId) {
+            const deal = await ctx.db.get(args.dealId);
+            if (!deal || deal.workspaceId !== args.workspaceId)
+                return [];
+            activities = await ctx.db
+                .query('activities')
+                .withIndex('by_deal', (q) => q.eq('dealId', args.dealId))
+                .order('desc')
+                .take(limit + 1);
+        }
+        else if (args.contactId) {
+            const contact = await ctx.db.get(args.contactId);
+            if (!contact || contact.workspaceId !== args.workspaceId)
+                return [];
+            activities = await ctx.db
+                .query('activities')
+                .withIndex('by_contact', (q) => q.eq('contactId', args.contactId))
+                .order('desc')
+                .take(limit + 1);
+        }
+        else if (args.companyId) {
+            const company = await ctx.db.get(args.companyId);
+            if (!company || company.workspaceId !== args.workspaceId)
+                return [];
+            activities = await ctx.db
+                .query('activities')
+                .withIndex('by_company', (q) => q.eq('companyId', args.companyId))
+                .order('desc')
+                .take(limit + 1);
+        }
+        else if (args.type) {
+            activities = await ctx.db
+                .query('activities')
+                .withIndex('by_workspace_type', (q) => q.eq('workspaceId', args.workspaceId).eq('type', args.type))
+                .order('desc')
+                .take(limit + 1);
+        }
+        else {
+            activities = await ctx.db
+                .query('activities')
+                .withIndex('by_workspace', (q) => q.eq('workspaceId', args.workspaceId))
+                .order('desc')
+                .take(limit + 1);
+        }
+        return activities.slice(0, limit);
+    },
+});
+exports.list = exports.listActivities;
+// ---------------------------------------------------------------------------
+// updateActivity — intentionally limited (OQ-4 audit trail integrity)
+// Only description + dueAt + completedAt + customFields may be updated.
+// subject, type, occurredAt, links (contactId/dealId/companyId) are immutable.
+// ---------------------------------------------------------------------------
+exports.updateActivity = (0, server_1.mutation)({
+    args: {
+        activityId: values_1.v.id('activities'),
+        description: values_1.v.optional(values_1.v.string()),
+        dueAt: values_1.v.optional(values_1.v.number()),
+        completedAt: values_1.v.optional(values_1.v.number()),
+        customFields: values_1.v.optional(values_1.v.record(values_1.v.string(), values_1.v.any())),
+        actorId: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('activities'),
+    handler: async (ctx, args) => {
+        const activity = await ctx.db.get(args.activityId);
+        if (!activity)
+            throw new Error('Activity not found');
+        const { canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, activity.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        const { activityId, actorId: _actorId, ...updates } = args;
+        await ctx.db.patch(activityId, {
+            ...updates,
+            updatedAt: Date.now(),
+        });
+        await ctx.db.insert('audit_log', {
+            workspaceId: activity.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'activity',
+            entityId: activityId,
+            action: 'update',
+            timestamp: Date.now(),
+        });
+        return activityId;
+    },
+});
+exports.update = exports.updateActivity;
+// ---------------------------------------------------------------------------
+// NO remove/delete mutation.
+// Activities are the immutable audit trail. OQ-4 / Salesforce doctrine.
+// This comment is intentional — do not add a remove mutation here.
+// ---------------------------------------------------------------------------