smithsonian-mcp-server

---

概述

史密森尼博物馆的开放访问目录：涵盖 20 多家博物馆的 1,450 万件藏品，其中 520 万件附有 CC0 图片。可通过自由文本或类别搜索，按博物馆、文化、日期或主题浏览，并探索各馆藏之间的关联。

工具

工具	描述
smithsonian_search_objects	按文本查询搜索 1,450 万件藏品，并可使用可选筛选条件（博物馆、类型、日期术语、文化、地点、主题、名称、学名、媒体类型、仅限在线、CC0）。返回整理后的摘要及总数。
smithsonian_list_terms	列出已索引筛选字段的有效术语词汇表（unit_code、culture、place、date、online_media_type、topic）。筛选前先调用，以免无效值导致结果为空；传入 contains 可将猜测的值解析为准确术语。unit_code 术语会附带博物馆名称。
smithsonian_get_object	根据 ID 获取对象的规范化目录元数据投影：标题、日期、材料、尺寸、展览历史、鸣谢信息和标识符。
smithsonian_get_media	返回对象所有采用 CC0 许可的图像，提供多种分辨率（缩略图、屏幕尺寸、高分辨率 JPEG/TIFF）。只返回 CC0 图像，且不会返回空列表；若对象尚未数字化、仅有非图像媒体或仅有受限图像，会通过不同的错误原因说明情况。
smithsonian_browse_category	浏览某个精确类别（博物馆、文化、时期、媒介、主题）中的对象，并返回总数、一页对象和博物馆细分统计。必须使用准确的已索引类别术语。
smithsonian_find_related	根据共同的文化、具名对象、主题和时期特征，发现与锚点对象相关的跨藏品对象。

---

功能参考

smithsonian_search_objects _工具

• 在 20 多家博物馆的 1,450 万件藏品中进行全文搜索
• 筛选条件会追加严格的 AND 约束。普通单词和带引号的短语保留其匹配语义；活动的 Lucene 表达式会分组，以保留布尔优先级。
• filters.online_media_type 接受 smithsonian_list_terms 中的准确媒体类别，例如 Images、3D Models 和 Sound recordings。这些类别描述的是索引内容；即使是 Images，也不保证附有图像或 CC0 图像。请检查 smithsonian_get_object.media_summary，确认是否可获取媒体。媒体类别可用于搜索，但没有媒体类型浏览模式。
• 筛选条件：博物馆单元代码、对象类型、已索引日期术语（1920s、500-1500、21st century、-2500）、文化、地理位置、主题、具名对象（name）、学名（scientific_name）、已索引媒体类别（online_media_type）、仅限在线、仅限 CC0
• topic 和 name 是严格的已索引约束，而不是全文搜索；topic: "Quilts" 匹配 1,134 件对象，而不带筛选的词语匹配 2,677 件；name: "Warhol, Andy" 匹配 421 件，而不带筛选的词语匹配 715 件
• 返回整理后的摘要：标题、日期、博物馆、对象类型、缩略图 URL、CC0 标记、record_id
• 使用 start + rows 进行标准分页（基于偏移量，每页最多 100 条）

---

smithsonian_list_terms _工具

• 字段：unit_code、culture、place、date、online_media_type、topic——受控词汇表，术语通常为复数形式（例如 Paintings，而非 Painting）；搜索或浏览前，请先在此确认筛选值
• contains 根据不区分大小写的子字符串筛选词汇表，可通过一次调用将猜测的值解析出来（例如 greek → Greek, Attic）；对于 unit_code，它也会匹配博物馆名称（National Air and Space → NASM），且每个 unit_code 术语都会附带一个映射博物馆名称的 labels 字段
• 使用 start + rows 分页（默认 50，每页最多 100 条）；topic（13.3 万个术语）和 place（11.4 万个术语）的词汇量较大，适合与 contains 搭配使用
• 上游不提供每个术语对应的对象数量，只提供术语本身
• 每个字段的词汇表都会按 SMITHSONIAN_TERMS_CACHE_TTL_SECONDS 缓存（默认 3600 秒，0 表示禁用）；上游忽略分页，每次调用都会返回完整集合，因此未缓存时分页获取大型词汇表会反复下载
• 此处无法枚举 object_type；请从 smithsonian_search_objects 结果中的 object_type 字段获取其值

