Docmost OSS MCP桥接工具

{
  "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"
      }
    }
  }
}

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

# 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)

npm start

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

{
  "items": [],
  "meta": {
    "limit": 20,
    "hasNextPage": true,
    "hasPrevPage": false,
    "nextCursor": "opaque-cursor-token",
    "prevCursor": null
  }
}

# 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 (cursor pagination)
curl -X POST -H "Content-Type: application/json"      -H "X-SHIM-KEY: change-this-long-random-string"      -d '{"query": "Docmost", "limit": 20}'      http://127.0.0.1:3888/search | jq .

# Search next page (use nextCursor from previous response)
curl -X POST -H "Content-Type: application/json"      -H "X-SHIM-KEY: change-this-long-random-string"      -d '{"query": "Docmost", "limit": 20, "cursor": "YOUR_NEXT_CURSOR"}'      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

{
  "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)

# 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

# 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 << EOF
DOCMOST_BASE_URL=http://your-docmost-server:3000
DOCMOST_EMAIL=your-mcp-user@example.com
DOCMOST_PASSWORD=your-secure-password
SHIM_API_KEY=$(openssl rand -hex 32)
DEBUG_SHIM=0
EOF

# Start the service
docker-compose up -d

# Check status
docker-compose ps
docker-compose logs -f

# Cache settings
CACHE_SPACES_TTL=300      # 5 minutes
CACHE_SEARCH_TTL=120      # 2 minutes
CACHE_MAX_ENTRIES=100

# Retry settings
RETRY_MAX_ATTEMPTS=3
RETRY_MIN_TIMEOUT=1000
RETRY_MAX_TIMEOUT=30000

flowchart LR
  subgraph A[AI Agent / Cursor MCP]
    X1["docmost_search()"]
    X2["docmost_createPage()"]
    X3["MCP Resources"]
    X4["MCP Prompts"]
  end

  subgraph B[MCP Server TypeScript]
    M1["docmost_search"]
    M2["docmost_createPage"]
    M3["docmost_listSpaces"]
    M4["Resources & Prompts"]
  end

  subgraph C[Express Shim Server]
    S1["/search (POST)"]
    S2["/pages (POST/PUT)"]
    S3["/spaces (GET)"]
    S4["/spaces/:id/pages (GET)"]
    S5["/pages/:id (GET)"]
    S6["/health/detailed (GET)"]
  end

  subgraph D[Docmost OSS Server]
    D1["/api/search"]
    D2["/api/pages/create"]
    D3["/api/spaces"]
  end

  subgraph E[Cache Layer]
    E1["LRU Cache"]
    E2["Retry Logic"]
  end

  A -->|MCP Protocol| B
  B -->|HTTP + X-SHIM-KEY| C
  C -->|Cached/Retry| E
  E -->|authToken cookie| D