内容
<div align="center">
<h1>@cyanheads/met-museum-mcp-server</h1>
<p><b>搜索大都会艺术博物馆藏品，获取完整的艺术品记录和开放访问的图片，通过MCP。STDIO或流式HTTP。</b>
<div>3 个工具</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip) [](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip) [](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip) [](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip) [](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip)
</div>
<div align="center">
[](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip) [](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip) [](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip)
[](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip)
</div>
<div align="center">
**公共托管服务器：** [https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip)
</div>
---
## 工具列表
浏览和获取大都会艺术博物馆藏品数据的三个工具：
| 工具 | 描述 |
|:---|:---|
| `met_list_departments` | 返回所有19个策展部门及其数字ID和显示名称 |
| `met_search` | 按关键词搜索藏品，过滤部门、日期范围、媒介、地理、公共领域状态和突出指定 |
| `met_get_object` | 获取一个或多个对象ID的完整记录 — 元数据、来源、艺术家信息、CC0图像URL、标签和维基数据链接 |
### `met_list_departments`
返回大都会艺术博物馆的19个策展部门及其数字ID和显示名称。
- 实时获取 — 如果Met重新组织，保持准确
- 在`met_search`之前使用，以发现有效的`departmentId`值
---
### `met_search`
按关键词和可选过滤器搜索Met藏品。
- 关键词搜索标题、艺术家姓名、文化、媒介、标签和其他文本字段
- 按部门ID过滤（使用`met_list_departments`获取有效ID）
- 按日期范围过滤（整数年份，负数 = BCE）
- 按媒介/分类过滤（例如，“绘画”，“雕塑”，“陶瓷”）— 映射到分类字段，而不是材料描述
- 按地理来源过滤 — 国家、地区或城市；多个值通过AND组合
- `isPublicDomain=true` 限制为CC0开放访问对象（保证可用的图像URL）
- `hasImages=true` 包括具有图像的任何对象（包括具有版权作品的不可重用URL）
- `isHighlight=true` 限制为Met指定的藏品亮点
- 返回总匹配数、截断指示符和最多`limit`个对象ID（默认20，最大500）
- 将返回的ID链接到`met_get_object`，每批最多20个
---
### `met_get_object`
获取一个或多个Met博物馆对象ID的完整记录。
- 每次调用接受1-20个ID；并行获取（并发限制）
- 部分成功 — 单个404不会导致整个批次失败；报告失败的ID
- 完整元数据：标题、部门、分类、媒介、尺寸、日期、文化、时期、朝代、编号、信用线、画廊编号
- 艺术家数据：显示名称、传记、国籍、日期、盖蒂ULAN URL、维基数据URL
- 所有关联人员的数组（匿名/未归属作品为null）
- 具有盖蒂AAT和维基数据URL的受控词汇标签
- 用于人工后续的规范metmuseum.org URL
- CC0对象返回全分辨率和网络显示图像URL以及其他图像数组
- 对象级维基数据URL，用于通过外部知识图工具丰富
## 功能
基于[`@cyanheads/mcp-ts-core`](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip)：
- 声明式工具定义 — 每个工具的单个文件，框架处理注册和验证
- 统一错误处理 — 处理程序抛出，框架捕获、分类和格式化
- 可插拔身份验证：`none`，`jwt`，`oauth`
- 可交换存储后端：`in-memory`，`filesystem`，`Supabase`，`Cloudflare KV/R2/D1`
- 带有可选OpenTelemetry跟踪的结构化日志记录
- STDIO和流式HTTP传输
大都会艺术博物馆藏品：
- 5,000多年来超过50万件艺术品，来自Met的公共藏品API
- 来自[大都会艺术博物馆](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip)的CC0开放访问数据 — 免费使用，无需许可或署名
- `met_get_object`的并行批次获取，具有可配置的并发性
- 每个对象的链接数据 — Getty ULAN和AAT URL，艺术家、标签和作品的维基数据实体URL
代理友好输出：
- 每个记录的出处 — `isPublicDomain`和`hasImages`标志区分CC0对象与具有不可访问图像的作品，以便代理可以推理它们可以实际显示的内容
- 部分失败报告 — `met_get_object`返回`objects`和`failed`数组，以便调用者接收成功的记录以及结构化的每个ID错误上下文
- 截断信号 — `met_search`返回`total`、`returned`和`truncated`字段，以便代理知道何时细化过滤器或增加`limit`
## 入门指南
### 公共托管实例
公共实例可在`https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip`访问 — 无需安装。通过流式HTTP将任何MCP客户端指向它：
```json
{
"mcpServers": {
"met-museum-mcp-server": {
"type": "streamable-http",
"url": "https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip"
}
}
}
```
### 自托管 / 本地
将以下内容添加到您的MCP客户端配置文件中。
```json
{
"mcpServers": {
"met-museum-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/met-museum-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
或使用npx（无需Bun）：
```json
{
"mcpServers": {
"met-museum-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/met-museum-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
或使用Docker：
```json
{
"mcpServers": {
"met-museum-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"ghcr.io/cyanheads/met-museum-mcp-server:latest"
]
}
}
}
```
对于流式HTTP，设置传输并启动服务器：
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# 服务器监听 http://localhost:3010/mcp
```
### 先决条件
- [Bun v1.3.0](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip) 或更高版本（或Node.js v24+）。
- 无需API密钥 — Met Collection API是公开且无身份验证的。
### 安装
1. **克隆仓库：**
```sh
git clone https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip
```
2. **进入目录：**
```sh
cd met-museum-mcp-server
```
3. **安装依赖项：**
```sh
bun install
```
4. **配置环境：**
```sh
cp .env.example .env
# 根据需要编辑.env（所有变量都是可选的）
```
## 配置
所有配置在启动时通过`src/config/server-config.ts`中的Zod模式验证。
| 变量 | 描述 | 默认值 |
|:---|:---|:---|
| `MCP_TRANSPORT_TYPE` | 传输：`stdio` 或 `http` | `stdio` |
| `MCP_HTTP_PORT` | HTTP服务器端口 | `3010` |
| `MCP_AUTH_MODE` | 身份验证：`none`，`jwt` 或 `oauth` | `none` |
| `MCP_LOG_LEVEL` | 日志级别（`debug`，`info`，`warning`，`error`） | `info` |
| `LOGS_DIR` | 日志文件目录（仅限Node.js） | `<项目根目录>/logs` |
| `OTEL_ENABLED` | 启用OpenTelemetry仪表盘 | `false` |
| `MET_BASE_URL` | Met Collection API基本URL（用于本地存根的重写） | `https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip` |
| `MET_REQUEST_TIMEOUT_MS` | 每个请求的HTTP超时毫秒数 | `10000` |
| `MET_BATCH_CONCURRENCY` | `met_get_object`中的最大并行获取数 | `5` |
参见[`.env.example`](./.env.example) 获取完整的覆盖变量列表。
## 运行服务器
### 本地开发
- **构建和运行：
```sh
# 一次性构建
bun run rebuild
# 运行构建的服务器
bun run start:stdio
# 或
bun run start:http
```
- **运行检查和测试：
```sh
bun run devcheck # 校验、格式化、类型检查、安全检查
bun run test # Vitest测试套件
bun run lint:mcp # 验证MCP定义是否符合规范
```
### Docker
```sh
docker build -t met-museum-mcp-server .
docker run --rm -p 3010:3010 met-museum-mcp-server
```
Dockerfile默认使用HTTP传输、无状态会话模式和日志记录到`/var/log/met-museum-mcp-server`。OpenTelemetry对等依赖项默认安装 — 构建时添加 `--build-arg OTEL_ENABLED=false` 以省略它们。
## 项目结构
| 目录 | 目的 |
|:---|:---|
| `src/index.ts` | `createApp()` 入口点 — 注册工具并初始化Met服务。 |
| `src/config` | 服务器特定的环境变量解析和验证，使用Zod。 |
| `src/mcp-server/tools` | 工具定义（`*.tool.ts`）— `met_list_departments`，`met_search`，`met_get_object`。 |
| `src/services/met` | Met Collection API客户端 — HTTP，请求超时，响应规范化。 |
| `tests/` | 单元测试和集成测试，镜像`src/`。 |
## 开发指南
参见 [`CLAUDE.md`](./CLAUDE.md) 获取开发指南和架构规则。简要版本：
- 处理程序抛出，框架捕获 — 工具逻辑中没有 `try/catch`
- 使用 `ctx.log` 进行请求范围的日志记录，使用 `ctx.state` 进行租户范围的存储
- 通过 `src/index.ts` 中的数组注册新工具
- 包装外部API调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；从不构造缺失字段
## 贡献
欢迎提出问题和拉取请求。在提交之前运行检查和测试：
```sh
bun run devcheck
bun run test
```
来自[大都会艺术博物馆藏品API](https://github.com/ficaviolaodorata520/met-museum-mcp-server/raw/refs/heads/main/skills/api-utils/museum_mcp_server_met_v2.4.zip)（CC0）的数据。
## 许可证
Apache-2.0 — 参见 [LICENSE](LICENSE) 获取详细信息。
