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：供 Agent 使用的机器可读指南

对 /mcp 的调用会报告给 Google Analytics 4。

MCP 资源

• artsdata://dumps/core-minus-provenance/latest（artsdata_dump）：最新 Artsdata core-minus-provenance 转储的清单——该转储是移除了溯源信息和 RDF-star 注释的核心图，每月以 gzip 压缩的 Turtle 文件形式发布。

  resources/read 会向 Artsdata Databus 请求最新版本的工件（GET /databus/artifact/latest?artifact=<ARTIFACT_URI>），并返回一个简短的 JSON 文档，其中包含下载 URL、版本、格式和压缩方式，而不是转储内容。通过 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（可选）：Artsdata API 的基础 URL，用于查询 Databus 上的最新数据转储（默认值为 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 的调用会报告到 Google Analytics 4，包括使用的工具、调用耗时以及调用方的 User-Agent。只有在设置了以下两个变量后，才会启用报告，因此开发和 CI 无需任何配置。

• GA4_MEASUREMENT_ID：GA4 媒体资源的 G-XXXXXXXXXX ID。不是机密；生产环境的默认值设定在 config/environments/production.rb 中。
• GA4_API_SECRET：Measurement Protocol 密钥。机密——请将其设为 Heroku 配置变量，切勿放入已提交的 env/*.env 文件中。
• GA4_DEBUG（可选）：为事件添加标记，使其在数秒内显示于 GA4 的 DebugView 中，并记录 GA4 是否认为每个负载有效。事件仍会被记录。此项很有用，因为无论负载是否有效，常规端点都会返回 204。

当两个凭据都存在时，报告功能会启用；否则会关闭。

此外，每次 MCP 调用都会以一行 JSON 写入 stdout，其中包括 Agent 发送的完整参数——完整的 SPARQL 查询、搜索词和实体 URI。在 Heroku 上，这些行会进入 heroku logs，也会发送到你附加的任何日志接收端。

• MCP_REQUEST_LOG（可选）：设为 false 可关闭请求日志。它独立于 Google Analytics 运行，即使未设置 GA4 凭据也能使用。

对于 sparql_query 调用，还会报告两项额外信息：sparql_form（SELECT、ASK 或 UNKNOWN）和 sparql_where，即移除 PREFIX 块并折叠空白字符后，由 Agent 编写的 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 详情：

此项目使用 GitHub Actions 进行持续集成，并自动部署到 Heroku。 每次向 main 分支推送都会触发一个工作流，用于构建应用程序并将其部署到 Heroku。 该工作流定义在 .github/workflows/deploy-to-heroku.yml 中。

每个拉取请求都会触发一个工作流来运行单元测试。该工作流定义在 .github/workflows/run-unit-tests.yml 中。

服务访问与 API 文档

Artsdata MCP 服务已部署并托管在实时生产环境中。

生产环境端点

• MCP 端点：https://mcp.artsdata.ca/mcp
• Agent 指南：https://mcp.artsdata.ca/llms.txt