Docmost Oss MCP Shim

Docmost OSS MCP垫片

AI代理之间的轻量级Node.js桥梁（如 光标, Claude桌面版，或任何模型上下文协议工具）和您的 自托管Docmost OSS实例.

✨ 特性

• 🔌 即插即用MCP集成 -适用于Cursor、Claude Desktop和任何兼容MCP的AI代理
• 🐳 Docker就绪 -在任何平台上使用Docker Compose在几秒钟内部署
• 🥧 Raspberry Pi兼容 -在ARM设备上运行良好
• 🔒 安全 -API密钥认证和会话管理
• 🔍 全文检索 -从IDE中搜索文档
• 📚 空间管理 -列出并浏览所有Docmost空间
• 🚀 自动身份验证 -自动处理Docmost登录和cookie管理
• 📦 对Docmost的零依赖 -适用于任何自托管的Docmost OSS实例（v0.23+）

______________________________________________________________________

🤖 适用于MCP用户（AI代理）

使用光标快速入门

将此添加到您的Cursor MCP配置中(~/.cursor/mcp.json):

{
  "mcpServers": {
    "docmost": {
      "command": "npx",
      "args": ["-y", "--package=github:dJPoida/docmost-oss-mcp-shim#v0.5.0", "docmost-mcp"],
      "env": {
        "MCP_DOCMOST_SHIM_URL": "http://YOUR_SHIM_SERVER_IP:3888",
        "MCP_SHIM_KEY": "your-secure-random-string"
      }
    }
  }
}

配置：

• 替换 YOUR_SHIM_SERVER_IP 使用您的垫片服务器（例如Raspberry Pi）的IP地址
• 替换 your-secure-random-string 同样的 SHIM_API_KEY 在您的垫片服务器上配置
• 更新版本标签(#v0.5.0)以匹配最新版本

可用工具

您的AI代理可以使用这些Docmost工具：

• docmost_listSpaces -列出可用工作区/空间
• docmost_search -按查询搜索页面（支持可选 spaceId，分页）
• docmost_getPage -获取包括附件和图表在内的完整页面内容✅ 新
• docmost_getSpacePages -获取特定空间中的所有页面✅ 新
• docmost_getAttachment -获取附件内容，包括draw.io图表✅ 新
• docmost_getPageHistory -获取页面版本历史和演变✅ 新
• docmost_getPageBreadcrumbs -获取页面层次结构和导航上下文✅ 新
• docmost_getComments -在页面上获取评论和讨论✅ 新
• docmost_health -检查垫片服务器运行状况

可用资源

浏览您的Docmost文档层次结构：

• docmost://spaces -所有可用空间列表
• docmost://all-pages -所有空间中所有页面的完整概述✅ 新
• docmost://space/{spaceId} -特定空间内的页面
• docmost://page/{pageId} -单个页面元数据

可用提示

获取文档查找的指导性帮助：

• search-docs -有效文档搜索的最佳实践

✅ 增强功能（v0.5.0+）

主要更新：全页面内容访问！ 此集成现在支持：

✅ 什么有效：

• 列出空间及其元数据
• 搜索页面并查看内容亮点/片段（带分页）
• 🆕 阅读整页内容，包括文本、标题和嵌入内容
• 🆕 访问draw.io图表和其他嵌入式附件
• 🆕 下载实际附件内容（SVG、图像、文件）
• 🆕 在空间内浏览完整的页面层次结构
• 🆕 获取附件元数据和引用
• 🆕 访问页面版本历史并跟踪文档演变
• 🆕 了解页面层次结构和导航上下文
• 🆕 阅读评论和讨论以获取更多背景信息
• 🆕 一次获取所有文档的全面概述
• 通过MCP资源浏览页面层次结构
• 获取文档查找的指导提示
• 缓存响应以提高性能
• 具有指数回退的自动重试，以实现网络弹性

❌ 此MCP不能做什么（只读设计）：

• 创建或修改页面
• 更新页面内容或元数据
• 管理用户、空间或权限
• 任何行政职能

该MCP被设计为 只读文档访问工具 对于AI代理。它提供了对文档内容、结构和上下文的全面访问，同时与行政职能保持了明确的分离。所有内容编辑都必须在Docmost UI中手动完成。

游标用法示例

只需问Cursor自然语言问题，它就会自动使用Docmost工具：

• “在我的Docmost中搜索部署文档”
• “列出我的所有Docmost空间”
• “显示带有draw.io图的环境概述页面”
• “获取环境空间中的所有页面”
• “给我一个所有文档页面的概述”
• “从环境概述页面下载draw.io图表”
• “显示环境概述页面的版本历史记录”
• “获取此页面的面包屑和层次结构”
• “显示对此文档的任何评论或讨论”
• “查找有关环境变量的页面”

Cursor将发现您的文档，并帮助您在不离开IDE的情况下导航它！

______________________________________________________________________

🛠️ 适用于Shim服务器操作员

🚀 为什么存在

Docmost的开源版本不公开API密钥或外部自动化功能。\ 这个填充程序通过充当AI代理和Docmost实例之间经过身份验证的桥梁来填补这一空白。

✅ 无需企业许可证\ ✅ 无需手动管理cookie\ ✅ 用于AI代理的简单REST API\ ✅ 生产就绪的Docker部署\ ✅ 适用于Raspberry Pi和ARM设备

⚙️ 设置

1.️⃣ 需求

• 节点 v22+
• 跑步自托管 Docmost OSS 实例（Docker或裸机）
• 垫片的Docmost用户帐户（例如。 my.docmost.mcp.user@gmail.com)

