docmost-mcp 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moritz Krause
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# Docmost MCP Server
+
+A Model Context Protocol (MCP) server for [Docmost](https://docmost.com/), enabling AI agents to search, create, modify, and organize documentation pages and spaces.
+
+## Features
+
+### Core Management
+
+- **`create_page`**: Smart creation tool. Creates content (via import) AND handles hierarchy (nesting under a parent) in one go.
+- **`update_page`**: Update a page's content and/or title. Updates are performed via real-time collaboration (WebSocket).
+- **`delete_page` / `delete_pages`**: Delete single or multiple pages at once.
+- **`move_page`**: Organize pages hierarchically by moving them to a new parent or root.
+
+### Exploration & Retrieval
+
+- **`search`**: Full-text search across spaces with optional space filtering (`query`, `spaceId`).
+- **`get_workspace`**: Get information about the current Docmost workspace.
+- **`list_spaces`**: View all spaces within the current workspace.
+- **`list_groups`**: View all groups within the current workspace.
+- **`list_pages`**: List pages within a space (ordered by `updatedAt` descending).
+- **`get_page`**: Retrieve full content and metadata of a specific page.
+
+### Technical Details
+
+- **Automatic Markdown Conversion**: Page content is automatically converted from Docmost's internal ProseMirror/TipTap JSON format to clean Markdown for easy agent consumption. Supports all Docmost extensions including callouts, task lists, math blocks, embeds, and more.
+- **Smart Import API**: Uses Docmost's import API to ensure clean Markdown-to-ProseMirror conversion when creating pages.
+- **Child Preservation**: The `update_page` tool creates a new page ID but effectively simulates an in-place update by reparenting existing child pages to the new version.
+- **Pagination Support**: Automatically handles pagination for large datasets (spaces, pages, groups).
+- **Filtered Responses**: API responses are filtered to include only relevant information, optimizing data transfer for agents.
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+This server requires the following environment variables to be set:
+
+- `DOCMOST_API_URL`: The full URL to your Docmost API (e.g., `https://docs.example.com/api`).
+- `DOCMOST_EMAIL`: The email address for authentication.
+- `DOCMOST_PASSWORD`: The password for authentication.
+
+## usage with Claude Desktop / generic MCP Client
+
+Add the following to your MCP configuration (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "docmost-local": {
+      "command": "node",
+      "args": ["./build/index.js"],
+      "env": {
+        "DOCMOST_API_URL": "http://localhost:3000/api",
+        "DOCMOST_EMAIL": "test@docmost.com",
+        "DOCMOST_PASSWORD": "test"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Watch mode
+npm run watch
+
+# Build
+npm run build
+```
+
+## License
+
+MIT

package/build/index.js

@@ -0,0 +1,409 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import FormData from "form-data";
+import axios from "axios";
+import { z } from "zod";
+import { filterWorkspace, filterSpace, filterGroup, filterPage, filterSearchResult, } from "./lib/filters.js";
+import { convertProseMirrorToMarkdown } from "./lib/markdown-converter.js";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { updatePageContentRealtime } from "./lib/collaboration.js";
+import { getCollabToken, performLogin } from "./lib/auth-utils.js";
+// Read version from package.json
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
+const VERSION = packageJson.version;
+const API_URL = process.env.DOCMOST_API_URL;
+const EMAIL = process.env.DOCMOST_EMAIL;
+const PASSWORD = process.env.DOCMOST_PASSWORD;
+if (!API_URL || !EMAIL || !PASSWORD) {
+    console.error("Error: DOCMOST_API_URL, DOCMOST_EMAIL, and DOCMOST_PASSWORD environment variables are required.");
+    process.exit(1);
+}
+class DocmostClient {
+    // ... [Client Implementation stays exactly the same] ...
+    client;
+    token = null;
+    constructor(baseURL) {
+        this.client = axios.create({
+            baseURL,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    async login() {
+        if (!EMAIL || !PASSWORD) {
+            throw new Error("Missing Credentials (DOCMOST_EMAIL, DOCMOST_PASSWORD)");
+        }
+        // baseURL is already set in this.client
+        const baseURL = this.client.defaults.baseURL || "";
+        // Use shared auth utility
+        this.token = await performLogin(baseURL, EMAIL, PASSWORD);
+        this.client.defaults.headers.common["Authorization"] =
+            `Bearer ${this.token}`;
+    }
+    async ensureAuthenticated() {
+        if (!this.token) {
+            await this.login();
+        }
+    }
+    /**
+     * Generic pagination handler for Docmost API endpoints
+     * @param endpoint - The API endpoint path (e.g., "/spaces", "/pages/recent")
+     * @param basePayload - Base payload object to send with each request
+     * @param limit - Items per page (min: 1, max: 100, default: 100)
+     * @returns All items collected from all pages
+     */
+    async paginateAll(endpoint, basePayload = {}, limit = 100) {
+        await this.ensureAuthenticated();
+        // Clamp limit between 1 and 100
+        const clampedLimit = Math.max(1, Math.min(100, limit));
+        let page = 1;
+        let allItems = [];
+        let hasNextPage = true;
+        while (hasNextPage) {
+            const response = await this.client.post(endpoint, {
+                ...basePayload,
+                limit: clampedLimit,
+                page,
+            });
+            const data = response.data;
+            // Handle both direct data.items and data.data.items structures
+            const items = data.data?.items || data.items || [];
+            const meta = data.data?.meta || data.meta;
+            allItems = allItems.concat(items);
+            hasNextPage = meta?.hasNextPage || false;
+            page++;
+        }
+        return allItems;
+    }
+    async getWorkspace() {
+        await this.ensureAuthenticated();
+        const response = await this.client.post("/workspace/info", {});
+        return {
+            data: filterWorkspace(response.data.data),
+            success: response.data.success,
+        };
+    }
+    async getSpaces() {
+        const spaces = await this.paginateAll("/spaces", {});
+        return spaces.map((space) => filterSpace(space));
+    }
+    async getGroups() {
+        const groups = await this.paginateAll("/groups", {});
+        return groups.map((group) => filterGroup(group));
+    }
+    async listPages(spaceId) {
+        const payload = spaceId ? { spaceId } : {};
+        const pages = await this.paginateAll("/pages/recent", payload);
+        return pages.map((page) => filterPage(page));
+    }
+    async listSidebarPages(spaceId, pageId) {
+        await this.ensureAuthenticated();
+        const response = await this.client.post("/pages/sidebar-pages", {
+            spaceId,
+            pageId,
+            page: 1,
+        });
+        return response.data?.data?.items || [];
+    }
+    async getPage(pageId) {
+        await this.ensureAuthenticated();
+        const response = await this.client.post("/pages/info", { pageId });
+        const resultData = response.data.data; // Assuming data is nested under 'data'
+        let content = resultData.content
+            ? convertProseMirrorToMarkdown(resultData.content)
+            : ""; // Default to empty string
+        // Always fetch subpages to provide context to the agent
+        let subpages = [];
+        try {
+            subpages = await this.listSidebarPages(resultData.spaceId, pageId);
+        }
+        catch (e) {
+            console.warn("Failed to fetch subpages:", e);
+        }
+        // Resolve subpages if the placeholder exists
+        if (content && content.includes("{{SUBPAGES}}")) {
+            if (subpages && subpages.length > 0) {
+                const list = subpages
+                    .map((p) => `- [${p.title}](page:${p.id})`)
+                    .join("\n");
+                content = content.replace("{{SUBPAGES}}", `### Subpages\n${list}`);
+            }
+            else {
+                content = content.replace("{{SUBPAGES}}", "");
+            }
+        }
+        return {
+            data: filterPage(resultData, content, subpages),
+            success: response.data.success,
+        };
+    }
+    /**
+     * Create a new page with title and content.
+     *
+     * Note: As long as Docmost doesn't provide a /pages/create endpoint that allows
+     * setting content directly, we must use the /pages/import workaround to create
+     * pages with initial content. This method:
+     * 1. Creates the page via /pages/import (which supports content)
+     * 2. Moves it to the correct parent if specified
+     */
+    async createPage(title, content, spaceId, parentPageId) {
+        await this.ensureAuthenticated();
+        if (parentPageId) {
+            try {
+                await this.getPage(parentPageId);
+            }
+            catch (e) {
+                throw new Error(`Parent page with ID ${parentPageId} not found.`);
+            }
+        }
+        // 1. Create content via Import (using multipart/form-data)
+        const form = new FormData();
+        form.append("spaceId", spaceId);
+        const fileContent = Buffer.from(content, "utf-8");
+        form.append("file", fileContent, {
+            filename: `${title || "import"}.md`,
+            contentType: "text/markdown",
+        });
+        const headers = {
+            ...form.getHeaders(),
+            Authorization: `Bearer ${this.token}`,
+        };
+        // Use raw axios call for FormData handling
+        const response = await axios.post(`${API_URL}/pages/import`, form, {
+            headers,
+        });
+        const newPageId = response.data.data.id;
+        // 2. Move to parent if needed
+        if (parentPageId) {
+            await this.movePage(newPageId, parentPageId);
+        }
+        // Return the final page object
+        return this.getPage(newPageId);
+    }
+    /**
+     * Update a page's content and optionally its title.
+     * Leverages WebSocket collaboration to update content without changing Page ID.
+     */
+    async updatePage(pageId, content, title) {
+        await this.ensureAuthenticated();
+        // 1. Update Title via REST API if provided
+        if (title) {
+            await this.client.post("/pages/update", { pageId, title });
+        }
+        // 2. Update Content via WebSocket
+        let collabToken = "";
+        try {
+            const baseURL = this.client.defaults.baseURL || "";
+            collabToken = await getCollabToken(baseURL, this.token);
+            await updatePageContentRealtime(pageId, content, collabToken, baseURL);
+        }
+        catch (error) {
+            console.error("Failed to update page content via realtime collaboration:", error);
+            const tokenPreview = collabToken
+                ? collabToken.substring(0, 15) + "..."
+                : "null";
+            throw new Error(`Failed to update page content: ${error.message} (Token: ${tokenPreview})`);
+        }
+        return {
+            success: true,
+            modified: true,
+            message: "Page updated successfully.",
+            pageId: pageId,
+        };
+    }
+    async search(query, spaceId) {
+        await this.ensureAuthenticated();
+        const response = await this.client.post("/search", {
+            query,
+            spaceId,
+        });
+        // Filter search results (data is directly an array)
+        const items = response.data?.data || [];
+        const filteredItems = items.map((item) => filterSearchResult(item));
+        return {
+            items: filteredItems,
+            success: response.data?.success || false,
+        };
+    }
+    async movePage(pageId, parentPageId, position) {
+        await this.ensureAuthenticated();
+        // Docmost requires position >= 5 chars.
+        const validPosition = position || "a00000";
+        return this.client
+            .post("/pages/move", {
+            pageId,
+            parentPageId,
+            position: validPosition,
+        })
+            .then((res) => res.data);
+    }
+    async deletePage(pageId) {
+        await this.ensureAuthenticated();
+        return this.client
+            .post("/pages/delete", { pageId })
+            .then((res) => res.data);
+    }
+    async deletePages(pageIds) {
+        await this.ensureAuthenticated();
+        const promises = pageIds.map((id) => this.client
+            .post("/pages/delete", { pageId: id })
+            .then(() => ({ id, success: true }))
+            .catch((err) => ({ id, success: false, error: err.message })));
+        return Promise.all(promises);
+    }
+}
+const docmostClient = new DocmostClient(API_URL);
+// --- Modern McpServer Implementation ---
+const server = new McpServer({
+    name: "docmost-mcp",
+    version: VERSION,
+});
+// Helper to format JSON responses
+const jsonContent = (data) => ({
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+});
+// Tool: list_workspaces
+server.registerTool("get_workspace", {
+    description: "Get the current Docmost workspace",
+}, async () => {
+    const workspace = await docmostClient.getWorkspace();
+    return jsonContent(workspace);
+});
+// Tool: list_spaces
+server.registerTool("list_spaces", {
+    description: "List all available spaces in Docmost",
+}, async () => {
+    const spaces = await docmostClient.getSpaces();
+    return jsonContent(spaces);
+});
+// Tool: list_groups
+server.registerTool("list_groups", {
+    description: "List all available groups in Docmost",
+}, async () => {
+    const groups = await docmostClient.getGroups();
+    return jsonContent(groups);
+});
+// Tool: list_pages
+server.registerTool("list_pages", {
+    description: "List pages in a space ordered by updatedAt (descending).",
+    inputSchema: {
+        spaceId: z.string().optional(),
+    },
+}, async ({ spaceId }) => {
+    const result = await docmostClient.listPages(spaceId);
+    return jsonContent(result);
+});
+// Tool: get_page
+server.registerTool("get_page", {
+    description: "Get details and content of a specific page by ID",
+    inputSchema: {
+        pageId: z.string(),
+    },
+}, async ({ pageId }) => {
+    const page = await docmostClient.getPage(pageId);
+    return jsonContent(page);
+});
+// Tool: create_page (Smart)
+server.registerTool("create_page", {
+    description: "Create a new page with content (automatically moves it to the correct hierarchy).",
+    inputSchema: {
+        title: z.string().describe("Title of the page"),
+        content: z.string().describe("Markdown content"),
+        spaceId: z.string(),
+        parentPageId: z
+            .string()
+            .optional()
+            .describe("Optional parent page ID to nest under"),
+    },
+}, async ({ title, content, spaceId, parentPageId }) => {
+    const result = await docmostClient.createPage(title, content, spaceId, parentPageId);
+    return jsonContent(result);
+});
+// Tool: update_page (Safe)
+server.registerTool("update_page", {
+    description: "Update a page's content and/or title via realtime collaboration (preserves Page ID and history).",
+    inputSchema: {
+        pageId: z.string().describe("ID of the page to update"),
+        content: z.string().describe("New Markdown content"),
+        title: z.string().optional().describe("Optional new title"),
+    },
+}, async ({ pageId, content, title }) => {
+    const result = await docmostClient.updatePage(pageId, content, title);
+    return jsonContent(result);
+});
+// Tool: move_page
+server.registerTool("move_page", {
+    description: "Move a page to a new parent (nesting) or root. Essential for organizing pages created via 'import_page'.",
+    inputSchema: {
+        pageId: z.string(),
+        parentPageId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Target parent page ID. Pass 'null' or empty string to move to root."),
+        position: z
+            .string()
+            .optional()
+            .describe("Optional position string (5-12 chars). Defaults to 'a00000' (end) if omitted."),
+    },
+}, async ({ pageId, parentPageId, position }) => {
+    // Ensure parentPageId is null if string "null" or empty is passed, or undefined
+    // Note: Zod handles type checking, but we double check for empty strings just in case
+    const finalParentId = parentPageId === "" || parentPageId === "null" ? null : parentPageId;
+    await docmostClient.movePage(pageId, finalParentId || null, position);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Successfully moved page ${pageId} to parent ${finalParentId || "root"}`,
+            },
+        ],
+    };
+});
+// Tool: delete_page
+server.registerTool("delete_page", {
+    description: "Delete a single page by ID.",
+    inputSchema: {
+        pageId: z.string(),
+    },
+}, async ({ pageId }) => {
+    await docmostClient.deletePage(pageId);
+    return {
+        content: [{ type: "text", text: `Successfully deleted page ${pageId}` }],
+    };
+});
+// Tool: delete_pages
+server.registerTool("delete_pages", {
+    description: "Delete multiple pages at once. Useful for cleanup.",
+    inputSchema: {
+        pageIds: z.array(z.string()),
+    },
+}, async ({ pageIds }) => {
+    const results = await docmostClient.deletePages(pageIds);
+    return jsonContent(results);
+});
+// Tool: search
+server.registerTool("search", {
+    description: "Search for pages and content.",
+    inputSchema: {
+        query: z.string().describe("Search query"),
+        spaceId: z.string().optional().describe("Optional space ID to filter by"),
+    },
+}, async ({ query, spaceId }) => {
+    const result = await docmostClient.search(query, spaceId);
+    return jsonContent(result);
+});
+async function run() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+run().catch((error) => {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+});

package/build/lib/auth-utils.js

@@ -0,0 +1,43 @@
+import axios from "axios";
+export async function getCollabToken(baseUrl, apiToken) {
+    try {
+        const response = await axios.post(`${baseUrl}/auth/collab-token`, {}, {
+            headers: {
+                Authorization: `Bearer ${apiToken}`,
+                "Content-Type": "application/json",
+            },
+        });
+        // console.error('Collab Token Response:', response.data);
+        // Response is wrapped in { data: { token: ... } }
+        return response.data.data?.token || response.data.token;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error)) {
+            throw new Error(`Failed to get collab token: ${error.response?.status} ${error.response?.statusText} - ${JSON.stringify(error.response?.data)}`);
+        }
+        throw error;
+    }
+}
+export async function performLogin(baseUrl, email, password) {
+    try {
+        const response = await axios.post(`${baseUrl}/auth/login`, {
+            email,
+            password,
+        });
+        // Extract token from Set-Cookie header
+        const cookies = response.headers["set-cookie"];
+        if (!cookies) {
+            throw new Error("No Set-Cookie header found in login response");
+        }
+        const authCookie = cookies.find((c) => c.startsWith("authToken="));
+        if (!authCookie) {
+            throw new Error("No authToken cookie found in login response");
+        }
+        const token = authCookie.split(";")[0].split("=")[1];
+        return token;
+    }
+    catch (error) {
+        console.error("Login failed:", axios.isAxiosError(error) ? error.response?.data : error.message);
+        throw error;
+    }
+}

package/build/lib/collaboration.js

@@ -0,0 +1,111 @@
+import { HocuspocusProvider } from "@hocuspocus/provider";
+import { TiptapTransformer } from "@hocuspocus/transformer";
+import * as Y from "yjs";
+import WebSocket from "ws";
+import { marked } from "marked";
+import { generateJSON } from "@tiptap/html";
+import { JSDOM } from "jsdom";
+import { tiptapExtensions } from "./tiptap-extensions.js";
+// Setup DOM environment for Tiptap HTML parsing in Node.js
+const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
+global.window = dom.window;
+global.document = dom.window.document;
+// @ts-ignore
+global.Element = dom.window.Element;
+// @ts-ignore
+global.WebSocket = WebSocket;
+// Navigator is read-only in newer Node versions and already exists
+// global.navigator = dom.window.navigator;
+export async function updatePageContentRealtime(pageId, markdownContent, collabToken, baseUrl) {
+    console.error(`Starting realtime update for page ${pageId}`);
+    console.error(`Token prefix: ${collabToken ? collabToken.substring(0, 5) : "NONE"}...`);
+    // 1. Convert Markdown to HTML
+    const html = await marked.parse(markdownContent);
+    // 2. Convert HTML to ProseMirror JSON
+    const tiptapJson = generateJSON(html, tiptapExtensions);
+    // 3. Setup Hocuspocus Provider
+    const ydoc = new Y.Doc();
+    // Construct WebSocket URL
+    // Replace protocol
+    let wsUrl = baseUrl.replace(/^http/, "ws");
+    try {
+        const urlObj = new URL(wsUrl);
+        // Remove /api suffix if present, as the websocket is mounted on root /collab
+        if (urlObj.pathname.endsWith("/api") || urlObj.pathname.endsWith("/api/")) {
+            urlObj.pathname = urlObj.pathname.replace(/\/api\/?$/, "");
+        }
+        // Set correct path to /collab
+        urlObj.pathname = urlObj.pathname.replace(/\/$/, "") + "/collab";
+        wsUrl = urlObj.toString();
+    }
+    catch (e) {
+        // Fallback if URL parsing fails
+        if (!wsUrl.endsWith("/collab")) {
+            wsUrl = wsUrl.replace(/\/$/, "") + "/collab";
+        }
+    }
+    console.error(`Connecting to WebSocket: ${wsUrl}`);
+    return new Promise((resolve, reject) => {
+        // Safety timeout
+        const timer = setTimeout(() => {
+            if (provider)
+                provider.destroy();
+            reject(new Error("Connection timeout to collaboration server"));
+        }, 25000);
+        const provider = new HocuspocusProvider({
+            url: wsUrl,
+            name: `page.${pageId}`,
+            document: ydoc,
+            token: collabToken,
+            // @ts-ignore - Required for Node.js environment
+            WebSocketPolyfill: WebSocket,
+            onConnect: () => console.error("WS Connect"),
+            onDisconnect: (data) => console.error("WS Disconnect"),
+            onClose: (data) => console.error("WS Close"),
+            onSynced: () => {
+                console.error("Connected and synced!");
+                try {
+                    // Prepare the new content in a separate doc
+                    const tempDoc = TiptapTransformer.toYdoc(tiptapJson, "default", tiptapExtensions);
+                    // Apply update
+                    ydoc.transact(() => {
+                        const fragment = ydoc.getXmlFragment("default");
+                        // 1. Clear existing content
+                        if (fragment.length > 0) {
+                            fragment.delete(0, fragment.length);
+                        }
+                        // 2. Apply new content from tempDoc
+                        // Note: applyUpdate adds content. Since we cleared, it should effectively replace.
+                        // However, applyUpdate merges structures based on IDs. tempDoc has new IDs.
+                        const update = Y.encodeStateAsUpdate(tempDoc);
+                        Y.applyUpdate(ydoc, update);
+                    });
+                    console.error("Content replaced. Returning success to user immediately (Background persistence)...");
+                    // Clear safety timeout as we are successful
+                    clearTimeout(timer);
+                    // Resolve immediately so the user doesn't have to wait
+                    resolve();
+                    // Keep connection open in background for save/sync (Docmost has 10s debounce)
+                    // The node process will keep running this timeout even after the tool returns
+                    setTimeout(() => {
+                        try {
+                            console.error(`Closing background connection for page ${pageId}`);
+                            provider.destroy();
+                        }
+                        catch (err) { }
+                    }, 15000);
+                }
+                catch (e) {
+                    clearTimeout(timer);
+                    provider.destroy();
+                    reject(e);
+                }
+            },
+            onAuthenticationFailed: () => {
+                clearTimeout(timer);
+                provider.destroy();
+                reject(new Error("Authentication failed for collaboration connection"));
+            },
+        });
+    });
+}

package/build/lib/filters.js

@@ -0,0 +1,70 @@
+/**
+ * Filter functions to extract only relevant information from API responses
+ * for better agent consumption
+ */
+export function filterWorkspace(data) {
+    return {
+        id: data.id,
+        name: data.name,
+        description: data.description,
+        defaultSpaceId: data.defaultSpaceId,
+        createdAt: data.createdAt,
+        updatedAt: data.updatedAt,
+        deletedAt: data.deletedAt,
+    };
+}
+export function filterSpace(space) {
+    return {
+        id: space.id,
+        name: space.name,
+        description: space.description,
+        slug: space.slug,
+        visibility: space.visibility,
+        createdAt: space.createdAt,
+        updatedAt: space.updatedAt,
+        deletedAt: space.deletedAt,
+    };
+}
+export function filterGroup(group) {
+    return {
+        id: group.id,
+        name: group.name,
+        description: group.description,
+        workspaceId: group.workspaceId,
+        createdAt: group.createdAt,
+        updatedAt: group.updatedAt,
+        deletedAt: group.deletedAt,
+    };
+}
+export function filterPage(page, content, subpages) {
+    return {
+        id: page.id,
+        title: page.title,
+        parentPageId: page.parentPageId,
+        spaceId: page.spaceId,
+        isLocked: page.isLocked,
+        createdAt: page.createdAt,
+        updatedAt: page.updatedAt,
+        deletedAt: page.deletedAt,
+        // Include converted markdown content if valid string (even empty)
+        ...(typeof content === "string" && { content }),
+        // Include subpages if provided
+        ...(subpages &&
+            subpages.length > 0 && {
+            subpages: subpages.map((p) => ({ id: p.id, title: p.title })),
+        }),
+    };
+}
+export function filterSearchResult(result) {
+    return {
+        id: result.id,
+        title: result.title,
+        parentPageId: result.parentPageId,
+        createdAt: result.createdAt,
+        updatedAt: result.updatedAt,
+        rank: result.rank,
+        highlight: result.highlight,
+        spaceId: result.space?.id,
+        spaceName: result.space?.name,
+    };
+}

package/build/lib/markdown-converter.js

@@ -0,0 +1,166 @@
+/**
+ * Convert ProseMirror/TipTap JSON content to Markdown
+ * Supports all Docmost-specific node types and extensions
+ */
+export function convertProseMirrorToMarkdown(content) {
+    if (!content || !content.content)
+        return "";
+    const processNode = (node) => {
+        const type = node.type;
+        const nodeContent = node.content || [];
+        switch (type) {
+            case "doc":
+                return nodeContent.map(processNode).join("\n\n");
+            case "paragraph":
+                const text = nodeContent.map(processNode).join("");
+                const align = node.attrs?.textAlign;
+                if (align && align !== "left") {
+                    return `<div align="${align}">${text}</div>`;
+                }
+                return text || "";
+            case "heading":
+                const level = node.attrs?.level || 1;
+                const headingText = nodeContent.map(processNode).join("");
+                return "#".repeat(level) + " " + headingText;
+            case "text":
+                let textContent = node.text || "";
+                // Apply marks (bold, italic, code, etc.)
+                if (node.marks) {
+                    for (const mark of node.marks) {
+                        switch (mark.type) {
+                            case "bold":
+                                textContent = `**${textContent}**`;
+                                break;
+                            case "italic":
+                                textContent = `*${textContent}*`;
+                                break;
+                            case "code":
+                                textContent = `\`${textContent}\``;
+                                break;
+                            case "link":
+                                textContent = `[${textContent}](${mark.attrs?.href || ""})`;
+                                break;
+                            case "strike":
+                                textContent = `~~${textContent}~~`;
+                                break;
+                            case "underline":
+                                textContent = `<u>${textContent}</u>`;
+                                break;
+                            case "subscript":
+                                textContent = `<sub>${textContent}</sub>`;
+                                break;
+                            case "superscript":
+                                textContent = `<sup>${textContent}</sup>`;
+                                break;
+                            case "highlight":
+                                const color = mark.attrs?.color || "yellow";
+                                textContent = `<mark style="background-color: ${color}">${textContent}</mark>`;
+                                break;
+                            case "textStyle":
+                                if (mark.attrs?.color) {
+                                    textContent = `<span style="color: ${mark.attrs.color}">${textContent}</span>`;
+                                }
+                                break;
+                        }
+                    }
+                }
+                return textContent;
+            case "codeBlock":
+                const language = node.attrs?.language || "";
+                const code = nodeContent.map(processNode).join("");
+                return "```" + language + "\n" + code + "\n```";
+            case "bulletList":
+                return nodeContent
+                    .map((item) => processListItem(item, "-"))
+                    .join("\n");
+            case "orderedList":
+                return nodeContent
+                    .map((item, index) => processListItem(item, `${index + 1}.`))
+                    .join("\n");
+            case "taskList":
+                return nodeContent.map((item) => processTaskItem(item)).join("\n");
+            case "taskItem":
+                const checked = node.attrs?.checked || false;
+                const checkbox = checked ? "[x]" : "[ ]";
+                return `- ${checkbox} ${nodeContent.map(processNode).join("\n")}`;
+            case "listItem":
+                return nodeContent.map(processNode).join("\n");
+            case "blockquote":
+                return nodeContent.map((n) => "> " + processNode(n)).join("\n");
+            case "horizontalRule":
+                return "---";
+            case "hardBreak":
+                return "\n";
+            case "image":
+                const imgAlt = node.attrs?.alt || "";
+                const imgSrc = node.attrs?.src || "";
+                const imgCaption = node.attrs?.caption || "";
+                return `![${imgAlt}](${imgSrc})${imgCaption ? `\n*${imgCaption}*` : ""}`;
+            case "video":
+                const videoSrc = node.attrs?.src || "";
+                return `🎥 [Video](${videoSrc})`;
+            case "youtube":
+                const youtubeUrl = node.attrs?.src || "";
+                return `📺 [YouTube Video](${youtubeUrl})`;
+            case "table":
+                return nodeContent.map(processNode).join("\n");
+            case "tableRow":
+                return "| " + nodeContent.map(processNode).join(" | ") + " |";
+            case "tableCell":
+            case "tableHeader":
+                return nodeContent.map(processNode).join("");
+            case "callout":
+                const calloutType = node.attrs?.type || "info";
+                const calloutContent = nodeContent.map(processNode).join("\n");
+                return `:::${calloutType.toLowerCase()}\n${calloutContent}\n:::`;
+            case "details":
+                return nodeContent.map(processNode).join("\n");
+            case "detailsSummary":
+                const summaryText = nodeContent.map(processNode).join("");
+                return `<details>\n<summary>${summaryText}</summary>\n`;
+            case "detailsContent":
+                const detailsText = nodeContent.map(processNode).join("\n");
+                return `${detailsText}\n</details>`;
+            case "mathInline":
+                const inlineMath = node.attrs?.text || "";
+                return `$${inlineMath}$`;
+            case "mathBlock":
+                const blockMath = node.attrs?.text || "";
+                return `$$\n${blockMath}\n$$`;
+            case "mention":
+                const mentionLabel = node.attrs?.label || node.attrs?.id || "";
+                return `@${mentionLabel}`;
+            case "attachment":
+                const attachmentName = node.attrs?.fileName || "attachment";
+                const attachmentUrl = node.attrs?.src || "";
+                return `📎 [${attachmentName}](${attachmentUrl})`;
+            case "drawio":
+                return `📊 [Draw.io Diagram]`;
+            case "excalidraw":
+                return `✏️ [Excalidraw Drawing]`;
+            case "embed":
+                const embedUrl = node.attrs?.src || "";
+                return `🔗 [Embedded Content](${embedUrl})`;
+            case "subpages":
+                return "{{SUBPAGES}}";
+            default:
+                // Fallback: process children
+                return nodeContent.map(processNode).join("");
+        }
+    };
+    const processListItem = (item, prefix) => {
+        const itemContent = item.content || [];
+        const lines = itemContent.map(processNode);
+        return lines
+            .map((line, i) => i === 0 ? `${prefix} ${line}` : `  ${line}`)
+            .join("\n");
+    };
+    const processTaskItem = (item) => {
+        const checked = item.attrs?.checked || false;
+        const checkbox = checked ? "[x]" : "[ ]";
+        const itemContent = item.content || [];
+        const text = itemContent.map(processNode).join("");
+        return `- ${checkbox} ${text}`;
+    };
+    return processNode(content).trim();
+}

