mcpengine/servers/intercom/src/tools/articles.ts

/**
 * Intercom Articles Tools
 */

import { z } from 'zod';
import { Tool } from '@modelcontextprotocol/sdk/types.js';
import type { IntercomClient } from '../clients/intercom.js';

// Zod schemas
const CreateArticleSchema = z.object({
  title: z.string(),
  description: z.string().optional(),
  body: z.string().optional(),
  author_id: z.string(),
  state: z.enum(['published', 'draft']).optional(),
  parent_id: z.string().optional(),
  parent_type: z.enum(['collection', 'section']).optional(),
});

const UpdateArticleSchema = z.object({
  id: z.string(),
  title: z.string().optional(),
  description: z.string().optional(),
  body: z.string().optional(),
  author_id: z.string().optional(),
  state: z.enum(['published', 'draft']).optional(),
  parent_id: z.string().optional(),
  parent_type: z.enum(['collection', 'section']).optional(),
});

// Tool definitions
export function getTools(client: IntercomClient): Array<{
  definition: Tool;
  handler: (args: Record<string, unknown>) => Promise<unknown>;
}> {
  return [
    {
      definition: {
        name: 'intercom_list_articles',
        description: 'List all help center articles with pagination.',
        inputSchema: {
          type: 'object',
          properties: {
            per_page: {
              type: 'number',
              description: 'Number of results per page',
            },
            page: {
              type: 'number',
              description: 'Page number',
            },
          },
        },
      },
      handler: async (args) => {
        const params = args as { per_page?: number; page?: number };
        return client.listArticles(params);
      },
    },

    {
      definition: {
        name: 'intercom_get_article',
        description: 'Retrieve a specific article by ID.',
        inputSchema: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              description: 'Article ID',
            },
          },
          required: ['id'],
        },
      },
      handler: async (args) => {
        const { id } = args as { id: string };
        return client.getArticle(id as any);
      },
    },

    {
      definition: {
        name: 'intercom_create_article',
        description: 'Create a new help center article. Can be published immediately or saved as draft.',
        inputSchema: {
          type: 'object',
          properties: {
            title: {
              type: 'string',
              description: 'Article title (required)',
            },
            description: {
              type: 'string',
              description: 'Short description/summary',
            },
            body: {
              type: 'string',
              description: 'Article body content (HTML or markdown)',
            },
            author_id: {
              type: 'string',
              description: 'Admin ID of the author (required)',
            },
            state: {
              type: 'string',
              enum: ['published', 'draft'],
              description: 'Publication state (default: draft)',
            },
            parent_id: {
              type: 'string',
              description: 'Collection or Section ID to place article in',
            },
            parent_type: {
              type: 'string',
              enum: ['collection', 'section'],
              description: 'Type of parent (collection or section)',
            },
          },
          required: ['title', 'author_id'],
        },
      },
      handler: async (args) => {
        const data = CreateArticleSchema.parse(args);
        return client.createArticle(data as any);
      },
    },

    {
      definition: {
        name: 'intercom_update_article',
        description: 'Update an existing article by ID.',
        inputSchema: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              description: 'Article ID',
            },
            title: {
              type: 'string',
              description: 'Article title',
            },
            description: {
              type: 'string',
              description: 'Description',
            },
            body: {
              type: 'string',
              description: 'Article body content',
            },
            author_id: {
              type: 'string',
              description: 'Author admin ID',
            },
            state: {
              type: 'string',
              enum: ['published', 'draft'],
              description: 'Publication state',
            },
            parent_id: {
              type: 'string',
              description: 'Parent collection or section ID',
            },
            parent_type: {
              type: 'string',
              enum: ['collection', 'section'],
              description: 'Parent type',
            },
          },
          required: ['id'],
        },
      },
      handler: async (args) => {
        const { id, ...data } = UpdateArticleSchema.parse(args);
        return client.updateArticle(id as any, data as any);
      },
    },

    {
      definition: {
        name: 'intercom_delete_article',
        description: 'Permanently delete an article by ID. This action cannot be undone.',
        inputSchema: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              description: 'Article ID to delete',
            },
          },
          required: ['id'],
        },
      },
      handler: async (args) => {
        const { id } = args as { id: string };
        return client.deleteArticle(id as any);
      },
    },
  ];
}