smithsonian_get_object _工具

• 输入：来自 smithsonian_search_objects 的 record_id——请勿手动构造 ID
• 返回公开的目录字段：标题、日期（均带标签）、制作者（含角色）、材料、尺寸、地点关联、文化术语、主题／对象术语、展览历史、登录编号、署名行、权利声明
• 包含媒体摘要——如需完整图片 URL，请调用 smithsonian_get_media
• 所有非空备注均保留其目录标签和来源顺序。description 会选取可识别的文本标签；行政备注仍保留标签。
• 自然历史元数据包括所有 scientific_names、报告的 taxonomy 层级，以及有效的十进制藏品 coordinates（若有，还包括其对应地点）。没有名称或有效坐标时，数组为空；缺失的层级会省略。不推断接受名、地理编码结果或精度。搜索时，将 scientific_names 用作确切的 filters.scientific_name 值；此字段无法通过 smithsonian_list_terms 枚举。

---

smithsonian_get_media _工具

• 仅返回 CC0 许可的图片，绝不返回受限内容
• 无内容可返回时有三种不同的失败原因：no_media（没有数字化内容）、no_images（存在媒体，但全都不是图片——扫描书籍、3D 模型、录音；恢复提示会列出存在的类型）、not_cc0（存在图片，但没有 CC0 图片；以 Forbidden 抛出）
• 每个图片条目都包含缩略图（约 120px）、屏幕尺寸图片（约 800px）以及高分辨率 JPEG/TIFF URL，并附像素尺寸
• 调用此工具前，使用 smithsonian_search_objects 和 filters.cc0_only: true 查找包含可下载 CC0 图片的对象

---

smithsonian_browse_category _工具

• 五种模式：museum（按机构代码筛选，例如 "NASM"——精确匹配，不按博物馆名称匹配）、culture（例如 "Aztecs"）、period（已索引的日期术语，例如 "1940s" 或 "500-1500"）、medium（对象类型，例如 "Paintings"）、topic（主题术语，例如 "Quilts"）
• value 必须是已索引的确切类别术语——先用 smithsonian_list_terms 查询 museum、culture、period 和 topic 词汇；object_type 无法通过该工具枚举，因此需从 smithsonian_search_objects 结果中获取
• 返回总数、一页样例对象，以及显示哪些机构持有匹配藏品的博物馆分布（根据当前页计算）
• 使用 start + rows 进行标准分页（基于偏移量，start = page × rows，每页最多 50 条）——相邻页面可获取上限样例中遗漏的对象
• 与任何对象都不匹配的类别值会触发 invalid_category，并附带针对该模式的恢复提示：词汇表以外的值会提供可解析该值的确切 smithsonian_list_terms 调用；索引中有列出但未匹配到任何对象的值则会明确指出，并引导至其他位置
• 对于开放式或主题探索，请改用 smithsonian_search_objects——此工具要求提供确切的类别值

---

smithsonian_find_related _工具

• 将共同文化、具名方、主题以及时期 + 类型元数据，与更广泛的目录进行匹配；跨博物馆发现是其差异化优势——以 NASM 航空航天藏品为锚点，可能会找到来自 NMNH、SAAM 和 NMAH 的相关藏品
• 具名方信号采用目录中该方自身的角色（maker、collector、donor、issuing authority 等），而非固定的 maker 标签；如果记录中有索引 name 分面，则优先将其用作硬筛选条件；如果其值只是重复文化信号，则会舍弃该信号
• 主题信号是硬性 topic: 筛选条件，因此每件匹配的藏品都带有该主题词，而非仅仅提及该词
• 每个结果中的 similarity_signals 会列出所有将其与锚点关联起来的元数据词项——如果一件藏品由多个信号匹配，则会包含所有这些信号
• 使用 start 分页——它是交错排列的相关结果集中的 0 起始偏移量，start = page × limit；每个信号最多可获取 5,000 条结果（按每块 ≤1,000 行获取——较深的页面可能会在分页边界附近造成范围有限的结果位置偏移）；响应被截断时会报告 truncationCeiling，作为可访问相关结果池的上限
• signals[] 按信号细分扩展结果：row_count 是该信号在上游的实际结果数（不设上限，因此可能超过 5,000 条可访问范围），search_continuation 则是可在任意深度获取该信号完整匹配集的确切 smithsonian_search_objects 输入——这是获取超出此工具单信号访问范围结果的途径
• 部分失败会在分页说明的同一通知中，以安全类别标明失败的信号。成功但无结果时，会区分缺少锚点信号、没有非锚点匹配项以及页面已耗尽。所有搜索均失败时，会以首个信号的失败原因拒绝；调用方取消操作时始终会拒绝。

