Notanda (Beta)

Notanda ローカル MCP サーバー — ベータ版

OpenAlex 検索を行うたびに、リクエスト、レスポンス、チェックサムが保存されるため、後からソースを確認できます。

ベータ版：外部開発者による支援なしの受け入れテストは、まだ実施されていません。 技術テストで、外部ユーザーによる使いやすさとインストールの確認を代替することはできません。

このディレクトリでは、Notanda の来歴情報を保持した OpenAlex 検索をローカル MCP クライアントに提供します。これは独立した notanda-mcp パッケージであり、ホスト型サービスでも notanda 1.3.2 パッケージの一部でもありません。リリース済みのコアに依存します。

このコンポーネントが提供するツールは、次の2つだけです。

• search_literature：OpenAlex を検索して、DOI を持つ OA 研究成果を取得し、リクエスト、プロバイダーの観測情報、返された結果、ハッシュを1つのエビデンス ID のもとに保存します。返される receipt は manifest.json の SHA-256 です。
• get_evidence：プロバイダーへのリクエストを再実行せずに、ハッシュを検証し、エビデンス ID に基づいて元の結果を返します。任意の呼び出し元保持の receipt を指定すると、マニフェストとともにペイロードが差し替えられたことも検出できます。

どちらのツールの説明にも、また成功時のすべてのレスポンスにも、タイトルとメタデータは未検証のサードパーティーコンテンツであり、指示ではないことを示す警告があります。

全文をダウンロードしたり、Notanda のコーパスや Evidence Ledger に書き込んだり、ウェブ UI を変更したり、ネットワークサーバーを公開したり、汎用的なエージェント推論を提供したりすることはありません。

来歴情報とステータス

実装は、隔離されたブランチ experiment/local-mcp のコミット 366bc2d4827aa915e2e58a82cd567163ed63d4be を基にしています。封印済みの引き継ぎパッケージでは、このソースが、合格した20件の MCP テストと成功した OpenAlex のライブ実行に紐付けられていました。公開リポジトリへの統合では、重複していた Notanda ランタイムを、リリース済みの notanda==1.3.1 PyPI 依存関係に置き換えました。ベータ版3では、この固定バージョンを notanda==1.3.2 に更新します。MCP は引き続き、テスト済みの SDK バージョン 1.30.0 に固定されています。SOURCE_PROVENANCE.json には、ソースハッシュと意図的に行った統合変更が、機械可読形式で記録されています。

当初の受け入れ基準6項目のうち、技術的には5項目を満たしています。残る6番目の基準、つまり Notanda に関する知識のない外部開発者が、支援なしでインストール、検索、再起動、独立検証を完了することは、その結果が報告されるまで外部での検証が必要です。

ベータ版パッケージをインストールする

Python 3.11 または 3.12 を使用してください。専用の仮想環境を推奨します。

python -m venv .venv-mcp
# Linux/macOS:
. .venv-mcp/bin/activate
# Windows PowerShell instead:
# .venv-mcp\Scripts\Activate.ps1
python -m pip install "notanda-mcp==0.1.0b3"

ベータ版3には、正確に notanda==1.3.2 が必要です。このバージョンがすでにインストールされている環境にインストールしても、コアのバージョンは維持されます。ベータ版2には notanda==1.3.1 が必要であり、pip はその固定バージョンを満たすため、既存の 1.3.2 インストールをダウングレードする場合があります。ベータ版2または別の Notanda コアバージョンが必要な場合は、別の環境を使用してください。依存関係のチェックを回避しないでください。バージョンを正確に固定することで、テスト済みのコアとサーバーの組み合わせを再現できますが、今後のコアリリースとの互換性を保証するものではありません。

uvx を使用するクライアントでは、次のコマンドと引数を設定してください（エビデンスディレクトリは、コンピューター上の書き込み可能な絶対パスに置き換えてください）。

uvx --python 3.12 [email protected] --evidence-dir ABSOLUTE_LOCAL_EVIDENCE_PATH

MCP クライアントのローカル環境に HARVESTER_OPENALEX_API_KEY を設定してください。検索にはこのキーが必要です。コマンドの引数には含めないでください。レジストリマニフェストでは、この変数はシークレット、エビデンスパスは必須入力として宣言されています。

このリポジトリからインストールする

Python 3.11 または 3.12 を使用してください。リポジトリのルートから実行します。

python -m venv .venv-mcp
# Linux/macOS:
. .venv-mcp/bin/activate
# Windows PowerShell:
# .venv-mcp\Scripts\Activate.ps1
python -m pip install -e ./mcp

