Tiptap Collaboration MCP Server

Instructions

Implementation Reference

• src/tools/batch-import-documents.ts:20-77 (handler)

  The handler function for the 'batch-import-documents' tool. It sends a PUT request to `/api/admin/batch-import` with the provided documents data, handles errors, and returns success or error messages.

  async ({ documents }) => {
    try {
      const headers: Record<string, string> = {
        'User-Agent': 'tiptap-collaboration-mcp',
        'Content-Type': 'application/json',
      };
  
      const token = getToken();
      if (token) headers['Authorization'] = token;
  
      const response = await fetch(`${getBaseUrl()}/api/admin/batch-import`, {
        method: 'PUT',
        headers,
        body: JSON.stringify(documents),
      });
  
      if (!response.ok) {
        if (response.status === 400) {
          return {
            content: [
              {
                type: 'text',
                text: 'Invalid data provided for batch import. Please check the document structure and format.',
              },
            ],
          };
        }
        return {
          content: [
            {
              type: 'text',
              text: `Failed to import documents. HTTP error: ${response.status} ${response.statusText}`,
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: `Successfully imported ${documents.length} document groups with their versions.`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error importing documents: ${
              error instanceof Error ? error.message : 'Unknown error'
            }`,
          },
        ],
      };
    }
  }

• src/tools/batch-import-documents.ts:12-19 (schema)

  Zod schema defining the input parameters for the tool: an array of arrays of document objects, each containing created_at, version, name, and tiptap_json.

  {
    documents: z.array(z.array(z.object({
      created_at: z.string().describe('Creation timestamp in ISO format'),
      version: z.number().describe('Document version number'),
      name: z.string().describe('Document name/identifier'),
      tiptap_json: z.object({}).describe('Document content in Tiptap JSON format'),
    }))).describe('Array of document arrays, where each inner array represents versions of a single document'),
  },

• src/tools/batch-import-documents.ts:4-79 (registration)

  The registration function `registerBatchImportDocuments` that defines and registers the 'batch-import-documents' tool on the MCP server, including name, description, schema, and handler.

  export default function registerBatchImportDocuments(
    server: McpServer,
    getBaseUrl: () => string,
    getToken: () => string | undefined
  ) {
    server.tool(
      'batch-import-documents',
      'Bulk import multiple documents using predefined JSON structure',
      {
        documents: z.array(z.array(z.object({
          created_at: z.string().describe('Creation timestamp in ISO format'),
          version: z.number().describe('Document version number'),
          name: z.string().describe('Document name/identifier'),
          tiptap_json: z.object({}).describe('Document content in Tiptap JSON format'),
        }))).describe('Array of document arrays, where each inner array represents versions of a single document'),
      },
      async ({ documents }) => {
        try {
          const headers: Record<string, string> = {
            'User-Agent': 'tiptap-collaboration-mcp',
            'Content-Type': 'application/json',
          };
  
          const token = getToken();
          if (token) headers['Authorization'] = token;
  
          const response = await fetch(`${getBaseUrl()}/api/admin/batch-import`, {
            method: 'PUT',
            headers,
            body: JSON.stringify(documents),
          });
  
          if (!response.ok) {
            if (response.status === 400) {
              return {
                content: [
                  {
                    type: 'text',
                    text: 'Invalid data provided for batch import. Please check the document structure and format.',
                  },
                ],
              };
            }
            return {
              content: [
                {
                  type: 'text',
                  text: `Failed to import documents. HTTP error: ${response.status} ${response.statusText}`,
                },
              ],
            };
          }
  
          return {
            content: [
              {
                type: 'text',
                text: `Successfully imported ${documents.length} document groups with their versions.`,
              },
            ],
          };
        } catch (error) {
          return {
            content: [
              {
                type: 'text',
                text: `Error importing documents: ${
                  error instanceof Error ? error.message : 'Unknown error'
                }`,
              },
            ],
          };
        }
      }
    );
  }

• src/server.ts:46-46 (registration)

  Invocation of the registration function in the main server file to register the tool.

  registerBatchImportDocuments(server, getBaseUrl, getToken);

• src/server.ts:2-2 (registration)

  Import of the registration module for the batch import documents tool.

  import registerBatchImportDocuments from './tools/batch-import-documents.js';