2.️⃣ 安装

git clone https://github.com/dJPoida/docmost-oss-mcp-shim.git
cd docmost-oss-mcp-shim
npm install

3.️⃣ 配置

创建一个 .env 项目根目录中的文件：

# Docmost Connection (Required)
DOCMOST_BASE_URL=http://your-docmost-server:3000
DOCMOST_EMAIL=your-mcp-user@example.com
DOCMOST_PASSWORD=your-secure-password

# Shim Network Settings (Optional)
HOST=0.0.0.0  # Use 0.0.0.0 for Docker, 127.0.0.1 for local-only
PORT=3888

# Security (Required for remote access)
SHIM_API_KEY=your-secure-random-string

# Debug Logging (Optional)
DEBUG_SHIM=0  # Set to 1 for verbose logging

# Cache Settings (Optional)
CACHE_SPACES_TTL=300      # Spaces cache TTL in seconds (default: 5 minutes)
CACHE_SEARCH_TTL=120      # Search cache TTL in seconds (default: 2 minutes)
CACHE_MAX_ENTRIES=100     # Maximum cache entries (default: 100)

# Retry Settings (Optional)
RETRY_MAX_ATTEMPTS=3       # Maximum retry attempts (default: 3)
RETRY_MIN_TIMEOUT=1000     # Minimum retry timeout in ms (default: 1s)
RETRY_MAX_TIMEOUT=30000    # Maximum retry timeout in ms (default: 30s)

重要提示：

• 为垫片创建一个专用的Docmost用户（不要使用您的个人帐户）
• 使用 HOST=0.0.0.0 Docker部署允许外部连接
• 为生成强随机字符串 SHIM_API_KEY 生产中

▶️ 跑

npm start

然后验证：

curl http://127.0.0.1:3888/health
# → {"ok":true}

🧠 运作原理

