DocsAgent — Zotero, Obsidian & Apple Notes MCP Server

AI エージェント向け DocsAgent MCP — Zotero、Obsidian、Apple Notes 📚⚡

DocsAgent を使うと、AI エージェントは個人のナレッジベースにすぐにプライベートにアクセスできます。 docsagent は仕様駆動型の MCP（Model Context Protocol）サーバーで、Claude Desktop、Cursor、Cline、Qwen Code などのあらゆる AI エージェントや MCP クライアントから、常駐する C++ 検索エンジンを介して Zotero ライブラリ、Obsidian の保管庫、Apple Notes（macOS）を検索、読み取り、書き込みできるようにします。1,000 件以上の PDFを対象にした BM25 全文検索とクエリに基づく順位付けによるパッセージ検索を約 15 msで実行します。すべてローカルで動作するため、RAG 対応のナレッジベースとして利用できます。

• 🔒 ローカル優先でプライベート — エンジンは Zotero ライブラリ、Obsidian の保管庫、Apple Notes のストアをお使いのマシンから直接読み取ります。ノートや PDF が外部に送信されることはありません。
• 🗂 3 つのソースを 1 つのクエリで検索 — Zotero のアイテム、注釈、ノート、Obsidian の保管庫、Apple Notes（macOS のみ）を対象に検索します。混合検索では、相互順位を使って 3 つすべての結果を統合します。
• ⚡ ネイティブ C++ 検索コア — 転置インデックス方式の BM25 とパッセージの順位付けにより、ミリ秒単位で検索できます。メモリ使用量は少なく、論文 1,500 件のライブラリで 160～227 MB です。
• 🧩 8 つの MCP ツール — 読み取り 5 つ、書き込み 3 つ。JSON スキーマによる引数検証、トークン予算、結果の重複排除、3 層の書き込み安全ゲートを備えています。
• 🌐 2 つのトランスポート — ローカル MCP クライアント向けの stdio と、リモートデプロイ向けの Streamable HTTP（オリジンチェック、API キー／OAuth 2.0 トークンのイントロスペクション、リクエストごとの RBAC、/health プローブ）に対応しています。
• 🐍 2 つのシェル、1 つのコア — この TypeScript パッケージと、機能が同等の Python ラッパーは、同じ JSON-RPC コントラクトを通じて同じツールを提供します。

---

アーキテクチャ

MCP Client (Claude Desktop / Cursor / Cline / Qwen Code / any MCP host)
        │  stdio (local)   or   Streamable HTTP  /mcp  (remote)
        ▼
MCP shell  ← this package (@docsagent/mcp-zotero / docsagent-mcp-zotero)
   · tool schemas (spec-driven), argument validation, token budget, dedup
   · write orchestration via the Zotero local API, write safety gate, RBAC
   · group-library sync via the Zotero Web API
        │  JSON-RPC 2.0 over HTTP ({coreHost}:{httpPort}/rpc, cpp-httplib)
        ▼
DocsAgent Core (resident C++ engine)
   · reads ~/Zotero/zotero.sqlite + storage/, an Obsidian vault, and (macOS) the
     Apple Notes store — directly on your machine
   · builds & serves one index per source (BM25 + passage ranking); mixed search
     (source "all") fuses them by reciprocal rank (RRF, k=60)

シェルはツール呼び出し時にコアを起動することはなく、ソースファイルにも触れません。コアはバックグラウンドサービスとして実行され、MCP クライアントを再起動しても利用できます。 ツールのスキーマとエラーコードについては、spec/ を参照してください。

---

クイックスタート

1. コアを起動する

npx @docsagent/docsagent start           # spawn the bundled core for your platform
npx @docsagent/docsagent status          # pid / endpoint / version

Python シェル（同じ動詞を core サブコマンドの下で使用）：

pip install ./python                      # build the wheel locally (PyPI upload pending)
docsagent-mcp core start

（core stop と core restart も利用できます。コアは、設定済みのすべてのソース、つまり Zotero のデータディレクトリ、Obsidian の保管庫、（macOS の場合）Apple Notes をインデックス化し、http://0.0.0.0:23120/rpc で JSON-RPC を提供します。）

2. MCP クライアントを設定する

Claude Desktop／Cursor／Cline／Qwen Code（mcpServers）：

{
  "mcpServers": {
    "docsagent": {
      "command": "npx",
      "args": ["-y", "@docsagent/docsagent"]
    }
  }
}

Python シェル（同じツール、同じコントラクト。このリポジトリからインストール）— mcpServers：

{
  "mcpServers": {
    "docsagent-zotero-py": {
      "command": "docsagent-mcp"
    }
  }
}

