@vantageos/vantage-crm-mcp 0.1.0

package/dist/mcp-server/tools/activities.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * VantageCRM MCP — Activities tools (5 tools)
+ *
+ * Tools: create_activity, get_activity, update_activity,
+ *        list_activities, list_activities_by_type
+ *
+ * Note: NO delete_activity — activities are immutable audit trail (OQ-4).
+ * Scope: read for queries, write for mutations
+ * Ref: spec §3.5
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVITY_TOOLS = void 0;
+exports.create_activity = create_activity;
+exports.get_activity = get_activity;
+exports.update_activity = update_activity;
+exports.list_activities = list_activities;
+exports.list_activities_by_type = list_activities_by_type;
+const zod_1 = require("zod");
+const api_1 = require("../../convex/_generated/api");
+const convexClient_1 = require("../lib/convexClient");
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+const ACTIVITY_TYPES = ['call', 'email', 'meeting', 'note', 'task'];
+const CreateActivitySchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    type: zod_1.z.enum(ACTIVITY_TYPES),
+    subject: zod_1.z.string().min(1).max(500),
+    description: zod_1.z.string().max(10000).optional(),
+    contactId: zod_1.z.string().optional(),
+    dealId: zod_1.z.string().optional(),
+    companyId: zod_1.z.string().optional(),
+    occurredAt: zod_1.z.number().optional(),
+    dueAt: zod_1.z.number().optional(),
+    customFields: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+const GetActivitySchema = zod_1.z.object({
+    activityId: zod_1.z.string().min(1),
+});
+const UpdateActivitySchema = zod_1.z.object({
+    activityId: zod_1.z.string().min(1),
+    description: zod_1.z.string().max(10000).optional(),
+    dueAt: zod_1.z.number().optional(),
+    completedAt: zod_1.z.number().optional(),
+    customFields: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+const ListActivitiesSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    contactId: zod_1.z.string().optional(),
+    dealId: zod_1.z.string().optional(),
+    companyId: zod_1.z.string().optional(),
+    limit: zod_1.z.number().int().min(1).max(100).default(20),
+});
+const ListActivitiesByTypeSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    type: zod_1.z.enum(ACTIVITY_TYPES),
+    since: zod_1.z.number().optional(),
+    until: zod_1.z.number().optional(),
+    limit: zod_1.z.number().int().min(1).max(100).default(20),
+});
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+async function create_activity(rawArgs) {
+    const args = CreateActivitySchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => (0, convexClient_1.getConvexClient)().mutation(api_1.api.crm.activities.create, {
+        workspaceId: args.workspaceId,
+        type: args.type,
+        subject: args.subject,
+        description: args.description,
+        contactId: args.contactId,
+        dealId: args.dealId,
+        companyId: args.companyId,
+        occurredAt: args.occurredAt,
+        dueAt: args.dueAt,
+        customFields: args.customFields,
+    }));
+}
+async function get_activity(rawArgs) {
+    const args = GetActivitySchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => (0, convexClient_1.getConvexClient)().query(api_1.api.crm.activities.get, {
+        activityId: args.activityId,
+    }));
+}
+async function update_activity(rawArgs) {
+    const args = UpdateActivitySchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => (0, convexClient_1.getConvexClient)().mutation(api_1.api.crm.activities.update, {
+        activityId: args.activityId,
+        description: args.description,
+        dueAt: args.dueAt,
+        completedAt: args.completedAt,
+        customFields: args.customFields,
+    }));
+}
+async function list_activities(rawArgs) {
+    const args = ListActivitiesSchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => (0, convexClient_1.getConvexClient)().query(api_1.api.crm.activities.list, {
+        workspaceId: args.workspaceId,
+        contactId: args.contactId,
+        dealId: args.dealId,
+        companyId: args.companyId,
+        limit: args.limit,
+    }));
+}
+async function list_activities_by_type(rawArgs) {
+    const args = ListActivitiesByTypeSchema.parse(rawArgs);
+    // listByType is a client-side filter on top of list (Convex layer has list with type filter)
+    return (0, convexClient_1.withEnvelope)(async () => {
+        const all = await (0, convexClient_1.getConvexClient)().query(api_1.api.crm.activities.list, {
+            workspaceId: args.workspaceId,
+            limit: 200,
+        });
+        let results = all.filter((a) => a['type'] === args.type);
+        if (args.since !== undefined) {
+            results = results.filter((a) => a['occurredAt'] >= args.since);
+        }
+        if (args.until !== undefined) {
+            results = results.filter((a) => a['occurredAt'] <= args.until);
+        }
+        return results.slice(0, args.limit);
+    });
+}
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+exports.ACTIVITY_TOOLS = [
+    {
+        name: 'create_activity',
+        description: 'Create a CRM activity (call/email/meeting/note/task). Activities are immutable audit trail (OQ-4) — no delete.',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                type: { type: 'string', enum: ['call', 'email', 'meeting', 'note', 'task'] },
+                subject: { type: 'string' },
+                description: { type: 'string' },
+                contactId: { type: 'string' },
+                dealId: { type: 'string' },
+                companyId: { type: 'string' },
+                occurredAt: { type: 'number' },
+                dueAt: { type: 'number' },
+                customFields: { type: 'object' },
+            },
+            required: ['workspaceId', 'type', 'subject'],
+        },
+    },
+    {
+        name: 'get_activity',
+        description: 'Retrieve an activity by ID',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: { activityId: { type: 'string' } },
+            required: ['activityId'],
+        },
+    },
+    {
+        name: 'update_activity',
+        description: 'Update mutable activity fields (description, dueAt, completedAt, customFields). Subject and type are immutable per OQ-4.',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                activityId: { type: 'string' },
+                description: { type: 'string' },
+                dueAt: { type: 'number' },
+                completedAt: { type: 'number' },
+                customFields: { type: 'object' },
+            },
+            required: ['activityId'],
+        },
+    },
+    {
+        name: 'list_activities',
+        description: 'List activities by workspace/contact/deal/company',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                contactId: { type: 'string' },
+                dealId: { type: 'string' },
+                companyId: { type: 'string' },
+                limit: { type: 'number' },
+            },
+            required: ['workspaceId'],
+        },
+    },
+    {
+        name: 'list_activities_by_type',
+        description: 'Filter activities by type and optional time range',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                type: { type: 'string', enum: ['call', 'email', 'meeting', 'note', 'task'] },
+                since: { type: 'number', description: 'Unix ms timestamp' },
+                until: { type: 'number', description: 'Unix ms timestamp' },
+                limit: { type: 'number' },
+            },
+            required: ['workspaceId', 'type'],
+        },
+    },
+];