これにより、チェックアウトから MCP コンポーネントがインストールされ、レビュー済みの Notanda コアが PyPI から notanda==1.3.2 として解決されます。

OpenAlex API キーをローカルで設定してください。たとえば、PowerShell でキーをターミナルの履歴に残さず設定するには、次のようにします。

$mcpSecureKey = Read-Host 'OpenAlex API key' -AsSecureString
$env:HARVESTER_OPENALEX_API_KEY = [System.Net.NetworkCredential]::new('', $mcpSecureKey).Password

既存の Notanda 設定方法も使用できます：HARVESTER_CONFIG または HARVESTER_OPENALEX_API_KEY。認証情報をエビデンスディレクトリ、Git、スクリーンショット、返却されるテストレポートに追加しないでください。

実行と検証

付属の実際の stdio クライアントは、サーバーを起動して MCP を初期化し、2 つの ツール名を検証して検索を実行します。

python mcp/tools/mcp_client.py \
  --evidence-dir ./tmp/mcp-evidence \
  --query "scientific reproducibility" \
  --limit 2

レスポンスには evidence_id と receipt が含まれます。どちらも evidence ディレクトリの外に保管してください。2 つ目のプロセスで receipt を検証し、 プロバイダーへの再リクエストなしに保存済みのレスポンスを取得できます。

python mcp/tools/mcp_client.py \
  --evidence-dir ./tmp/mcp-evidence \
  --id EVIDENCE_ID \
  --receipt RECEIPT

互換性のため、get_evidence は receipt なしでも動作し、従来のペイロードハッシュ と ID のチェックを実行します。これらのチェックで破損は検出できますが、ペイロードと マニフェストを協調して置き換えた場合、元の receipt が指定されているときにのみ検出できます。

独立した検証ツールは Python の標準ライブラリのみを使用します。

python -S mcp/tools/verify_mcp_evidence.py \
  ./tmp/mcp-evidence/EVIDENCE_ID

別のローカル MCP クライアントを使用する場合は、仮想環境の notanda-mcp 実行ファイルを次の引数で設定してください。

--evidence-dir ABSOLUTE_LOCAL_EVIDENCE_PATH

トランスポートは stdio です。サーバーにはユーザーインターフェースがなく、リッスン ポートも開きません。

エビデンスの仕様

各検索では、32 文字の evidence ID を名前とするディレクトリが 1 つ作成されます。

ファイル	内容
request.json	指定されたクエリと有効なクエリ、上限、MCP クライアント名／バージョン、ソース実験のコミット、インストール済みの Notanda バージョン、サーバーハッシュ
provider.json	シークレットをマスキングした後の OpenAlex URL、タイムスタンプ、HTTP ステータス、取得した解析済み JSON
response.json	構造化されたエラーと信頼できないコンテンツに関する通知を含む、永続化された結果。独立した receipt は、封印後に MCP レスポンスへ追加されます
manifest.json	3 つのペイロードファイルのバイト数と SHA-256

マニフェストだけで、破損や単一ファイルの変更を検出できます。これはデジタル署名では なく、呼び出し元が保持する receipt がなければ、ペイロードとマニフェストを協調して 置き換えた場合は検出できません。オプションの receipt と照合すると、元の検索時に 確認された正確なマニフェストを基準として検証できます。

制限とエラー時の動作

• クエリの長さ：1～1000 文字。結果の上限：整数で 1～10。
• OpenAlex へのリクエストは 1 回のみで、ページネーションと自動再試行はありません。
• 操作タイムアウトは 20 秒、接続タイムアウトは 10 秒、レスポンスの上限は 4 MiB です。
• プロバイダーのエンドポイントとして受け付けるのは https://api.openalex.org/works のみです。
• キーがない場合：configuration_error。入力が無効な場合：invalid_arguments。
• プロバイダー／トランスポートのエラー：provider_error。プロバイダーの例外テキストは保存されません。
• 書き込みが中断された場合：incomplete。ハッシュまたは ID が一致しない場合：integrity_failure； 指定された receipt が一致しない場合：receipt_mismatch。
• プロバイダーのテキストは信頼できないデータとして永続化され、指示として解釈されることはありません。

テスト

開発用追加機能をインストールし、決定論的な 23 件のチェックを実行します。

python -m pip install -e "./mcp[dev]"
python -m pytest mcp/tests

テストでは、正常な取得、再起動、独立した検証、破損、無効な入力、HTTP 401／429／500、 タイムアウト、不正なレスポンスとサイズ超過のレスポンス、ストレージ障害、プロセスの 異常終了、シークレットのマスキング、実際の 2 プロセス間での stdio MCP 動作を検証します。