Artsdata

Artsdata MCP サーバー（Rails）

前提条件

• Ruby 4.0.6
• Rails 8.1
• Bundler

セットアップ

bundle install

エンドポイント

• POST /mcp：MCP Streamable HTTP エンドポイント（ツールとリソースについては docs/mcp-server.md を参照してください）
• GET /up：ヘルスチェック
• GET /llms.txt：エージェント向けの機械可読なガイド

/mcp への呼び出しは Google Analytics 4 に報告されます。

MCP リソース

• artsdata://dumps/core-minus-provenance/latest（artsdata_dump）：最新の Artsdata core-minus-provenance ダンプのマニフェストです。これは、プロベナンスと RDF-star アノテーションを除去したコアグラフで、圧縮された Turtle ファイルとして毎月公開されます。

  resources/read は Artsdata Databus に最新バージョンのアーティファクトを問い合わせ（GET /databus/artifact/latest?artifact=<ARTIFACT_URI>）、ダウンロード URL、バージョン、形式、圧縮方式を含む小さな JSON ドキュメントを返します。ダンプの内容は返しません。Databus を経由することで、MCP クライアントはファイルが実際に保存されている場所を知る必要がありません。クライアントは downloadUrl からファイルをダウンロードし、読み取りごとに version を比較して、新しいダンプが公開されたことを検知します。

ディレクトリ構成

.github/
  workflows/
    deploy-to-heroku.yml  # Workflow deploying to Heroku
    run-unit-tests.yml    # Reusable workflow running Minitest
    unit-test-on-pull-request.yml # Workflow running unit tests on pull requests
app/
  resource/     # MCP resources
  schema/       # JSON schemas of the tools' input and output
  services/     # Clients for the reconciliation service, SPARQL endpoint and Databus
  tool/         # MCP tools
config/
  initializers/mcp_server.rb  # MCP server: registered tools, resources and transport
  initializers/mcp_analytics.rb # Google Analytics 4 reporting configuration
  routes.rb
lib/
  mcp_analytics/  # Rack middleware reporting MCP usage to Google Analytics 4
test/

設定

• ARTSDATA_RECONCILIATION_ENDPOINT：search_entities、get_entity、search_events ツールが使用する照合サービスの URL。
• ARTSDATA_SCHEMA_URL（任意）：get_schema ツールがコンパイルする Turtle ファイル（デフォルトは https://docs.artsdata.ca/artsdata-schema.ttl）。
• ARTSDATA_SCHEMA_CACHE_TTL_SECONDS（任意）：コンパイル済みスキーマをプロセス内でキャッシュする期間（デフォルトは 86400）。
• ARTSDATA_CORS_ORIGINS（任意）：カンマ区切りの CORS オリジン（デフォルトは *）。
• ARTSDATA_API_ENDPOINT（任意）：最新のデータダンプを Databus に問い合わせる際に使用する Artsdata API のベース URL（デフォルトは https://api.artsdata.ca）。
• ARTSDATA_SPARQL_ENDPOINT（任意）：sparql_query ツールがクエリする SPARQL エンドポイント（デフォルトは https://query.artsdata.ca/query）。
• ARTSDATA_SPARQL_TIMEOUT_SECONDS（任意）：sparql_query の呼び出しに対する読み取りタイムアウト（デフォルトは 25）。
• ARTSDATA_SPARQL_MAX_ROWS（任意）：sparql_query が返す最大行数。超過した行は切り捨てられ、結果に truncated フラグが設定されます（デフォルトは 1000）。
• Docker インスタンスのプロファイルは次のファイルに用意されています。
  • env/production.env
  • env/staging.env
• ARTSDATA_INSTANCE_TYPE（任意）：PRODUCTION（デフォルト）または STAGING。 Docker のエントリーポイントは、env/ から対応するファイルを読み込みます。

使用状況分析

/mcp への呼び出しは、使用されたツール、呼び出しにかかった時間、呼び出し元の User-Agent を含め、Google Analytics 4 に報告されます。以下の両方の変数が設定されるまで、報告はオフのままなので、開発環境や CI で設定する必要はありません。