package/dist/mcp-server/tools/admin.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * VantageCRM MCP — Admin tools (5 tools)
+ *
+ * Tools: list_audit_log, get_entity_history, get_actor_history,
+ *        purge_archived_records, list_workspace_limits
+ *
+ * All admin tools require scope: admin
+ * Ref: spec §3.10
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADMIN_TOOLS = void 0;
+exports.list_audit_log = list_audit_log;
+exports.get_entity_history = get_entity_history;
+exports.get_actor_history = get_actor_history;
+exports.purge_archived_records = purge_archived_records;
+exports.list_workspace_limits = list_workspace_limits;
+const zod_1 = require("zod");
+const server_1 = require("convex/server");
+const api_1 = require("../../convex/_generated/api");
+const convexClient_1 = require("../lib/convexClient");
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+const ListAuditLogSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    entityType: zod_1.z.string().optional(),
+    actorId: zod_1.z.string().optional(),
+    since: zod_1.z.number().optional(),
+    until: zod_1.z.number().optional(),
+    limit: zod_1.z.number().int().min(1).max(200).default(50),
+});
+const GetEntityHistorySchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    entityType: zod_1.z.string().min(1),
+    entityId: zod_1.z.string().min(1),
+});
+const GetActorHistorySchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    actorId: zod_1.z.string().min(1),
+    since: zod_1.z.number().optional(),
+    until: zod_1.z.number().optional(),
+    limit: zod_1.z.number().int().min(1).max(200).default(50),
+});
+const PurgeArchivedSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    entityType: zod_1.z.enum(['contact', 'company', 'deal', 'custom_object_record']),
+    olderThanDays: zod_1.z.number().int().min(30).default(30),
+});
+const ListWorkspaceLimitsSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Query audit_log table via Convex HTTP — uses deals.summary as a proxy
+ *  until a dedicated audit log query is exposed in V0.1.x.
+ *  Returns stub data with clear attribution until Convex layer ships.
+ */
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+async function list_audit_log(rawArgs) {
+    ListAuditLogSchema.parse(rawArgs);
+    // Convex layer V0.1.0 does not expose an audit log query via HTTP API yet.
+    // The audit_log table is written internally.
+    return {
+        success: false,
+        error: {
+            code: 'NOT_IMPLEMENTED',
+            message: 'list_audit_log: reserved for V0.2. Convex query crm.auditLog.list not yet exposed.',
+        },
+    };
+}
+async function get_entity_history(rawArgs) {
+    GetEntityHistorySchema.parse(rawArgs);
+    return {
+        success: false,
+        error: {
+            code: 'NOT_IMPLEMENTED',
+            message: 'get_entity_history: reserved for V0.2. Convex query crm.auditLog.byEntity not yet exposed.',
+        },
+    };
+}
+async function get_actor_history(rawArgs) {
+    GetActorHistorySchema.parse(rawArgs);
+    return {
+        success: false,
+        error: {
+            code: 'NOT_IMPLEMENTED',
+            message: 'get_actor_history: reserved for V0.2. Convex query crm.auditLog.byActor not yet exposed.',
+        },
+    };
+}
+async function purge_archived_records(rawArgs) {
+    const args = PurgeArchivedSchema.parse(rawArgs);
+    // Hard delete of archived records >N days.
+    // 30-day grace is enforced server-side in convex/crm/admin.ts purgeArchivedRecords.
+    // anyApi is used since crm.admin is not yet in the generated types.
+    return (0, convexClient_1.withEnvelope)(() => 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (0, convexClient_1.getConvexClient)().mutation(server_1.anyApi.crm.admin.purgeArchivedRecords, {
+        workspaceId: args.workspaceId,
+        entityType: args.entityType,
+        olderThanDays: args.olderThanDays,
+    }));
+}
+async function list_workspace_limits(rawArgs) {
+    const args = ListWorkspaceLimitsSchema.parse(rawArgs);
+    // workspaceLimits — proxy to workspace context query which includes subscription info
+    return (0, convexClient_1.withEnvelope)(() => (0, convexClient_1.getConvexClient)().query(api_1.api.workspaces.getContext, {
+        workspaceId: args.workspaceId,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+exports.ADMIN_TOOLS = [
+    {
+        name: 'list_audit_log',
+        description: 'List audit log entries with filters (admin only)',
+        requiredScope: 'admin',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                entityType: { type: 'string' },
+                actorId: { type: 'string' },
+                since: { type: 'number' },
+                until: { type: 'number' },
+                limit: { type: 'number' },
+            },
+            required: ['workspaceId'],
+        },
+    },
+    {
+        name: 'get_entity_history',
+        description: 'Full audit history for a single entity record (admin only)',
+        requiredScope: 'admin',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                entityType: { type: 'string' },
+                entityId: { type: 'string' },
+            },
+            required: ['workspaceId', 'entityType', 'entityId'],
+        },
+    },
+    {
+        name: 'get_actor_history',
+        description: 'All actions by a specific actor (user or agent) in a workspace (admin only)',
+        requiredScope: 'admin',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                actorId: { type: 'string' },
+                since: { type: 'number' },
+                until: { type: 'number' },
+                limit: { type: 'number' },
+            },
+            required: ['workspaceId', 'actorId'],
+        },
+    },
+    {
+        name: 'purge_archived_records',
+        description: 'Hard delete archived records older than N days (admin only, OQ-4 minimum 30 days grace)',
+        requiredScope: 'admin',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                entityType: { type: 'string', enum: ['contact', 'company', 'deal', 'custom_object_record'] },
+                olderThanDays: { type: 'number', minimum: 30, default: 30 },
+            },
+            required: ['workspaceId', 'entityType'],
+        },
+    },
+    {
+        name: 'list_workspace_limits',
+        description: 'List workspace subscription limits and current usage (admin only)',
+        requiredScope: 'admin',
+        inputSchema: {
+            type: 'object',
+            properties: { workspaceId: { type: 'string' } },
+            required: ['workspaceId'],
+        },
+    },
+];