package/build/lib/tiptap-extensions.js

@@ -0,0 +1,18 @@
+import StarterKit from "@tiptap/starter-kit";
+import Image from "@tiptap/extension-image";
+import Link from "@tiptap/extension-link";
+// Define extensions compatible with standard Markdown features
+// We use the default Tiptap extensions to handle basic content
+export const tiptapExtensions = [
+    StarterKit.configure({
+        // Explicitly enable features that might be disabled in some contexts
+        codeBlock: {},
+        heading: {},
+    }),
+    Image.configure({
+        inline: true,
+    }),
+    Link.configure({
+        openOnClick: false,
+    }),
+];

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "docmost-mcp",
+  "version": "1.0.1",
+  "description": "A Model Context Protocol (MCP) server for Docmost, allowing AI agents to manage documentation spaces and pages.",
+  "main": "build/index.js",
+  "bin": {
+    "docmost-mcp": "build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "start": "node build/index.js",
+    "watch": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector --config mcp_config.json"
+  },
+  "keywords": [
+    "mcp",
+    "docmost",
+    "documentation",
+    "ai",
+    "agent"
+  ],
+  "author": "Moritz Krause",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@hocuspocus/provider": "^3.4.4",
+    "@hocuspocus/transformer": "^3.4.4",
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@tiptap/core": "^3.18.0",
+    "@tiptap/extension-image": "^3.18.0",
+    "@tiptap/extension-link": "^3.18.0",
+    "@tiptap/html": "^3.18.0",
+    "@tiptap/starter-kit": "^3.18.0",
+    "@types/jsdom": "^27.0.0",
+    "axios": "^1.6.0",
+    "form-data": "^4.0.0",
+    "jsdom": "^27.4.0",
+    "marked": "^17.0.1",
+    "ws": "^8.19.0",
+    "yjs": "^13.6.29",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/form-data": "^2.5.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}