DocsMint

DocsMint MCP サーバー

AI エージェントに永続的なプロジェクト知識を提供します。ハイブリッド検索、再ランキング、GraphRAG、スコープ付きアクセスを使って、ドキュメントを検索、閲覧、作成、整理できます。

DocsMint Cloud を推奨します： Streamable HTTP 経由で https://docsmint.com/mcp に接続してください。サーバーのデプロイは不要です。高度なセルフホスト構成にする場合は、独自の DocsMint API を実行し、独自の API キーで docsmint-mcp stdio ブリッジに接続してください。このブリッジは TypeScript SDK および CLI とともに @hiai-gg/docsmint に同梱されています。

オプション A — DocsMint Cloud（推奨）

DocsMint Cloud に接続から開始してください。セルフホストサーバーやローカル MCP プロセスは不要です。

1. DocsMint アカウントを新規登録するか、既存のアカウントにログインします。
2. ワークスペースを選択し、プランにホスト型 MCP が含まれていることを確認します。
3. OAuth 対応クライアントの場合は、ブラウザーで認証し、ワークスペースと明示的なスコープへのアクセスに同意します。API キー対応クライアントの場合は、認証済み UI で MCP/API 認証情報を作成します。ワークスペースに紐付けられたアクセス、またはカテゴリをスコープとしたアクセスを推奨します。
4. MCP クライアントを選択し、接続手順に従います。
5. initialize と許可されたツール呼び出しを使って接続を確認します。

OAuth 対応クライアントも同じホスト URL を使用します。認証されていないリクエストは、/.well-known/oauth-protected-resource/mcp へのリンクを含む 401 と WWW-Authenticate を返します。このリソースメタデータは /.well-known/oauth-authorization-server を参照します。現在のホスト型認証とクライアント接続方法については、DocsMint Cloud セットアップガイドを参照してください。

現在の認証メタデータでは、code レスポンスタイプ、authorization_code グラントのみ、トークンエンドポイントでのクライアント認証なし、S256 を使用する PKCE が示されています。トークンエンドポイントは認証コードを交換しますが、リフレッシュトークンを発行しません。

認証には、既存の DocsMint アカウントとブラウザーでの同意を使用し、認証コードグラントと必須の PKCE S256 を適用します。同意によって、選択したワークスペース、任意のカテゴリ、および要求された mcp:read、mcp:edit、mcp:write スコープにアクセスが紐付けられます。不透明なベアラートークンはホスト型 MCP リソースに紐付けられ、有効期限は 1 時間で、ブラウザー UI から取り消すことができます。リフレッシュトークンは発行されないため、期限切れ後は再認証してください。これは DocsMint Cloud の機能であり、stdio npm ブリッジによってインストールされる OAuth サーバーではありません。

API キー対応クライアントは、Authorization: Bearer <key> を使用して https://docsmint.com/mcp に接続します。認証情報の作成、変更、取り消しはブラウザーセッションによって管理されます。MCP/API 認証情報から認証情報を作成したり、権限を昇格させたりすることはできません。

export HIAI_DOCS_API_KEY="your-global-or-category-key"

codex mcp add docsmint \
  --url https://docsmint.com/mcp \
  --bearer-token-env-var HIAI_DOCS_API_KEY

汎用 HTTP クライアントは、Authorization: Bearer <key> を指定して https://docsmint.com/mcp に接続してください。ワークスペースに紐付けられたキーには追加のヘッダーは不要です。紐付けられていないキーでは、ドキュメントに記載されている X-Docsmint-Workspace スラッグを指定できます。

オプション B — セルフホスト型 stdio ブリッジ（上級者向け）

公開されている MCP バイナリは、すでに実行中の DocsMint API に接続します。パッケージをインストールしても DocsMint 自体はデプロイされません。

まず DocsMint を実行し、認証済みブラウザー UI で API キーを作成します。次に、HIAI_DOCS_URL にデプロイ先の API URL を、HIAI_DOCS_API_KEY にそのキーを設定してから、stdio ブリッジを起動します。MCP エンドポイントとして /api/health の URL を使用しないでください。このブリッジは、そのベアラー API キーで独自の DocsMint API に対して認証を行います。DocsMint Cloud の OAuth 認証サーバーをインストールしたり、公開したりすることはありません。

Bun で実行

bunx --package @hiai-gg/docsmint docsmint-mcp

NPX で実行