package/dist/mcp-server/tools/companies.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * VantageCRM MCP — Companies tools (6 tools)
+ *
+ * Tools: create_company, get_company, update_company, list_companies,
+ *        search_companies, delete_company
+ *
+ * Scope: read for queries, write for mutations
+ * Ref: spec §3.3
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPANY_TOOLS = void 0;
+exports.create_company = create_company;
+exports.get_company = get_company;
+exports.update_company = update_company;
+exports.list_companies = list_companies;
+exports.search_companies = search_companies;
+exports.delete_company = delete_company;
+const zod_1 = require("zod");
+const api_1 = require("../../convex/_generated/api");
+const convexClient_1 = require("../lib/convexClient");
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+const COMPANY_SIZE = ['1-10', '11-50', '51-200', '201-1000', '1000+'];
+const CreateCompanySchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    name: zod_1.z.string().min(1).max(200),
+    domain: zod_1.z.string().max(200).optional(),
+    industry: zod_1.z.string().max(100).optional(),
+    size: zod_1.z.enum(COMPANY_SIZE).optional(),
+    website: zod_1.z.string().url().optional(),
+    phone: zod_1.z.string().max(30).optional(),
+    address: zod_1.z.string().max(500).optional(),
+    description: zod_1.z.string().max(5000).optional(),
+    tags: zod_1.z.array(zod_1.z.string()).max(20).optional(),
+    notes: zod_1.z.string().max(5000).optional(),
+    customFields: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+const GetCompanySchema = zod_1.z.object({
+    companyId: zod_1.z.string().min(1),
+});
+const UpdateCompanySchema = zod_1.z.object({
+    companyId: zod_1.z.string().min(1),
+    name: zod_1.z.string().min(1).max(200).optional(),
+    domain: zod_1.z.string().max(200).optional(),
+    industry: zod_1.z.string().max(100).optional(),
+    size: zod_1.z.enum(COMPANY_SIZE).optional(),
+    website: zod_1.z.string().url().optional(),
+    phone: zod_1.z.string().max(30).optional(),
+    address: zod_1.z.string().max(500).optional(),
+    description: zod_1.z.string().max(5000).optional(),
+    tags: zod_1.z.array(zod_1.z.string()).max(20).optional(),
+    notes: zod_1.z.string().max(5000).optional(),
+    customFields: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+const ListCompaniesSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    industry: zod_1.z.string().optional(),
+    limit: zod_1.z.number().int().min(1).max(100).default(20),
+});
+const SearchCompaniesSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    query: zod_1.z.string().min(1).max(200),
+    limit: zod_1.z.number().int().min(1).max(50).default(10),
+});
+const DeleteCompanySchema = zod_1.z.object({
+    companyId: zod_1.z.string().min(1),
+});
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+async function create_company(rawArgs) {
+    const args = CreateCompanySchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (0, convexClient_1.getConvexClient)().mutation(api_1.api.crm.companies.create, {
+        workspaceId: args.workspaceId,
+        name: args.name,
+        domain: args.domain,
+        industry: args.industry,
+        size: args.size,
+        website: args.website,
+        phone: args.phone,
+        address: args.address,
+        description: args.description,
+        tags: args.tags,
+        notes: args.notes,
+        customFields: args.customFields,
+    }));
+}
+async function get_company(rawArgs) {
+    const args = GetCompanySchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (0, convexClient_1.getConvexClient)().query(api_1.api.crm.companies.get, {
+        companyId: args.companyId,
+    }));
+}
+async function update_company(rawArgs) {
+    const args = UpdateCompanySchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (0, convexClient_1.getConvexClient)().mutation(api_1.api.crm.companies.update, {
+        companyId: args.companyId,
+        name: args.name,
+        domain: args.domain,
+        industry: args.industry,
+        size: args.size,
+        website: args.website,
+        phone: args.phone,
+        address: args.address,
+        description: args.description,
+        tags: args.tags,
+        notes: args.notes,
+        customFields: args.customFields,
+    }));
+}
+async function list_companies(rawArgs) {
+    const args = ListCompaniesSchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (0, convexClient_1.getConvexClient)().query(api_1.api.crm.companies.list, {
+        workspaceId: args.workspaceId,
+        industry: args.industry,
+        limit: args.limit,
+    }));
+}
+async function search_companies(rawArgs) {
+    const args = SearchCompaniesSchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (0, convexClient_1.getConvexClient)().query(api_1.api.crm.companies.search, {
+        workspaceId: args.workspaceId,
+        query: args.query,
+    }));
+}
+async function delete_company(rawArgs) {
+    const args = DeleteCompanySchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (0, convexClient_1.getConvexClient)().mutation(api_1.api.crm.companies.remove, {
+        companyId: args.companyId,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+exports.COMPANY_TOOLS = [
+    {
+        name: 'create_company',
+        description: 'Create a company record in the CRM',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                name: { type: 'string' },
+                domain: { type: 'string' },
+                industry: { type: 'string' },
+                size: { type: 'string', enum: ['1-10', '11-50', '51-200', '201-1000', '1000+'] },
+                website: { type: 'string' },
+                description: { type: 'string' },
+                customFields: { type: 'object' },
+            },
+            required: ['workspaceId', 'name'],
+        },
+    },
+    {
+        name: 'get_company',
+        description: 'Retrieve a company by ID',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: { companyId: { type: 'string' } },
+            required: ['companyId'],
+        },
+    },
+    {
+        name: 'update_company',
+        description: 'Update a company record',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                companyId: { type: 'string' },
+                name: { type: 'string' },
+                domain: { type: 'string' },
+                industry: { type: 'string' },
+                size: { type: 'string', enum: ['1-10', '11-50', '51-200', '201-1000', '1000+'] },
+            },
+            required: ['companyId'],
+        },
+    },
+    {
+        name: 'list_companies',
+        description: 'List companies with optional industry filter',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                industry: { type: 'string' },
+                limit: { type: 'number' },
+            },
+            required: ['workspaceId'],
+        },
+    },
+    {
+        name: 'search_companies',
+        description: 'Full-text search companies',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                query: { type: 'string' },
+                limit: { type: 'number' },
+            },
+            required: ['workspaceId', 'query'],
+        },
+    },
+    {
+        name: 'delete_company',
+        description: 'Soft delete a company (isArchived=true)',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: { companyId: { type: 'string' } },
+            required: ['companyId'],
+        },
+    },
+];