Tiptap 协作 MCP 服务器

Tiptap Collaboration MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Tiptap Collaboration services.

Tools Available

Statistics

get-server-statistics

Get server-wide usage statistics.

• Parameters: None
• Returns: Total documents, connections, concurrent users, and the collaboration server's version — useful for confirming which server you are talking to

get-document-statistics

Get real-time statistics for a specific document.

• Parameters:
  • id (string): Document ID
• Returns: Document size, version count, current connections, connected IPs
• Note: The server's statistics endpoint returns zeroes for nonexistent documents, so the tool first checks existence with a HEAD request (available since server 3.91.0). On older servers the check is skipped and a missing document reports zeroes.

Document Management

create-document

Create a new collaborative document.

• Parameters:
  • name (string): Name of the document
  • content (object, optional): Initial content in Tiptap JSON format; defaults to {"type": "doc", "content": [{"type": "paragraph"}]}
• Returns: Creation confirmation (the server answers 204 with no body)

get-document

Retrieve a collaborative document.

• Parameters:
  • id (string): ID of the document to retrieve
• Returns: The document's Tiptap JSON content

list-documents

List all available collaborative documents.

• Parameters: None
• Returns: Array of documents (name, size, timestamps)

update-document

Update a collaborative document with new content.

• Parameters:
  • id (string): Document ID
  • content (object): Document content in Tiptap JSON format
  • mode (string, optional): Update mode - "replace" or "append" (default: "replace")
• Returns: Update confirmation (the server answers 204; the document is not echoed back)

delete-document

Delete a collaborative document.

• Parameters:
  • id (string): ID of the document to delete
• Returns: Deletion confirmation

Advanced Document Operations

duplicate-document

Duplicate an existing collaborative document (fetches the source as JSON and creates the target from it; versions are not copied).

• Parameters:
  • sourceId (string): ID of the source document to duplicate
  • targetId (string): ID for the new duplicated document
• Returns: Duplication confirmation

search-documents

Search documents using semantic search.

• Parameters:
  • query (string): Search query
  • limit (number, optional): Maximum results, 1-100 (default: 10)
• Returns: Matching documents with relevance scores
• Note: Semantic search is a Tiptap Cloud restricted-beta feature. Self-hosted collaboration servers do not implement it; there the tool returns an explicit "not enabled on this server" error.

Markdown Conversion

These two tools call the Tiptap Conversion service (https://api.tiptap.dev by default), not the collaboration server. They require CONVERT_TOKEN (a Tiptap Cloud Convert JWT); without it they return setup guidance instead of making a request.

import-markdown

Convert Markdown content to Tiptap JSON format.

• Parameters:
  • content (string): Markdown content to convert
  • appId (string, optional): Tiptap Convert App ID
  • format (string, optional): Accepted for backwards compatibility; the v2 Conversion API has no format switch
• Returns: Converted Tiptap JSON content (plus the service's conversion logs)

export-markdown

Convert Tiptap JSON content to Markdown format.

• Parameters:
  • content (object): Tiptap JSON content to convert
  • appId (string, optional): Tiptap Convert App ID
  • format (string, optional): Accepted for backwards compatibility; the v2 Conversion API has no format switch
• Returns: Converted Markdown content

Installation

git clone <repository-url>
cd tiptap-collaboration-mcp
npm install
npm run build

Configuration

Configuration is passed as command-line arguments only (a .env file is not read).

node /path/to/build/index.js BASE_URL <url> API_TOKEN <token> [CONVERT_TOKEN <jwt>] [CONVERT_URL <url>]

Host Usage

Add this server to your Claude, Windsurf, or any other host with the relevant syntax. An example:

"tiptap-collaboration": {
  "command": "node",
  "args": [
    "/path/to/tiptap-collaboration-mcp/build/index.js",
    "BASE_URL",
    "http://localhost:8080",
    "API_TOKEN",
    "your-actual-api-token"
  ]
}

Development

npm run dev -- BASE_URL <url> API_TOKEN <token>   # run from source (tsx)
npm run inspect -- BASE_URL <url> API_TOKEN <token>   # MCP Inspector
npm run typecheck                                  # type-check src + tests
npm run format                                     # prettier
npm test                                           # unit tests (mocked fetch)
npm run test:live                                  # integration tests against a real server

The live suite is skipped unless pointed at a server:

TIPTAP_TEST_BASE_URL=http://localhost:8080 \
TIPTAP_TEST_API_TOKEN=<your API secret> \
npm run test:live

Set TIPTAP_TEST_CONVERT_TOKEN as well to exercise the conversion tools for real; without it they are asserted to return their setup guidance. The suite creates uniquely named mcp-live-* documents and deletes them afterwards.

Limitations

• Semantic search (search-documents) only works against Tiptap Cloud servers with the restricted-beta Semantic Search feature enabled — it is not part of the self-hosted collaboration server image.
• Markdown conversion requires a Tiptap Cloud Convert JWT (CONVERT_TOKEN); the conversion service is separate from the collaboration server.
• Error messages include the HTTP status and the server's X-Correlation-Id (e.g. [HTTP 404, correlation-id …]) so failures can be matched against collaboration server logs.

Resources

• ModelContextProtocol
• ModelContextProtocol SDK
• Tiptap Document management REST API
• Tiptap content injection REST API
• Tiptap collaboration server changelog / upgrade guide

License

This project is licensed under the MIT License - see the LICENSE file for details.