npx --yes --package @hiai-gg/docsmint docsmint-mcp

ローカルチェックアウトから実行

git clone https://github.com/HiAi-gg/docsmint.git
cd docsmint
bun install --frozen-lockfile
bun run packages/mcp-server/src/index.ts

3 つの方法はいずれも、@hiai-gg/docsmint の同じ stdio サーバーを実行します。

クライアント設定

{
  "mcpServers": {
    "docsmint": {
      "command": "npx",
      "args": ["--yes", "--package", "@hiai-gg/docsmint", "docsmint-mcp"],
      "env": {
        "HIAI_DOCS_URL": "http://localhost:50700",
        "HIAI_DOCS_API_KEY": "your-global-or-category-key"
      }
    }
  }
}

HIAI_DOCS_URL のデフォルト値は http://localhost:50700 です。任意の API キーはベアラートークンとして送信されます。カテゴリに紐付けられたエージェントにはカテゴリキーを、信頼されたオーナー全体の自動化にはグローバルキーを使用してください。カテゴリの read、edit、write スコープは階層型ではなく、それぞれ明示的に設定します。公開するツールに必要な組み合わせを設定してください。

Glama サーバーの登録

Glama MCP サーバーディレクトリに、DocsMint リポジトリのこのオープンソースの stdio ブリッジを登録してください。上記の NPX コマンドで起動します（公開済みバイナリを実行するには Bun のインストールが必要です）。稼働中で到達可能な DocsMint API の URL を HIAI_DOCS_URL に、ツールに必要な権限を持つシークレットの API キーを HIAI_DOCS_API_KEY に指定してください。ホストされた Glama プロセスを利用するには、両方の値が必須です。デフォルトの localhost URL は Glama 自身の環境を指しており、API を指すものではありません。API にアクセスできなくても、プロセスはツール、プロンプト、リソースを公開できますが、ドキュメントの操作には到達可能な API と有効なキーが必要です。Glama のホストされたコネクターは DocsMint Cloud の https://docsmint.com/mcp を使用する別個の登録です。

MCP の機能

ツール

DocsMint は 22 個の MCP ツールを公開します。従来の 31 個の操作も引き続き利用できます。グループ化されたツールでは、mode、view、kind、または action の明示的な指定が必要です。これにより、エージェントが閲覧と検索、バージョンの復元とゴミ箱からの復元、取り消し可能な削除と完全な消去を混同しないようにします。2 つ目のツールカタログや旧式のツールカタログは公開されません。古いツール名を呼び出す MCP クライアントを移行する場合は、セルフホスト型ブリッジまたは Cloud エンドポイントの適合するバージョンを使用してください。

リソースと目的に応じてツールを選択してください。save_* は 1 つのドキュメント、フォルダー、カテゴリ、またはタグを作成または更新し、delete_* は文書化されたルールに従って 1 つのリソースを削除します。1 つのドキュメントを操作する場合は、対応する単一ドキュメント用ツールを優先してください。複数の明示的に選択したドキュメントに対して、同じ配置、タグ付け、ゴミ箱への移動、復元、またはインデックス作成の操作が必要な場合は、batch_documents を使用してください。自動化との互換性のため、ID を 1 つだけ指定できますが、処理は順次実行され、一部のみ成功する場合があります。ID の検索、任意の更新、バージョンの復元、完全な消去はできません。読み取り専用の閲覧、グラフの探索、バージョン履歴、ゴミ箱の確認、インデックスのステータスは、それぞれ独立した目的のままであり、並行する CRUD ツール群は追加されません。スナップショットは新しい不変の履歴エントリであるため、create_snapshot では create を使用します。save_* リソースのように既存のスナップショットを更新することはできません。