• GA4_MEASUREMENT_ID：GA4 プロパティの G-XXXXXXXXXX ID。秘密情報ではありません。本番環境では config/environments/production.rb でデフォルト値が設定されています。
• GA4_API_SECRET：Measurement Protocol のシークレット。秘密情報です。Heroku の config var として設定してください。コミットされている env/*.env には絶対に設定しないでください。
• GA4_DEBUG（任意）：イベントにタグを付け、数秒以内に GA4 の DebugView に表示し、各ペイロードが有効だと GA4 に判定されたかどうかをログに記録します。イベントは引き続き記録されます。通常のエンドポイントは、ペイロードの有効性にかかわらず 204 を返すため便利です。

両方の認証情報が設定されている場合は報告が有効になり、そうでない場合は無効になります。

これとは別に、すべての MCP 呼び出しは、エージェントが送信した引数全体（完全な SPARQL クエリ、検索語、エンティティ URI を含む）とともに、1 行の JSON として stdout に書き込まれます。Heroku では、これらの行は heroku logs と、接続した任意のログドレインに送られます。

• MCP_REQUEST_LOG（任意）：リクエストログを無効にするには false を設定します。これは Google Analytics とは独立して動作し、GA4 の認証情報が設定されていなくても使用できます。

sparql_query の呼び出しでは、追加で 2 つの情報が報告されます。sparql_form（SELECT、ASK、または UNKNOWN）と、エージェントが記述した WHERE 句から PREFIX ブロックを取り除き、空白を圧縮した sparql_where です。どちらも Google Analytics とリクエストログに送られます。GA4 では WHERE 句は 100 文字の上限で切り詰められますが、ログには全文が記録されます。

アプリケーションを実行する

bundle exec rails server

API は http://localhost:3000 で利用できます。

Docker

イメージをビルドします。

docker build -t artsdata-mcp-server .

サーバーを実行します。

docker run --rm -p 3000:3000 artsdata-mcp-server

staging プロファイルで実行します。

docker run --rm -p 3000:3000 -e ARTSDATA_INSTANCE_TYPE=STAGING artsdata-mcp-server

Docker でテストを実行します。

docker run --rm artsdata-mcp-server bundle exec rails test

テストを実行する

単一のテストファイルを実行します。

bundle exec rails test test/tool/search_events_test.rb

すべてのテストを実行します。

bundle exec rails test

llms.txt のメンテナンス

公開される public/llms.txt ファイルは、MCP サーバーのメタデータ（ツール、リソース、説明、スキーマ）から生成されます。

CI の動作：

• プルリクエストの CI では bundle exec rake docs:check_llms が実行されます。
• public/llms.txt が最新でない場合、ワークフローは失敗します。

開発者のワークフロー：

• ほとんどの場合、手動での作業は不要です。
• MCP のツール、リソース、またはスキーマを変更した場合は、次のコマンドでファイルを再生成します。

bundle exec rake docs:generate_llms

• 次のコマンドで同期されていることを確認します。

bundle exec rake docs:check_llms

• 更新された public/llms.txt をコミットします。

デプロイと CI/CD の詳細：

このプロジェクトでは、継続的インテグレーションと Heroku への自動デプロイに GitHub Actions を使用しています。 main ブランチへのプッシュごとに、アプリケーションをビルドして Heroku にデプロイするワークフローが実行されます。 このワークフローは .github/workflows/deploy-to-heroku.yml で定義されています。

プルリクエストごとに、ユニットテストを実行するワークフローが起動します。このワークフローは .github/workflows/run-unit-tests.yml で定義されています。

サーバーへのアクセスと API ドキュメント

Artsdata MCP Server は稼働中の本番環境にデプロイされ、ホストされています。

本番環境のエンドポイント

• MCP エンドポイント：https://mcp.artsdata.ca/mcp
• エージェントガイド：https://mcp.artsdata.ca/llms.txt