まず Python パッケージをインストールし（手順 1）、docsagent-mcp が PATH 上にある状態にしてください。

起動時にシェルはコアに接続し、ソースを読み込み、インデックスの状態を確認します。コアが実行されていない場合は、起動手順を表示してすぐにエラー終了します。何かを起動することはありません。

---

MCP ツール（外部 API）

ツールは 8 つで、読み取り 5 つ、書き込み 3 つです。スキーマは spec/tools/*.json に一元管理されたコントラクトであり、両方のパッケージに反映されています。ハンドラーの実行前に引数が検証され、エラーは型付きの docsagent エラーコードに対応付けられます。

list_sources

検索可能な各ソースの機能、サポートされるターゲット／対象範囲／参照モード、フィルター、ドキュメント件数を返します。最初に呼び出してください。

現在のソース：zotero（ターゲットは items、annotations、notes。コレクション／タグを参照可能）、obsidian（保管庫。ノートをアイテムとして扱い、フォルダー／タグを参照可能）、apple-notes（macOS のみ。それ以外のプラットフォームではエンジンがソースを省略します）。保管庫は ~/Documents/Obsidian Vault にあり（DOCSAGENT_OBSIDIAN_VAULT で変更できます）、Apple Notes はシステムの Notes ストアから読み取ります（DOCSAGENT_APPLE_NOTES_DB で変更できます）。

search

1つのソースを横断して検索します（アイテム、注釈、ノート）。

パラメーター	型	説明
query	文字列	通常のキーワードまたはフレーズ。mode=grep でない場合は必須です
mode	relevance | grep	デフォルトは BM25 による関連度検索です。grep はトークン化やランキングを行わず、リテラルパターンを検索します
pattern	文字列。mode=grep の場合は必須	検索するリテラル文字列
caseSensitive、wholeWord、maxMatches		mode=grep 専用：ASCII の大文字・小文字の折りたたみ、[A-Za-z0-9_] の単語境界、合計ヒット数の上限
target	"items" | "annotations" | "notes" または配列	デフォルトは items です
depth	ids | snippets | full	デフォルトはスニペット（BM25 でランキングされた抜粋）です
filters	オブジェクト	tags、yearFrom/yearTo、itemType、authors、colors、containerId、titleContains
k、snippetsPerResult、max_tokens	数値	ランキングの深さとトークン予算（mode=grep の場合は最大ドキュメント数、ドキュメントあたりのヒットウィンドウ数）

results[] として、グローバル ID（zotero:KEY、obsidian:<path>、apple-notes:<uuid>）、 タイトル、関連度、スニペットを返します。複数のターゲットを検索した場合、 結果はターゲットごとにグループ化されます。mode=grep では、各結果に matchCount と ヒットウィンドウを示す snippets[]（line/column/offset を含む hits[] と、 field でタグ付けされたメタデータのヒット）が含まれます。relevance は 0 となり、 レスポンスには totalMatches が追加されます。結果は重複排除（ID、次に正規化されたタイトル＋年）され、 トークン予算内に収まるようにまとめられます。

search は config.defaultSource（デフォルトは zotero）に対して実行されます。複数ソース検索は中核機能です。コアの search / grep メソッドに source: "all" を渡すと、各ソースが個別にランキングされた後、逆順位融合（k=60）によって統合されます。各ヒットにはソースがタグ付けされます。コーパス間で BM25 スコアを比較できないため、統合には順位を使用します。

get_content

1つのエントリーを読み取ります。mode=passages（クエリでランキングされた抜粋、k）または mode=fulltext （nextOffset を使ったオフセットページネーション）を指定します。ノートの場合は、タグとメタデータとともに本文を返します。

get_metadata

include：metadata、abstract、annotations、notes、citation（bibtex / csljson / citationFormat/citationStyle による書式設定）。ノートはトークン予算内に収まるようにまとめられます。

list_library

閲覧モード：collections（parentId で絞り込み）、items（containerId で指定）、 tags、saved_searches、standalone_notes。閲覧モードはソースごとに異なります。Zotero では これらすべてを利用できますが、Obsidian と Apple Notes では folders（絞り込み）／tags／items を利用できます。

書き込みツール（3層のセーフティゲート）

ツール	機能	主な引数
import_item	ローカルの PDF をインポートするか、DOI / ISBN / arXiv ID を解決します（Zotero translation server 経由）。オプションの autoClassify でコレクションを提案します	paths | identifiers、containerId、autoClassify、confirmed
add_note	孤立状態の検証とロールバック機能を備え、アイテムに Markdown の子ノートを追加します（Zotero のノート HTML に変換）	id、content、tags、confirmed
batch_modify	最大 200 件のアイテムを50件ずつのバッチで一括処理し、add_to_collection / remove_from_collection / add_tags / remove_tags を実行します	action、ids、containerId、tags、confirmed

書き込みツールの対象は Zotero ソースのみです。Obsidian と Apple Notes のソースは読み取り専用です。

書き込みセーフティゲート（spec/algorithms/write-gate.md）：レイヤー1 enableWrites=true でない場合、書き込みツールは登録されません。レイヤー2 confirmed=false の場合はプレビューを返し、レート制限の枠を消費しません。レイヤー3 確定済みの書き込みでは、1時間あたりのレート制限（デフォルトは30/h）の枠を消費します。batch_modify で20件を超えるアイテムを処理する場合、プレビューに requiresConfirmation も報告されます。

エンジンのパフォーマンス

C++ エンジンは PapersGPT を支えています。この MCP サーバーにも、同じインデックス作成と検索のスタックが組み込まれています。実際の Zotero インストール環境でのベンチマーク結果は以下のとおりです（詳細なレポート）。

指標	Mac（Intel i9）	Windows VM（4C8G）
ライブラリのサイズ	1,506 件の PDF（ディスク上で 4.5 GB）	500 件以上の PDF
インデックスの作成時間	141 秒	数秒
メモリ（エージェントプロセス）	227 MB	160 MB
平均検索レイテンシ	約 15 ms	約 15 ms

• インデックス作成のコストはライブラリのサイズに対しておおむね線形に増加しますが、検索レイテンシは一定です。論文 10,000 件のライブラリ（約 30 GB）は約 15〜20 分でインデックス化でき、日常的な検索は約 15 msで行えます。
• 比較として、一般的なウェブページの読み込みには 1,000〜3,000 ms、まばたきには 100〜150 ms かかります。PapersGPT は完全オフラインで、約 15 ms で回答します。
• プライバシー：ライブラリがマシンの外部に送信されることはありません。

設定

設定ファイルは ~/.docsagent/config.json（または $DOCSAGENT_CONFIG）にあります。JS シェル、Python ラッパー、C++ コアで共有される単一のファイルです。spec/config.json に照らして検証されます。

キー	デフォルト	説明
coreHost	0.0.0.0	コアがバインドし、シェルが接続するアドレス
httpPort	23120	コアの HTTP ポート（POST /rpc）
coreBinary	""	コアバイナリの明示的なパス（任意）
zoteroDataDir	~/Zotero	Zotero のデータディレクトリ
zoteroApiUrl	http://localhost:23119/api	Zotero のローカル API（書き込みのオーケストレーション）
zoteroGroups	[]	zotero.org から同期するグループライブラリ
enableWrites	false	3 つの書き込みツールを登録するかどうか
writeRateLimitPerHour	30	確認済み書き込みのレート制限
maxTokensPerTool	4000	ツール結果ごとのトークン予算
defaultSource	zotero	シェルが検索し、ID の接頭辞を解決するソース（zotero、obsidian、apple-notes）
transport	stdio	stdio または streamable-http
httpListenAddr	0.0.0.0:8080	streamable-http のリッスンアドレス（/mcp）
authMode / authConfig	none	api-key または oauth2（RFC 7662）と allowedOrigins
rbacRoles	{}	ロール → 許可されるツール名（HTTP でリクエストごとに RBAC を適用）
logLevel	info	debug / info / warn / error

---

配布

チャネル	パッケージ	同梱コア	サイズ
npm（JS/TS シェル）	@docsagent/docsagent	bin/ に全プラットフォーム用のバイナリ	約 70 MB の tarball
PyPI（Python シェル）	docsagent-mcp（pip install ./python）	wheel に同じバイナリを同梱	約 65 MB の wheel

同梱コアの対応プラットフォーム：macOS ユニバーサル（Intel + Apple Silicon）、Windows x64（x86_64）、Linux x64（x86_64）。Linux ARM は非対応です。ソースの対応状況：Zotero と Obsidian はすべてのプラットフォームで利用できます。Apple Notes は macOS のみで利用でき（それ以外では list_sources に表示されません）。

どちらのシェルも同じ設定を読み込み、同じコアと通信します。MCP の配布チャネルとして、どちらか一方、または両方を選べます。コアのライフサイクル（start / stop / restart / status）は、どちらの CLI からも操作できます。

リンク

• spec/ — 唯一の情報源となる契約：8 つのツールスキーマ、23 の JSON-RPC メソッド、エラーコードと推奨される呼び出し、設定スキーマ
• PapersGPT 検索パフォーマンスのベンチマーク
• Zotero · Model Context Protocol

ライセンス

Apache-2.0