• find_documents：mode=listでフォルダー／タグのUUIDから参照するか、mode=searchでテキスト／タグ名からハイブリッド検索します。
• read_document：view=detailで内容とメタデータを読み取るか、view=markdownでMarkdownをエクスポートするか、view=versionsでリビジョンとスナップショットを一覧表示します。
• save_document：action=createでドキュメントを作成するか、action=updateで既存のドキュメントにパッチを適用します。省略されたパッチフィールドは変更されません。配置にnullを指定すると、その配置が解除されます。APIは有効なカテゴリを適用し、インデックス作成をスケジュールします。
• delete_document：内容やバージョンを削除せずに、ドキュメントをゴミ箱に移動します。
• list_workspace_structure：kind=folders|categories|tagsでフォルダー、カテゴリ、タグを一覧表示します。フォルダーの場合は、任意でparentIdを指定できます。
• save_folder：action=createでフォルダーを作成するか、action=updateで名前の変更、移動、並べ替えを行います。メタデータを変更すると、再インデックス作成がキューに追加されます。
• delete_folder：APIのフォルダー切り離しルールに従って、その中のドキュメントを保持しながらフォルダーを削除します。
• save_category：action=createでカテゴリを作成するか、action=updateで名前の変更／並べ替えを行います。ワークスペース全体への書き込みアクセスが必要です。
• delete_category：カテゴリを削除し、そのドキュメントを切り離します。ワークスペース全体への書き込みアクセスが必要です。
• save_tag：action=createでタグを作成するか、action=updateで名前の変更／色の変更を行います。ワークスペース全体への書き込みアクセスが必要です。
• delete_tag：ドキュメントを削除せずに、タグとその割り当てを削除します。
• set_document_tag：action=addでタグを割り当てるか、action=removeで割り当てを解除します。ドキュメントへの編集アクセスが必要です。
• create_snapshot：現在のドキュメント内容の名前付きバージョンを保存します。
• restore_document_version：read_document(view=versions)で選択したリビジョンまたはスナップショットから内容を復元します。そのドキュメントのUUIDをdocumentIdとして渡します。
• explore_graph：mode=neighborsで1つのドキュメントをたどるか、mode=searchでシードIDから関連性を順位付けします。
• get_document_index_status：インデックス作成の状態を確認します。作業は開始しません。
• refresh_document_index：状態を確認した後、明示的な非同期再試行をキューに追加します。
• list_trash：アクティブなスコープで表示可能な、論理削除されたドキュメントを一覧表示します。
• restore_trashed_document：論理削除されたドキュメントを復元します。以前のバージョンは復元されません。
• permanently_delete_document：ユーザーから明示的な要求があった場合に、すでにゴミ箱にあるドキュメントを取り消し不能な形で完全に削除します。
• batch_documents：明示的に指定した1～25件のドキュメントIDに対して、移動、カテゴリの設定、1つのタグの追加／削除、ゴミ箱への移動、復元、インデックスの再作成のいずれか1つの操作を適用します。複数のIDにはこちらを優先し、IDが1つの場合は対応する単一ドキュメント用ツールを使用してください。結果には各IDの成功または失敗が示されます。一部だけ成功する場合があります。ドキュメントを完全に削除することはありません。
• get_workspace_item：UUIDを指定して、表示可能なフォルダー、カテゴリ、タグを1つ読み取ります。カテゴリとタグは権限で絞り込まれた一覧全体から選択されます。アクセスできないIDは見つからないものとして報告されます。

グループ化されたツールは、テキスト形式と構造化されたMCPコンテンツの両方で、{ "operation": "<selected variant>", "result": ... }を返します。 その他のツールは、従来の結果形式を維持します。 バージョン0.10.0からの31から20への移行は次のとおりです。

