Docmost MCP Server

Docmost MCP服务器

一 主控程序 服务器，让AI助手直接访问您的自托管 Docmost 通过其API提供文档。

适用于任何MCP兼容客户端，包括：

• 光标
• 帆板运动
• 克莱恩
• 继续
• 泽德

特性

先决条件

• Python 3.10+
• 具有有效用户凭据的正在运行的Docmost实例
• MCP兼容客户端（克劳德代码、克劳德桌面、光标、VS代码等）

安装

1.克隆存储库

git clone https://github.com/aleksvin8888/local-docmost-mcp.git
cd docmost-mcp

2.创建虚拟环境并安装依赖项

python3 -m venv venv
source venv/bin/activate   # Linux / macOS
# venv\Scripts\activate    # Windows

pip install -r requirements.txt

这将安装核心依赖项：

• mcp --用于构建MCP服务器的官方Python SDK
• requests -用于Docmost API调用的HTTP客户端

3.使用Docker进行本地开发（可选）

如果你需要一个本地Docmost实例进行测试，你可以使用提供的Docker Compose设置：

cd container_docmost
docker compose up -d

这将启动Docmost http://localhost:3000 （港口 3001 如果在主机映射中配置）以及Postgres和Redis。

4.配置凭据

复制示例配置并填写您的详细信息：

cp config.example.json config.json

编辑 config.json:

{
  "base_url": "https://your-docmost-instance.example.com",
  "email": "your-email@example.com",
  "password": "your-password",
  "timeout": 30,
  "page_content_format": "markdown",
  "create_space_conflict_policy": "return_existing",
  "duplicate_page_conflict_policy": "auto_suffix",
  "clear_parent_on_space_move": true
}

注： config.json 包含敏感凭据，并通过以下方式从版本控制中排除 .gitignore.

4.验证设置

source venv/bin/activate   # if not already active

python docmost_client.py

预期产量：

=== Spaces ===
  My Space (my-space) - 019a2a69-...
  Another Space (another) - 019a5e21-...
  ...

=== Search 'example' ===
  Example Page Title - abc123def
  ...

如果您看到您的空格和搜索结果，则表明客户端工作正常。

连接到MCP客户端

服务器使用 标准 传输，由所有主要的MCP客户端支持。下面是最受欢迎的设置说明。

克劳德代码

选择以下选项之一。

重要提示： 使用 绝对路径 内部的Python二进制文件 venv 和 mcp_server.py.

选项1：全局配置（推荐）

添加 ~/.claude/settings.json:

{
  "mcpServers": {
    "docmost": {
      "command": "/absolute/path/to/docmost-mcp/venv/bin/python",
      "args": ["/absolute/path/to/docmost-mcp/mcp_server.py"]
    }
  }
}

选项2：项目级配置

创建 .claude/settings.json 在项目根目录中：

{
  "mcpServers": {
    "docmost": {
      "command": "/absolute/path/to/docmost-mcp/venv/bin/python",
      "args": ["/absolute/path/to/docmost-mcp/mcp_server.py"]
    }
  }
}

选项3:CLI命令

claude mcp add docmost \
  -c "/absolute/path/to/docmost-mcp/venv/bin/python" \
  -- /absolute/path/to/docmost-mcp/mcp_server.py

添加配置后，重新启动Claude Code或启动新会话。

克劳德桌面

将服务器添加到Claude Desktop配置文件中：

• Linux： ~/.config/claude/claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "docmost": {
      "command": "/absolute/path/to/docmost-mcp/venv/bin/python",
      "args": ["/absolute/path/to/docmost-mcp/mcp_server.py"]
    }
  }
}

保存配置后重新启动Claude Desktop。

光标/风帆/VS码/其他客户端

大多数MCP客户端使用相同的配置格式。使用以下命令添加服务器：

• 命令： /absolute/path/to/docmost-mcp/venv/bin/python
• Args： /absolute/path/to/docmost-mcp/mcp_server.py
• 运输： 标准

有关配置文件的确切位置和格式，请参阅客户的文档。

用法

连接MCP服务器后，您的AI助手可以使用以下工具：

列出所有空间

Show me all available documentation spaces

搜索文档

