内容
# 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://tiptap.dev/docs/conversion/getting-started/overview) (`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
```bash
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).
| Argument | Required | Description |
| --------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `BASE_URL` | Yes | Base URL of your Tiptap collaboration server; the server exits without it. A trailing slash is fine. |
| `API_TOKEN` | Recommended | The collaboration server's API secret, sent as-is in the `Authorization` header (Tiptap's legacy auth). Most operations fail without it. |
| `CONVERT_TOKEN` | Optional | Tiptap Cloud Convert JWT for `import-markdown` / `export-markdown`. |
| `CONVERT_URL` | Optional | Conversion service base URL (default: `https://api.tiptap.dev`). |
```bash
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:
```json
"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
```bash
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:
```bash
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](https://modelcontextprotocol.io)
- [ModelContextProtocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Tiptap Document management REST API](https://tiptap.dev/docs/collaboration/documents/rest-api)
- [Tiptap content injection REST API](https://tiptap.dev/docs/collaboration/documents/content-injection)
- [Tiptap collaboration server changelog / upgrade guide](https://tiptap-suite.notion.site/Upgrade-Guide-a553322f83eb402e968738540ec4130f)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