以前のツール	現在のツールとセレクター
search_documents, list_documents	`mode=search
get_document, export_document, get_version_history	`view=detail
create_document, update_document	`action=create
list_folders, list_categories, list_tags	`kind=folders
create_folder, update_folder	`action=create
create_category, update_category	`action=create
create_tag, update_tag	`action=create
add_tag_to_document, remove_tag_from_document	`action=add
get_related_documents, search_knowledge_graph	`mode=neighbors
delete_document, delete_folder, delete_category, delete_tag, create_snapshot, restore_document_version, get_document_index_status, refresh_document_index, list_trash, restore_trashed_document, permanently_delete_document	同じ名前と動作

ライフサイクルの権限

操作	必要な権限	効果
ドキュメントの削除	実効カテゴリでの write	ゴミ箱にソフト削除します。コンテンツとバージョン履歴は保存されたままです。
フォルダーの削除	実効カテゴリでの write	フォルダーを削除します。直下の子フォルダーとドキュメントは削除されず、関連付けが解除されます。
カテゴリの削除	ワークスペース全体の write	カテゴリの所属を解除し、コンテンツを保持して再インデックスをキューに追加します。カテゴリキーでは実行できません。
バージョンの復元	ドキュメントに対する edit	現在のコンテンツをバックアップし、選択したバージョンのコンテンツを復元して、インデックス作成をキューに追加します。タイトルや配置は変更しません。
タグの作成、更新、削除	ワークスペース全体の write	ワークスペースのタグカタログを管理します。カテゴリキーでは実行できません。
ドキュメントタグの割り当てまたは解除	ドキュメントに対する edit	1 つのドキュメントのタグ所属を変更し、メタデータの再インデックスをキューに追加します。
フォルダーの更新	実効カテゴリでの write	API のスコープ規則に従ってフォルダーの名前を変更するか、移動し、メタデータの再インデックスをキューに追加します。
カテゴリの更新	ワークスペース全体の write	カテゴリの名前を変更するか、並べ替えます。カテゴリキーでは実行できません。
ゴミ箱の一覧表示	アクティブなスコープでの read	キーから参照できるソフト削除済みドキュメントを表示します。
ゴミ箱内のドキュメントの復元	実効カテゴリでの write	ソフト削除済みのドキュメントをアクティブなライブラリに戻します。
ドキュメントの完全削除	実効カテゴリでの write	ゴミ箱内のドキュメントをバージョン履歴も含めて完全に消去し、復元できない状態にします。
ドキュメントへの一括操作	選択した単一ドキュメント操作と同じ権限。各 ID について確認します	順次実行され、アトミックではありません。1 件の拒否によって、他の操作が許可されたり取り消されたりすることはありません。認証エラーやレート制限エラーが発生すると、残りの呼び出しは停止します。

一覧表示ツールまたは履歴ツールが返す UUID を使用してください。スナップショットはラベル付きのバージョンです。 そのバージョン ID を restore_document_version に渡してください。ゴミ箱内のドキュメントを復元するには restore_trashed_document を使用してください。ライフサイクルツールは破壊的操作を示す注釈を付与しますが、認可は それらの参考情報としてのクライアントヒントではなく、REST API によって適用されます。リクエストに失敗すると、 REST のステータスを含む MCP isError が返され、削除が成功したと誤って通知されることはありません。

プロンプト

• organize_workspace：DocsMint のカテゴリとフォルダーを使って、安全なドキュメント整理を計画します。
• research_workspace：ハイブリッド検索、GraphRAG、再ランキングを使って質問を調査し、ドキュメント ID を引用します。

リソース

• docsmint://guide/editor：エディターの使用ガイド。
• docsmint://guide/search：検索、GraphRAG、再ランキングのガイド。
• docsmint://workspace/catalog：スコープに応じた、最新のワークスペースカタログ。

スキル

• docsmint-document-manager： DocsMint の MCP ツールを通じて、DocsMint のドキュメントを作成、整理、編集、調査します。

ツールと REST ルート

グループ化されたセレクターは、同じ文書化済みの REST 操作に対応しています。stdio ブリッジには、独自のデータベース実装も認証サーバー実装もありません。エンドポイントの詳細については、機械可読な REST コントラクトと上記の操作マッピングを参照してください。

プロンプトとリソース

サーバーは organize_workspace と research_workspace のプロンプトを公開しています。MCP クライアントは、次のリソースを通じて、エディターのルール、検索ルール、現在のスコープに応じたワークスペースカタログも利用できます。

• docsmint://guide/editor
• docsmint://guide/search
• docsmint://workspace/catalog

リポジトリには、再利用可能な docsmint-document-manager スキルが含まれています。このスキルでは、API と UI で使用されるものと同じワークスペース／カテゴリーの権限、多言語検索フロー、エディターのルール、インデックス作成のライフサイクルについて説明しています。

ワークスペースキーでは、現在のワークスペースロールで許可されているドキュメント領域全体を管理できます。カテゴリーキーは、割り当てられたカテゴリーとそのフォルダーおよびドキュメントに制限され、明示的に付与された read、edit、write 権限のみを使用できます。カテゴリーキーではカテゴリーを作成できず、ドキュメント、フォルダー、グラフ、タグ、インデックスの各操作を通じて、割り当てられたカテゴリーの範囲外にアクセスすることもできません。

サーバーはキーを管理したり、キーを公開したりしません。これらのエンドポイントには Better Auth のブラウザーセッションが必要です。MCP エラーには、認証情報を公開することなく、バックエンドの HTTP ステータスとメッセージがそのまま保持されます。

開発

cd packages/mcp-server
bun run test
bun run typecheck
bun run dev