Search the documentation for "user permissions"

在特定空间内搜索

Find "API endpoints" in the Engineering space

获取特定页面

Show me the full content of page with slug_id "abc123def"

创建新空间

Create a space named "Project Phoenix" with description "Q2 launch docs"

创建页面

Create a page in space "SPACE_ID" titled "Kickoff Notes" with content "# Kickoff\n..."

更新页面（附加）

Append "## Decisions\n- ..." to page "PAGE_ID"

移动页面

Move page "PAGE_ID" under parent "PARENT_ID" and set position "after:SIBLING_ID"

注： move_page 将位置提示传递给Docmost API。如果Docmost版本需要分数索引，则可能需要调整API负载或客户端逻辑。

评论和解决

Add a comment to page "PAGE_ID": "Please review this section."
Resolve comment "COMMENT_ID" with note "Addressed in revision 3."

写入工具错误处理

• create_space：409冲突返回一个明确的错误或现有空格（请参阅 create_space_conflict_policy).
• create_page：404表示无效 space_id，400为无效 parent_page_id.
• update_page：页面缺失时为404；append/prepend需要 content.
• duplicate_page：404当源页面丢失时；冲突处理取决于 duplicate_page_conflict_policy.
• move_page：需要 new_parent_page_id 或 new_position；拒绝循环移动；无效位置返回400。
• create_comment：页面缺失时为404；401如果没有授权。
• resolve_comment：404当评论缺失时；403如果没有授权。

运作原理

1. MCP客户端将服务器作为子进程启动，并通过以下方式进行通信 标准 （标准输入/标准输出）。
2. 在第一次API调用中，服务器使用电子邮件/密码对Docmost实例进行身份验证，并接收 JWT令牌 从 Set-Cookie 头球
3. 令牌缓存在 token.json 用于后续请求。如果请求返回 401，服务器会自动重新进行身份验证并重试。
4. 页面内容以如下方式存储在Docmost中 ProseMirror JSON。服务器将其转换为clean 标记语言 （标题、列表、表格、代码块、图像、链接等），然后再将其返回给客户端。

项目结构

docmost-mcp/
├── .github/workflows/    # CI/CD pipelines (GitHub Actions)
├── container_docmost/    # Docker Compose setup for local testing
├── tests/                # Comprehensive unit test suite
├── mcp_server.py         # MCP server (11 tools)
├── docmost_client.py     # Docmost API client
├── requirements.txt      # Python dependencies
├── config.example.json   # Configuration template
├── config.json           # Your credentials (not in git)
├── token.json            # Cached JWT token (auto-generated)
├── .gitignore
└── README.md

测试和CI/CD

该项目包括一个全面的测试套件，涵盖API客户端和MCP服务器处理程序。

在本地运行测试

# Install test dependencies
pip install pytest pytest-asyncio responses coverage pytest-cov

# Run all tests
PYTHONPATH=. pytest tests/ -v

# Run tests with coverage report
PYTHONPATH=. pytest tests/ --cov=. --cov-report=term-missing

CI/CD

GitHub操作配置在 .github/workflows/ci.yml 在多个Python版本（3.10、3.11、3.12）中对每个推送和拉取请求自动运行测试。

您可以使用以下命令在本地模拟CI环境 行动:

act push -W .github/workflows/ci.yml

安全

• config.json 包含您的凭据-- 永远不要将其提交给git
• token.json 包含JWT令牌-- 永远不要将其提交给git
• 这两个文件已在中列出 .gitignore

故障排除

“响应Cookie中没有authToken”

• 核实一下 email 和 password 在 config.json 是正确的
• 核实一下 base_url 指向您的Docmost实例

“连接被拒绝”

• 检查您的Docmost实例是否正在运行且可访问
• 检查您的网络连接和防火墙规则

“401未经授权”

• 令牌可能已过期--删除 token.json 它将在下次请求时自动重新创建

MCP工具未出现在客户端中

• 确保您使用 绝对路径 到 venv/bin/python 和 mcp_server.py
• 检查虚拟环境是否安装了所有依赖项(pip install -r requirements.txt)
• 更改配置后重新启动MCP客户端

许可证

麻省理工学院