---

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

Smithsonian 专属功能：

• 封装 Smithsonian Open Access API（涵盖 20 多家博物馆的 1,450 万件藏品，其中 520 万件带有 CC0 媒体），使用免费的 api.data.gov 密钥
• smithsonian_get_media 实施 CC0 限制——只返回开放访问图像，绝不返回受限内容
• smithsonian_find_related 支持优雅降级——某个元数据信号失败不会中止其余操作
• 统一不同博物馆异构元数据架构的响应格式

面向 Agent 的输出：

• 每个藏品摘要都包含 has_media——Agent 无需额外查询即可判断是否调用图像下载；is_cc0 标记的是元数据许可证，而 Open Access 语料中的几乎所有藏品都带有此许可证
• 提供带类型的错误原因（no_results、invalid_filter、not_found、no_media、no_images、not_cc0、invalid_id），并为每种情况提供恢复提示
• 相关藏品结果中的 similarity_signals 让 Agent 能够说明藏品被展示的原因
• 所有搜索响应都包含 total_count，使 Agent 能在分页前说明结果范围

---

开始使用

公共托管实例

公共实例位于 https://smithsonian.caseyjhand.com/mcp——无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "smithsonian-mcp-server": {
      "type": "streamable-http",
      "url": "https://smithsonian.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

需要免费的 api.data.gov API 密钥——请前往 https://api.data.gov/signup 注册，并在配置中设置 SMITHSONIAN_API_KEY。

将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "smithsonian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/smithsonian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SMITHSONIAN_API_KEY": "your-api-key"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "smithsonian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/smithsonian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SMITHSONIAN_API_KEY": "your-api-key"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "smithsonian-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "SMITHSONIAN_API_KEY=your-api-key",
        "ghcr.io/cyanheads/smithsonian-mcp-server:latest"
      ]
    }
  }
}

使用 Streamable HTTP 时，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 SMITHSONIAN_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 免费的 api.data.gov API 密钥 — 在 https://api.data.gov/signup 注册。审核即时完成。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/smithsonian-mcp-server.git

2. 进入目录：

cd smithsonian-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# Edit .env and set SMITHSONIAN_API_KEY

---

配置

变量	描述	默认值
SMITHSONIAN_API_KEY	必需。 从 api.data.gov/signup 获取的免费 API 密钥。	—
SMITHSONIAN_BASE_URL	Smithsonian Open Access API 基础 URL。	https://api.si.edu/openaccess/api/v1.0
SMITHSONIAN_TERMS_CACHE_TTL_SECONDS	缓存每个已索引字段的术语词汇表的秒数。0 表示禁用缓存。	3600
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_SESSION_MODE	会话模式：auto、stateful 或 stateless。服务在代码中声明为 stateless；仅在需要覆盖时设置此项。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

完整的可选覆盖项列表请参阅 .env.example。

---

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t smithsonian-mcp-server .
docker run --rm -e SMITHSONIAN_API_KEY=your-api-key -p 3010:3010 smithsonian-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/smithsonian-mcp-server。默认会安装 OpenTelemetry 对等依赖项 — 若要省略这些依赖项，请使用 --build-arg OTEL_ENABLED=false 构建。

---

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具并初始化 Smithsonian 服务。
src/config	解析服务专用环境变量（SMITHSONIAN_API_KEY、SMITHSONIAN_BASE_URL、SMITHSONIAN_TERMS_CACHE_TTL_SECONDS）。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/services/smithsonian	Smithsonian Open Access API 客户端、规范化处理和类型定义。
tests/	单元测试和集成测试。
docs/	设计文档和目录树。

---

开发指南

开发指南和架构规则请参阅 CLAUDE.md / AGENTS.md。简要说明：

• 处理程序抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 在 src/index.ts 的 tools 数组中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不虚构缺失字段

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache-2.0 — 详情请参阅 LICENSE。