@vantageos/vantage-crm-mcp 0.1.0

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

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * VantageCRM MCP — Contacts tools (8 tools)
+ *
+ * Tools: create_contact, get_contact, update_contact, list_contacts,
+ *        search_contacts, delete_contact, list_contacts_by_custom_field, restore_contact
+ *
+ * Scope: read for queries, write for mutations
+ * Ref: spec §3.2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTACT_TOOLS = void 0;
+exports.create_contact = create_contact;
+exports.get_contact = get_contact;
+exports.update_contact = update_contact;
+exports.list_contacts = list_contacts;
+exports.search_contacts = search_contacts;
+exports.delete_contact = delete_contact;
+exports.list_contacts_by_custom_field = list_contacts_by_custom_field;
+exports.restore_contact = restore_contact;
+const zod_1 = require("zod");
+const api_1 = require("../../convex/_generated/api");
+const convexClient_1 = require("../lib/convexClient");
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+const CreateContactSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    firstName: zod_1.z.string().min(1).max(100),
+    lastName: zod_1.z.string().min(1).max(100),
+    email: zod_1.z.string().email().optional(),
+    phone: zod_1.z.string().max(30).optional(),
+    companyId: zod_1.z.string().optional(),
+    type: zod_1.z.enum(['lead', 'prospect', 'client', 'partner', 'other']).default('lead'),
+    source: zod_1.z.string().max(100).optional(),
+    tags: zod_1.z.array(zod_1.z.string()).max(20).optional(),
+    notes: zod_1.z.string().max(10000).optional(),
+    jobTitle: zod_1.z.string().max(200).optional(),
+    linkedinUrl: zod_1.z.string().url().optional(),
+    customFields: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+const GetContactSchema = zod_1.z.object({
+    contactId: zod_1.z.string().min(1),
+});
+const UpdateContactSchema = zod_1.z.object({
+    contactId: zod_1.z.string().min(1),
+    firstName: zod_1.z.string().min(1).max(100).optional(),
+    lastName: zod_1.z.string().min(1).max(100).optional(),
+    email: zod_1.z.string().email().optional(),
+    phone: zod_1.z.string().max(30).optional(),
+    companyId: zod_1.z.string().optional(),
+    type: zod_1.z.enum(['lead', 'prospect', 'client', 'partner', 'other']).optional(),
+    source: zod_1.z.string().max(100).optional(),
+    tags: zod_1.z.array(zod_1.z.string()).max(20).optional(),
+    notes: zod_1.z.string().max(10000).optional(),
+    jobTitle: zod_1.z.string().max(200).optional(),
+    linkedinUrl: zod_1.z.string().url().optional(),
+    customFields: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+const ListContactsSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    type: zod_1.z.enum(['lead', 'prospect', 'client', 'partner', 'other']).optional(),
+    companyId: zod_1.z.string().optional(),
+    limit: zod_1.z.number().int().min(1).max(100).default(20),
+});
+const SearchContactsSchema = 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 DeleteContactSchema = zod_1.z.object({
+    contactId: zod_1.z.string().min(1),
+});
+const ListContactsByCustomFieldSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    fieldKey: zod_1.z.string().min(1),
+    fieldValue: zod_1.z.unknown(),
+    limit: zod_1.z.number().int().min(1).max(100).default(20),
+});
+const RestoreContactSchema = zod_1.z.object({
+    contactId: zod_1.z.string().min(1),
+});
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+async function create_contact(rawArgs) {
+    const args = CreateContactSchema.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.contacts.create, {
+        workspaceId: args.workspaceId,
+        firstName: args.firstName,
+        lastName: args.lastName,
+        email: args.email,
+        phone: args.phone,
+        companyId: args.companyId,
+        type: args.type,
+        source: args.source,
+        tags: args.tags,
+        notes: args.notes,
+        jobTitle: args.jobTitle,
+        linkedinUrl: args.linkedinUrl,
+        customFields: args.customFields,
+    }));
+}
+async function get_contact(rawArgs) {
+    const args = GetContactSchema.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.contacts.get, {
+        contactId: args.contactId,
+    }));
+}
+async function update_contact(rawArgs) {
+    const args = UpdateContactSchema.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.contacts.update, {
+        contactId: args.contactId,
+        firstName: args.firstName,
+        lastName: args.lastName,
+        email: args.email,
+        phone: args.phone,
+        companyId: args.companyId,
+        type: args.type,
+        source: args.source,
+        tags: args.tags,
+        notes: args.notes,
+        jobTitle: args.jobTitle,
+        linkedinUrl: args.linkedinUrl,
+        customFields: args.customFields,
+    }));
+}
+async function list_contacts(rawArgs) {
+    const args = ListContactsSchema.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.contacts.list, {
+        workspaceId: args.workspaceId,
+        type: args.type,
+        companyId: args.companyId,
+        limit: args.limit,
+    }));
+}
+async function search_contacts(rawArgs) {
+    const args = SearchContactsSchema.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.contacts.search, {
+        workspaceId: args.workspaceId,
+        query: args.query,
+    }));
+}
+async function delete_contact(rawArgs) {
+    const args = DeleteContactSchema.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.contacts.remove, {
+        contactId: args.contactId,
+    }));
+}
+async function list_contacts_by_custom_field(rawArgs) {
+    const args = ListContactsByCustomFieldSchema.parse(rawArgs);
+    // listByCustomField not yet in Convex layer — fall back to list + client-side filter
+    return (0, convexClient_1.withEnvelope)(async () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const all = await (0, convexClient_1.getConvexClient)().query(api_1.api.crm.contacts.list, {
+            workspaceId: args.workspaceId,
+            limit: 200,
+        });
+        return all.filter((c) => {
+            const cf = c['customFields'];
+            return cf && cf[args.fieldKey] === args.fieldValue;
+        }).slice(0, args.limit);
+    });
+}
+async function restore_contact(rawArgs) {
+    const args = RestoreContactSchema.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.contacts.restoreContact, {
+        contactId: args.contactId,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Tool definitions (for MCP registry)
+// ---------------------------------------------------------------------------
+exports.CONTACT_TOOLS = [
+    {
+        name: 'create_contact',
+        description: 'Create a CRM contact with optional custom fields',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                firstName: { type: 'string' },
+                lastName: { type: 'string' },
+                email: { type: 'string' },
+                phone: { type: 'string' },
+                companyId: { type: 'string' },
+                type: { type: 'string', enum: ['lead', 'prospect', 'client', 'partner', 'other'] },
+                source: { type: 'string' },
+                tags: { type: 'array', items: { type: 'string' } },
+                notes: { type: 'string' },
+                jobTitle: { type: 'string' },
+                linkedinUrl: { type: 'string' },
+                customFields: { type: 'object' },
+            },
+            required: ['workspaceId', 'firstName', 'lastName'],
+        },
+    },
+    {
+        name: 'get_contact',
+        description: 'Retrieve a contact by ID',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: { contactId: { type: 'string' } },
+            required: ['contactId'],
+        },
+    },
+    {
+        name: 'update_contact',
+        description: 'Update a contact record',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                contactId: { type: 'string' },
+                firstName: { type: 'string' },
+                lastName: { type: 'string' },
+                email: { type: 'string' },
+                phone: { type: 'string' },
+                type: { type: 'string' },
+                tags: { type: 'array', items: { type: 'string' } },
+                customFields: { type: 'object' },
+            },
+            required: ['contactId'],
+        },
+    },
+    {
+        name: 'list_contacts',
+        description: 'List contacts filtered by workspace/type',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                type: { type: 'string' },
+                companyId: { type: 'string' },
+                limit: { type: 'number' },
+            },
+            required: ['workspaceId'],
+        },
+    },
+    {
+        name: 'search_contacts',
+        description: 'Full-text search contacts',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                query: { type: 'string' },
+                limit: { type: 'number' },
+            },
+            required: ['workspaceId', 'query'],
+        },
+    },
+    {
+        name: 'delete_contact',
+        description: 'Soft delete a contact (isArchived=true, 30-day grace period)',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: { contactId: { type: 'string' } },
+            required: ['contactId'],
+        },
+    },
+    {
+        name: 'list_contacts_by_custom_field',
+        description: 'Filter contacts by a custom field value',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                fieldKey: { type: 'string' },
+                fieldValue: {},
+                limit: { type: 'number' },
+            },
+            required: ['workspaceId', 'fieldKey', 'fieldValue'],
+        },
+    },
+    {
+        name: 'restore_contact',
+        description: 'Restore a soft-deleted contact (isArchived=false)',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: { contactId: { type: 'string' } },
+            required: ['contactId'],
+        },
+    },
+];

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

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * VantageCRM MCP — Custom Fields tools (5 tools)
+ *
+ * Tools: add_custom_field, update_custom_field_definition, list_custom_fields,
+ *        set_custom_field_value, delete_custom_field
+ *
+ * Scope: read/write for most, admin for delete
+ * Ref: spec §3.6
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CUSTOM_FIELD_TOOLS = void 0;
+exports.add_custom_field = add_custom_field;
+exports.update_custom_field_definition = update_custom_field_definition;
+exports.list_custom_fields = list_custom_fields;
+exports.set_custom_field_value = set_custom_field_value;
+exports.delete_custom_field = delete_custom_field;
+const zod_1 = require("zod");
+const server_1 = require("convex/server");
+const convexClient_1 = require("../lib/convexClient");
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+const ENTITY_TYPES = ['contact', 'company', 'deal', 'activity'];
+const FIELD_TYPES = ['text', 'number', 'boolean', 'date', 'select', 'multi_select', 'url', 'email', 'phone'];
+const AddCustomFieldSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    entityType: zod_1.z.enum(ENTITY_TYPES),
+    key: zod_1.z.string().min(1).max(100).regex(/^[a-z0-9_]+$/, 'Key must be snake_case'),
+    label: zod_1.z.string().min(1).max(200),
+    fieldType: zod_1.z.enum(FIELD_TYPES),
+    required: zod_1.z.boolean().default(false),
+    options: zod_1.z.array(zod_1.z.string()).optional(),
+    validation: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    description: zod_1.z.string().max(1000).optional(),
+    visibility: zod_1.z.enum(['all', 'admin', 'owner']).default('all'),
+});
+const UpdateCustomFieldDefinitionSchema = zod_1.z.object({
+    definitionId: zod_1.z.string().min(1),
+    label: zod_1.z.string().min(1).max(200).optional(),
+    options: zod_1.z.array(zod_1.z.string()).optional(),
+    validation: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    description: zod_1.z.string().max(1000).optional(),
+    visibility: zod_1.z.enum(['all', 'admin', 'owner']).optional(),
+    required: zod_1.z.boolean().optional(),
+});
+const ListCustomFieldsSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    entityType: zod_1.z.enum(ENTITY_TYPES).optional(),
+});
+const SetCustomFieldValueSchema = zod_1.z.object({
+    workspaceId: zod_1.z.string().min(1),
+    entityType: zod_1.z.enum(ENTITY_TYPES),
+    entityId: zod_1.z.string().min(1),
+    key: zod_1.z.string().min(1),
+    value: zod_1.z.unknown(),
+});
+const DeleteCustomFieldSchema = zod_1.z.object({
+    definitionId: zod_1.z.string().min(1),
+});
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+async function add_custom_field(rawArgs) {
+    const args = AddCustomFieldSchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => (0, convexClient_1.getConvexClient)().mutation(server_1.anyApi.crm.customFields.defineCustomField, {
+        workspaceId: args.workspaceId,
+        entityType: args.entityType,
+        key: args.key,
+        label: args.label,
+        fieldType: args.fieldType,
+        required: args.required,
+        options: args.options,
+        description: args.description,
+        visibility: args.visibility,
+    }));
+}
+async function update_custom_field_definition(rawArgs) {
+    const args = UpdateCustomFieldDefinitionSchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => (0, convexClient_1.getConvexClient)().mutation(server_1.anyApi.crm.customFields.updateCustomFieldDefinition, {
+        definitionId: args.definitionId,
+        label: args.label,
+        options: args.options,
+        description: args.description,
+        visibility: args.visibility,
+        required: args.required,
+    }));
+}
+async function list_custom_fields(rawArgs) {
+    const args = ListCustomFieldsSchema.parse(rawArgs);
+    return (0, convexClient_1.withEnvelope)(() => (0, convexClient_1.getConvexClient)().query(server_1.anyApi.crm.customFields.listCustomFieldDefinitions, {
+        workspaceId: args.workspaceId,
+        entityType: args.entityType,
+    }));
+}
+async function set_custom_field_value(rawArgs) {
+    const args = SetCustomFieldValueSchema.parse(rawArgs);
+    // setValue is implemented as a patch on the entity's customFields JSON column
+    // Map entityType to the correct mutation
+    return (0, convexClient_1.withEnvelope)(async () => {
+        const entityType = args.entityType;
+        const entityId = args.entityId;
+        const patch = { customFields: { [args.key]: args.value } };
+        if (entityType === 'contact') {
+            return (0, convexClient_1.getConvexClient)().mutation(server_1.anyApi.crm.contacts.update, {
+                contactId: entityId,
+                customFields: patch.customFields,
+            });
+        }
+        else if (entityType === 'company') {
+            return (0, convexClient_1.getConvexClient)().mutation(server_1.anyApi.crm.companies.update, {
+                companyId: entityId,
+                customFields: patch.customFields,
+            });
+        }
+        else if (entityType === 'deal') {
+            return (0, convexClient_1.getConvexClient)().mutation(server_1.anyApi.crm.deals.update, {
+                dealId: entityId,
+                customFields: patch.customFields,
+            });
+        }
+        else if (entityType === 'activity') {
+            return (0, convexClient_1.getConvexClient)().mutation(server_1.anyApi.crm.activities.update, {
+                activityId: entityId,
+                customFields: patch.customFields,
+            });
+        }
+        throw new Error(`Unsupported entityType: ${entityType}`);
+    });
+}
+async function delete_custom_field(rawArgs) {
+    DeleteCustomFieldSchema.parse(rawArgs);
+    // deleteDefinition not yet in Convex layer V0.1.0 — stable NOT_IMPLEMENTED envelope
+    return {
+        success: false,
+        error: {
+            code: 'NOT_IMPLEMENTED',
+            message: 'delete_custom_field: reserved for V0.2. Requires crm.customFields.deleteCustomFieldDefinition mutation.',
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+exports.CUSTOM_FIELD_TOOLS = [
+    {
+        name: 'add_custom_field',
+        description: 'Create a custom field definition for an entity type',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                entityType: { type: 'string', enum: ['contact', 'company', 'deal', 'activity'] },
+                key: { type: 'string', description: 'snake_case identifier' },
+                label: { type: 'string' },
+                fieldType: { type: 'string', enum: ['text', 'number', 'boolean', 'date', 'select', 'multi_select', 'url', 'email', 'phone'] },
+                required: { type: 'boolean' },
+                options: { type: 'array', items: { type: 'string' } },
+                description: { type: 'string' },
+                visibility: { type: 'string', enum: ['all', 'admin', 'owner'] },
+            },
+            required: ['workspaceId', 'entityType', 'key', 'label', 'fieldType'],
+        },
+    },
+    {
+        name: 'update_custom_field_definition',
+        description: 'Update a custom field definition (label, options, validation)',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                definitionId: { type: 'string' },
+                label: { type: 'string' },
+                options: { type: 'array', items: { type: 'string' } },
+                description: { type: 'string' },
+                visibility: { type: 'string' },
+                required: { type: 'boolean' },
+            },
+            required: ['definitionId'],
+        },
+    },
+    {
+        name: 'list_custom_fields',
+        description: 'List custom field definitions for a workspace/entity type',
+        requiredScope: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                entityType: { type: 'string' },
+            },
+            required: ['workspaceId'],
+        },
+    },
+    {
+        name: 'set_custom_field_value',
+        description: 'Set a custom field value on an entity record',
+        requiredScope: 'write',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string' },
+                entityType: { type: 'string', enum: ['contact', 'company', 'deal', 'activity'] },
+                entityId: { type: 'string' },
+                key: { type: 'string' },
+                value: {},
+            },
+            required: ['workspaceId', 'entityType', 'entityId', 'key', 'value'],
+        },
+    },
+    {
+        name: 'delete_custom_field',
+        description: 'Delete a custom field definition (admin only — irreversible)',
+        requiredScope: 'admin',
+        inputSchema: {
+            type: 'object',
+            properties: { definitionId: { type: 'string' } },
+            required: ['definitionId'],
+        },
+    },
+];