Docmost Model Context Protocol (MCP) Bridge

Introduction

The Docmost Model Context Protocol (MCP) Bridge enables AI assistants like Claude to directly interact with the Docmost documentation platform. It implements the Model Context Protocol standard to provide a consistent interface for AI models to discover and use Docmost's capabilities.

What is the Model Context Protocol?

The Model Context Protocol (MCP) is a standardized interface that allows AI models to:

1. Discover available tools and their capabilities
2. Understand parameter requirements for each tool
3. Call tools with appropriate parameters
4. Process tool responses in a consistent format

Architecture

The Docmost MCP implementation consists of three main components:

1. MCP Bridge

The MCP Bridge acts as an adapter between AI assistants and the Docmost API:

┌─────────────┐      ┌───────────────┐      ┌─────────────┐
│             │      │               │      │             │
│ AI Assistant│<────>│   MCP Bridge  │<────>│ Docmost API │
│             │      │               │      │             │
└─────────────┘      └───────────────┘      └─────────────┘
     (Claude)          (MCP Server)          (JSON-RPC API)

2. JSON-RPC API

A JSON-RPC 2.0 API that provides a uniform interface to all Docmost functionality.

3. WebSocket Events System

Real-time event system that notifies clients about changes made through the MCP API.

Getting Started

Prerequisites

1. Node.js 16 or higher
2. A Docmost instance with API key support
3. An MCP-compatible AI assistant (like Claude)

Setup

1. Clone this repository
2. Install dependencies: npm install
3. Create a .env.mcp file with the following variables:

   MCP_SERVER_URL=https://your-docmost-instance.com
   MCP_API_KEY=your_api_key
   MCP_WORKSPACE_ID=your_workspace_id
   MCP_DEBUG=false
   

4. Run the MCP bridge: npm start

Available Tools

The MCP bridge exposes the following tool categories:

Content Management

• Space Management:

  • space_create: Create a new space
  • space_list: List spaces in a workspace
  • space_update: Update a space
  • space_delete: Delete a space

• Page Management:

  • page_create: Create a new page
  • page_list: List pages in a space
  • page_update: Update a page
  • page_delete: Delete a page
  • page_move: Move a page to a different parent or space

• Comment Management:

  • comment_create: Create a comment
  • comment_list: List comments on a page
  • comment_update: Update a comment
  • comment_delete: Delete a comment

• Attachment Management:

  • attachment_upload: Upload a file attachment
  • attachment_list: List attachments for a page
  • attachment_get: Get attachment details
  • attachment_download: Download an attachment
  • attachment_delete: Delete an attachment

User Management

• user_list: List users in a workspace
• user_get: Get a user's details
• user_update: Update a user

Group Management

• group_create: Create a user group
• group_list: List groups in a workspace
• group_update: Update a group
• group_delete: Delete a group
• group_addMember: Add a user to a group
• group_removeMember: Remove a user from a group

Workspace Management

• workspace_create: Create a workspace
• workspace_list: List workspaces
• workspace_update: Update a workspace
• workspace_delete: Delete a workspace
• workspace_addMember: Add a member to a workspace
• workspace_removeMember: Remove a member from a workspace

UI Control

• ui_navigate: Navigate to a specific destination in the UI

Real-time Events

The MCP implementation includes a WebSocket component for real-time updates:

1. Server Gateway: Broadcasts events for MCP operations
2. Client Hook: Connects to the WebSocket server and updates UI based on events

Events are categorized by resource type and operation:

export enum MCPEventType {
  // Space events
  SPACE_CREATED = 'space.created',
  SPACE_UPDATED = 'space.updated',
  SPACE_DELETED = 'space.deleted',
  
  // Page events
  PAGE_CREATED = 'page.created',
  PAGE_UPDATED = 'page.updated',
  PAGE_DELETED = 'page.deleted',
  PAGE_MOVED = 'page.moved',
  
  // Comment events
  COMMENT_CREATED = 'comment.created',
  COMMENT_UPDATED = 'comment.updated',
  COMMENT_DELETED = 'comment.deleted',
  
  // UI events
  UI_NAVIGATE = 'ui.navigate',
}

Examples

Using the MCP Bridge with an AI Assistant

AI assistants like Claude can use the MCP Bridge to interact with Docmost:

// Example: AI assistant creating a new page via MCP
const result = await callTool("page_create", {
  title: "Meeting Notes",
  content: {
    type: "doc",
    content: [
      {
        type: "paragraph",
        content: [{ type: "text", text: "These are the meeting notes." }]
      }
    ]
  },
  spaceId: "space-123",
  workspaceId: "workspace-456"
});

// Result contains the created page information
console.log("Created page:", JSON.parse(result.content[0].text));

Direct API Usage

You can also use the Docmost JSON-RPC API directly:

// Example: Creating a new page via direct API call
const mcpRequest = {
  jsonrpc: "2.0",
  method: "page.create",
  params: {
    spaceId: "space-123",
    workspaceId: "workspace-456",
    title: "My New Page",
    content: {
      type: "doc",
      content: [
        {
          type: "paragraph",
          content: [{ type: "text", text: "This is the content of my new page" }]
        }
      ]
    }
  },
  id: "request-1"
};

// Sending the request with API key authentication
const response = await fetch("https://your-docmost-instance.com/api/mcp", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_key"
  },
  body: JSON.stringify(mcpRequest)
});

const result = await response.json();
// result.result will contain the created page information

API Key Authentication

The MCP Bridge uses API key authentication to securely connect to the Docmost API:

1. Create an API key in your Docmost workspace settings or via the API
2. Set the MCP_API_KEY environment variable
3. The bridge automatically includes the API key in all requests

Future Roadmap

1. Enhanced Tool Descriptions: Improve parameter descriptions for better AI understanding
2. Context Gathering: Enhance context for AI operations
3. Error Handling: More specific error messages and better error reporting
4. Schema Improvements: Consolidate schema definitions
5. Code Organization: Split large files into modules and standardize parameter handling

Contributing

Contributions to the Docmost MCP Bridge are welcome! Please check the existing issues or create new ones to discuss potential improvements.

License

The MCP implementation is part of the Docmost project and follows the same licensing terms.