Artsdata README

Artsdata MCP Server (Rails)

Prerequisites

• Ruby 4.0.6
• Rails 8.1
• Bundler

Setup

bundle install

Endpoints

• POST /mcp: MCP Streamable HTTP endpoint (tools and resources are documented in docs/mcp-server.md)
• GET /up: health check
• GET /llms.txt: machine-readable guide for agents

Calls to /mcp are reported to Google Analytics 4.

MCP resources

• artsdata://dumps/core-minus-provenance/latest (artsdata_dump): manifest for the latest Artsdata core-minus-provenance dump — the core graph with provenance and RDF-star annotations removed, published monthly as a gzipped Turtle file.

  resources/read asks the Artsdata Databus for the newest version of the artifact (GET /databus/artifact/latest?artifact=<ARTIFACT_URI>) and returns a small JSON document with the download URL, version, format and compression — never the dump contents. Going through the Databus means MCP clients need to know nothing about where the file is actually stored. Clients download the file from downloadUrl and compare version across reads to detect when a new dump lands.

Directory structure

.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/

Configuration

• ARTSDATA_RECONCILIATION_ENDPOINT: reconciliation service URL used by the search_entities, get_entity and search_events tools.
• ARTSDATA_SCHEMA_URL (optional): Turtle file compiled by the get_schema tool (default https://docs.artsdata.ca/artsdata-schema.ttl).
• ARTSDATA_SCHEMA_CACHE_TTL_SECONDS (optional): how long the compiled schema is cached in process (default 86400).
• ARTSDATA_CORS_ORIGINS (optional): comma-separated CORS origins (default *).
• ARTSDATA_API_ENDPOINT (optional): base URL of the Artsdata API, used to query the Databus for the latest data dump (default https://api.artsdata.ca).
• ARTSDATA_SPARQL_ENDPOINT (optional): SPARQL endpoint queried by the sparql_query tool (default https://query.artsdata.ca/query).
• ARTSDATA_SPARQL_TIMEOUT_SECONDS (optional): read timeout for a sparql_query call (default 25).
• ARTSDATA_SPARQL_MAX_ROWS (optional): maximum rows sparql_query returns; extra rows are cut and the result is flagged truncated (default 1000).
• Docker instance profiles are provided in:
  • env/production.env
  • env/staging.env
• ARTSDATA_INSTANCE_TYPE (optional): PRODUCTION (default) or STAGING. The Docker entrypoint loads the matching file from env/.

Usage analytics

Calls to /mcp are reported to Google Analytics 4, including the tool used, how long the call took, and the caller's User-Agent. Reporting stays off until both variables below are set, so development and CI need no configuration.

• GA4_MEASUREMENT_ID: the GA4 property's G-XXXXXXXXXX id. Not a secret; defaulted for production in config/environments/production.rb.
• GA4_API_SECRET: Measurement Protocol secret. Secret — set it as a Heroku. config var, never in env/*.env, which is committed.
• GA4_DEBUG (optional): tag events so they appear in GA4's DebugView within seconds, and log whether GA4 considers each payload valid. Events are still recorded. Useful because the normal endpoint answers 204 whether or not the payload is valid.

Reporting is on when both credentials are present and off otherwise.

Separately, every MCP call is written to stdout as one JSON line, including the complete arguments the agent sent — the full SPARQL query, search terms, entity URIs. On Heroku these lines go to heroku logs and to any drain you attach.

• MCP_REQUEST_LOG (optional): set to false to silence the request log. It runs independently of Google Analytics and works with no GA4 credentials set.

For sparql_query calls, two extra facts are reported: sparql_form (SELECT, ASK or UNKNOWN) and sparql_where, the WHERE clause as the agent wrote it with the PREFIX block removed and whitespace collapsed. Both go to Google Analytics and to the request log; GA4 cuts the WHERE clause at its 100-character limit, the log keeps it whole.

Run the application

bundle exec rails server

The API will be available at http://localhost:3000.

Docker

Build the image:

docker build -t artsdata-mcp-server .

Run the server:

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

Run with staging profile:

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

Run tests in Docker:

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

Run tests

Run a single test file:

bundle exec rails test test/tool/search_events_test.rb

Run all tests:

bundle exec rails test

llms.txt maintenance

The public/llms.txt file is generated from MCP server metadata (tools, resources, descriptions, and schemas).

CI behavior:

• Pull request CI runs bundle exec rake docs:check_llms.
• If public/llms.txt is stale, the workflow fails.

Developer workflow:

• Most of the time, no manual action is needed.
• If you change MCP tools, resources, or schemas, regenerate the file with:

bundle exec rake docs:generate_llms

• Confirm it is in sync with:

bundle exec rake docs:check_llms

• Commit the updated public/llms.txt.

Deployment & CI/CD Details:

This project uses GitHub Actions for continuous integration and automated deployment to Heroku. Every push to the main branch triggers a workflow that builds and deploys the application to Heroku. The workflow is defined in .github/workflows/deploy-to-heroku.yml.

Every pull request triggers a workflow that unit tests. The workflow is defined in .github/workflows/run-unit-tests.yml.

Server Access & API Documentation

The Artsdata MCP Server is actively deployed and hosted in a live production environment.

Live Production Endpoints

• MCP endpoint: https://mcp.artsdata.ca/mcp
• Agent guide: https://mcp.artsdata.ca/llms.txt