所有Docmost端点都使用 发布 请求背后 /api/*.\ 垫片反映了这种行为，并自动管理会话Cookie。

身份验证是通过 authToken cookie发布者 /api/auth/login.\ 填充程序会自动登录，并在会话过期时刷新会话。

🔒 安全

• 不要 将此服务器暴露到公共互联网。\

将其绑定到localhost或反向代理后面。

• 使用 专用Docmost帐户 为了实现自动化。
• 保护 .env 档案；它包含登录凭据。
• 启用 SHIM_API_KEY 如果你希望外部工具连接。

______________________________________________________________________

🧪 测试端点

# Health check
curl http://127.0.0.1:3888/health

# Detailed health check (includes Docmost connectivity)
curl http://127.0.0.1:3888/health/detailed | jq .

# List spaces
curl -H "X-SHIM-KEY: change-this-long-random-string"      http://127.0.0.1:3888/spaces | jq .

# Search for pages (with pagination)
curl -X POST -H "Content-Type: application/json"      -H "X-SHIM-KEY: change-this-long-random-string"      -d '{"query": "Docmost", "page": 1, "limit": 20}'      http://127.0.0.1:3888/search | jq .

# Get pages in a space
curl -H "X-SHIM-KEY: change-this-long-random-string"      http://127.0.0.1:3888/spaces/YOUR_SPACE_ID/pages | jq .

# Get specific page metadata
curl -H "X-SHIM-KEY: change-this-long-random-string"      http://127.0.0.1:3888/pages/YOUR_PAGE_ID | jq .

# Create new page
curl -X POST -H "Content-Type: application/json"      -H "X-SHIM-KEY: change-this-long-random-string"      -d '{"spaceId": "YOUR_SPACE_ID", "title": "MCP Test Page", "content": "Hello world"}'      http://127.0.0.1:3888/pages | jq .

# Update page
curl -X PUT -H "Content-Type: application/json"      -H "X-SHIM-KEY: change-this-long-random-string"      -d '{"pageId": "YOUR_PAGE_ID", "title": "MCP Test Page (Updated)"}'      http://127.0.0.1:3888/pages | jq .

# Debug current session / cookies / cache stats
curl http://127.0.0.1:3888/debug/session | jq .

______________________________________________________________________

🧑‍💻 发展

npm run build     # compile TypeScript and bundle MCP server with dependencies
npm run lint      # run ESLint on TypeScript and JavaScript files
npm run format    # format with Prettier
npm run dev       # development mode with auto-rebuild
npm run dev:watch # watch mode for development
DEBUG_SHIM=1 npm start  # enable verbose logging

注： MCP服务器和Express服务器都是用TypeScript编写的。构建过程编译TypeScript，并将MCP服务器与所有依赖项捆绑在一起，以实现npx兼容性。预提交钩子会自动构建并将编译后的文件包含在提交中。

MCP服务器捆绑

MCP服务器使用 esb构建捆绑 以确保与 npx 从GitHub包执行：

• 问题: npx 从GitHub下载时不安装依赖项，导致模块解析错误
• 解决方案：将MCP SDK和所有依赖项捆绑到一个JavaScript文件中
• 结果：捆绑版本(docmostServer.bundle.js)与无缝协作 npx 无需单独安装依赖项

构建过程：

1. TypeScript编译(tsc)-将源代码编译为JavaScript
2. esb构建捆绑(scripts/bundle-mcp.js)-捆绑MCP SDK和依赖项
3. 最终输出： dist/mcp/docmostServer.bundle.js -包含所有内容的单个文件

这确保了用户可以通过以下方式运行MCP服务器 npx 没有任何依赖性问题。

发布新版本

自动版本缓冲

每次提交时，项目都会自动更新补丁版本：

• 每一个承诺 自动调整补丁版本（0.2.9→0.2.10）
• 适用于任何git工具 -IDE侧边栏、命令行等。
• 创建标签 准备发布时：

  npm run tag  # Creates git tag from current version
  git push --tags  # Push tags to remote

手册版本管理

对于主要/次要版本更改：

1. 手动更新版本 在 package.json （例如，0.2.7→ 0.3.0)
2. 提交并标记:

   git commit -am "commit message"
   git tag 
   git push && git push --tags

MCP用户更新

新版本发布后，MCP用户可以将其Cursor配置更新为最新版本标签：

{
  "mcpServers": {
    "docmost": {
      "command": "npx",
      "args": ["-y", "--package=github:dJPoida/docmost-oss-mcp-shim#v0.2.27", "docmost-mcp"]
    }
  }
}

项目结构

src/
  server/            # Express shim server (runs on remote machine)
    server.ts        # Main server entry point
    routes.ts        # defines REST endpoints
    docmostClient.ts # handles login, cookies, API calls
    logger.ts        # lightweight debug logger
    cache.ts         # LRU cache implementation
    types.ts         # shared TypeScript interfaces
  mcp/               # MCP server TypeScript source
    docmostServer.ts # MCP server implementation

scripts/
  bundle-mcp.js      # esbuild bundling script for MCP server

dist/
  server/            # Compiled Express server
  mcp/               # Compiled MCP server files
    docmostServer.js           # Original compiled MCP server
    docmostServer.bundle.js    # Bundled MCP server with dependencies (used by npx)

双服务器架构：

• Express Shim服务器 (src/server/)-在远程机器上运行，连接到Docmost OSS
• MCP服务器 (src/mcp/)-在开发人员的计算机上运行，连接到Express垫片

______________________________________________________________________

🐳 Docker部署

使用Docker Compose（推荐）

1. 创建一个 .env 文件 使用您的Docmost证书：

   DOCMOST_BASE_URL=http://your-docmost-server:3000
   DOCMOST_EMAIL=your-mcp-user@example.com
   DOCMOST_PASSWORD=your-secure-password
   SHIM_API_KEY=change-this-long-random-string
   DEBUG_SHIM=0

1. 启动服务:

   docker-compose up -d

1. 检查日志:

   docker-compose logs -f

1. 停止服务:

   docker-compose down

使用Docker CLI

# Build the image
docker build -t docmost-oss-mcp-shim .

# Run the container
docker run -d \
  --name docmost-mcp-shim \
  --restart unless-stopped \
  -p 3888:3888 \
  -e DOCMOST_BASE_URL=http://your-docmost-server:3000 \
  -e DOCMOST_EMAIL=your-mcp-user@example.com \
  -e DOCMOST_PASSWORD=your-secure-password \
  -e SHIM_API_KEY=change-this-long-random-string \
  docmost-oss-mcp-shim

Raspberry Pi部署

Docker镜像是多拱形的，适用于Raspberry Pi（ARM）：

# On your Raspberry Pi
git clone https://github.com/dJPoida/docmost-oss-mcp-shim.git
cd docmost-oss-mcp-shim

# Create .env file with your settings
cat > .env |MCP Protocol| B
  B -->|HTTP + X-SHIM-KEY| C
  C -->|Cached/Retry| E
  E -->|authToken cookie| D