Tiptap Collaboration MCP Server

Instructions

Implementation Reference

• src/tools/update-document.ts:17-84 (handler)

  The handler function that implements the core logic of the 'update-document' tool. It performs an HTTP PATCH request to the API to update the document content, handles specific error codes (404, 422), and returns structured content responses.

  async ({ id, content, mode = 'replace' }) => {
    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/documents/${id}?mode=${mode}`, {
        method: 'PATCH',
        headers,
        body: JSON.stringify(content),
      });
  
      if (!response.ok) {
        if (response.status === 404) {
          return {
            content: [
              {
                type: 'text',
                text: `Document with ID ${id} not found.`,
              },
            ],
          };
        }
        if (response.status === 422) {
          return {
            content: [
              {
                type: 'text',
                text: `Invalid payload or update cannot be applied to document ${id}.`,
              },
            ],
          };
        }
        return {
          content: [
            {
              type: 'text',
              text: `Failed to update document. HTTP error: ${response.status} ${response.statusText}`,
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: `Document with ID ${id} updated successfully using ${mode} mode.`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error updating document: ${
              error instanceof Error ? error.message : 'Unknown error'
            }`,
          },
        ],
      };
    }
  }

• src/tools/update-document.ts:12-16 (schema)

  Zod schema for the tool's input parameters: document ID, content object, and optional update mode.

  {
    id: z.string().describe('ID of the document to update'),
    content: z.object({}).describe('Document content in Tiptap JSON format'),
    mode: z.enum(['replace', 'append']).optional().describe('Update mode: replace entire document or append content (default: replace)'),
  },

• src/tools/update-document.ts:4-86 (registration)

  The registration function exported from the tool module, which calls server.tool to register the 'update-document' tool with its schema and handler.

  export default function registerUpdateDocument(
    server: McpServer,
    getBaseUrl: () => string,
    getToken: () => string | undefined
  ) {
    server.tool(
      'update-document',
      'Update a collaborative document with new content',
      {
        id: z.string().describe('ID of the document to update'),
        content: z.object({}).describe('Document content in Tiptap JSON format'),
        mode: z.enum(['replace', 'append']).optional().describe('Update mode: replace entire document or append content (default: replace)'),
      },
      async ({ id, content, mode = 'replace' }) => {
        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/documents/${id}?mode=${mode}`, {
            method: 'PATCH',
            headers,
            body: JSON.stringify(content),
          });
  
          if (!response.ok) {
            if (response.status === 404) {
              return {
                content: [
                  {
                    type: 'text',
                    text: `Document with ID ${id} not found.`,
                  },
                ],
              };
            }
            if (response.status === 422) {
              return {
                content: [
                  {
                    type: 'text',
                    text: `Invalid payload or update cannot be applied to document ${id}.`,
                  },
                ],
              };
            }
            return {
              content: [
                {
                  type: 'text',
                  text: `Failed to update document. HTTP error: ${response.status} ${response.statusText}`,
                },
              ],
            };
          }
  
          return {
            content: [
              {
                type: 'text',
                text: `Document with ID ${id} updated successfully using ${mode} mode.`,
              },
            ],
          };
        } catch (error) {
          return {
            content: [
              {
                type: 'text',
                text: `Error updating document: ${
                  error instanceof Error ? error.message : 'Unknown error'
                }`,
              },
            ],
          };
        }
      }
    );
  }

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

  Invocation of the registerUpdateDocument function on the main MCP server instance, integrating the tool into the server.

  registerUpdateDocument(server, getBaseUrl, getToken);