Local Docmost MCP

🚀 Docmost MCP Server

このサーバーは、MCP を介して、AIアシスタントがセルフホストの Docmost ドキュメントに直接アクセスできるようにするものです。

以下を含む、すべてのMCP互換クライアントで動作します。

• Claude Code / Claude Desktop
• Cursor
• Windsurf
• VS Code (GitHub Copilot)
• Cline
• Continue
• Zed

✨ 主な機能

📦 インストール

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

これにより、2つの依存関係がインストールされます。

• mcp — MCPサーバーを構築するための公式Python SDK
• requests — Docmost API呼び出し用のHTTPクライアント

3. 認証情報を設定する

サンプル設定ファイルをコピーし、詳細を入力します。

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
}

⚠️ 重要提示

config.json には機密情報が含まれており、.gitignore を通じてバージョン管理から除外されています。

4. セットアップを確認する

source venv/bin/activate   # まだアクティブでない場合

python docmost_client.py

期待される出力は以下の通りです。

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

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

スペースと検索結果が表示されれば、クライアントは正常に動作しています。

💻 使用例

すべてのスペースをリストする

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"

🔧 技術詳細

1. MCPクライアントは、サーバーをサブプロセスとして起動し、stdio（stdin/stdout）を介して通信します。
2. 最初のAPI呼び出しで、サーバーはメールアドレスとパスワードを使用してDocmostインスタンスに認証し、Set-Cookie ヘッダーから JWTトークン を受け取ります。
3. トークンは token.json にキャッシュされ、後続のリクエストで使用されます。リクエストが 401 を返した場合、サーバーは自動的に再認証してリトライします。
4. ページコンテンツはDocmostに ProseMirror JSON として保存されています。サーバーは、クライアントに返す前に、それをクリーンな Markdown（見出し、リスト、テーブル、コードブロック、画像、リンクなど）に変換します。

📚 ドキュメント

プロジェクト構造

docmost-mcp/
├── mcp_server.py         # MCPサーバー (3つのツール)
├── docmost_client.py     # Docmost APIクライアント
├── requirements.txt      # Python依存関係 (mcp, requests)
├── config.example.json   # 設定テンプレート
├── config.json           # 認証情報 (gitには含まれない)
├── token.json            # キャッシュされたJWTトークン (自動生成、gitには含まれない)
├── .gitignore
└── README.md

セキュリティ

• config.json には認証情報が含まれているため、決してgitにコミットしないでください。
• token.json にはJWTトークンが含まれているため、決してgitにコミットしないでください。
• 両方のファイルはすでに .gitignore に記載されています。

トラブルシューティング

"No authToken in response cookies"

• config.json の email と password が正しいことを確認してください。
• base_url がDocmostインスタンスを指していることを確認してください。

"Connection refused"

• Docmostインスタンスが実行中でアクセス可能であることを確認してください。
• ネットワーク接続とファイアウォールルールを確認してください。

"401 Unauthorized"

• トークンが期限切れになっている可能性があります。token.json を削除すると、次のリクエストで自動的に再作成されます。

MCPツールがクライアントに表示されない場合

• venv/bin/python と mcp_server.py への 絶対パス を使用していることを確認してください。
• 仮想環境にすべての依存関係がインストールされていることを確認してください（pip install -r requirements.txt）。
• 設定を変更した後、MCPクライアントを再起動してください。

📄 ライセンス

MIT