MCP Openverse

🚀 @mcp/openverse

@mcp/openverse 是一個 MCP（模型上下文協議）服務器，它提供了從 Openverse 搜索和獲取開放許可圖像的工具。藉助該服務器，用戶能夠輕鬆地找到符合各種需求的開放許可圖像。

🚀 快速開始

你可以通過以下步驟快速使用 @mcp/openverse 服務器：

1. 安裝服務器（具體安裝方式見“📦 安裝指南”）。
2. 配置 Claude Desktop（具體配置方式見“💻 使用示例”）。
3. 開始使用服務器提供的工具進行圖像搜索和獲取。

✨ 主要特性

• 🔍 搜索知識共享許可（CC）和公共領域的圖像。
• 🎨 可以按許可類型、來源、文件格式等進行過濾。
• 📊 獲取包含版權聲明的詳細圖像信息。
• 🔗 查找相關圖像。
• 📝 針對文章內容進行特定的圖像搜索，用於內容配圖。
• ⚡ 使用 TypeScript 和 fastmcp 構建，性能卓越。

📦 安裝指南

你可以通過以下兩種方式安裝 @mcp/openverse：

使用 npm 全局安裝

npm install -g @mcp/openverse

從源代碼安裝

git clone https://github.com/yourusername/mcp-openverse.git
cd mcp-openverse
npm install
npm run build
npm link

💻 使用示例

作為 MCP 服務器使用

將以下配置添加到你的 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "openverse": {
      "command": "npx",
      "args": ["@mcp/openverse"]
    }
  }
}

如果你是本地安裝的，可以使用以下配置：

{
  "mcpServers": {
    "openverse": {
      "command": "node",
      "args": ["/path/to/mcp-openverse/dist/index.js"]
    }
  }
}

可用工具

search_images

使用各種過濾器搜索開放許可的圖像。

參數說明：

• query（必填）：搜索詞。
• page：頁碼（默認值：1）。
• page_size：每頁結果數（默認值：20，最大值：500）。
• license：許可類型（如 by, by-sa, by-nc, by-nd, cc0 等）。
• license_type：commercial 或 modification。
• creator：按創作者名稱過濾。
• source：按來源過濾（如 flickr, wikimedia, met 等）。
• extension：文件類型（如 jpg, png, gif, svg）。
• aspect_ratio：tall, wide, 或 square。
• size：small, medium, 或 large。
• mature：是否包含成人內容（默認值：false）。

示例：

// 搜索具有商業許可的自然照片
{
  "query": "forest landscape",
  "page_size": 10,
  "license_type": "commercial",
  "extension": "jpg",
  "aspect_ratio": "wide"
}

get_image_details

獲取特定圖像的詳細信息。

參數說明：

• image_id（必填）：Openverse 圖像 ID（UUID 格式）。

get_related_images

查找與特定圖像相關的圖像。

參數說明：

• image_id（必填）：要查找相關圖像的圖像 ID。
• page：頁碼（默認值：1）。
• page_size：每頁結果數（默認值：10）。

get_image_stats

按來源獲取可用圖像的統計信息。

參數說明：無。

search_images_for_essay

用於為文章或論文查找配圖的高級工具。

參數說明：

• essay_topic（必填）：文章的主要主題/標題。
• concepts（必填）：用於查找圖像的關鍵概念數組。
• style：photo, illustration, 或 any（默認值：any）。
• max_images：返回的最大圖像數（默認值：10）。

示例：

{
  "essay_topic": "Climate Change",
  "concepts": ["global warming", "renewable energy", "carbon emissions"],
  "style": "photo",
  "max_images": 15
}

📚 詳細文檔

圖像版權聲明

所有來自 Openverse 的圖像都有版權聲明要求。API 提供以下信息：

• attribution：預格式化的版權聲明文本。
• license：許可代碼（如 'by-sa'）。
• license_url：許可鏈接。
• creator：原始創作者/攝影師。
• creator_url：創作者資料鏈接。

在使用圖像時，請始終包含適當的版權聲明。

速率限制

Openverse API 有以下速率限制：

• 匿名訪問：每天 100 個請求，每小時 5 個請求。
• 認證訪問：每天 10,000 個請求，每分鐘 100 個請求。

此 MCP 服務器目前使用匿名訪問。如需更高的速率限制，請考慮實現 OAuth 認證。

開發相關

從源代碼構建

npm install
npm run build

在開發模式下運行

npm run dev

測試服務器

你可以使用 MCP 檢查器來測試服務器：

npx @modelcontextprotocol/inspector dist/index.js

示例

為博客文章查找圖像

// 使用 search_images_for_essay 工具
{
  "essay_topic": "Sustainable Architecture",
  "concepts": ["green building", "solar panels", "eco-friendly design"],
  "style": "photo",
  "max_images": 10
}

使用特定要求進行搜索

// 使用 search_images 工具
{
  "query": "mountain landscape sunrise",
  "aspect_ratio": "wide",
  "license_type": "commercial",
  "extension": "jpg",
  "size": "large",
  "page_size": 20
}

故障排除

常見問題

1. 速率限制錯誤：你達到了匿名 API 的限制。請等待一小時或實現認證。
2. 無搜索結果：請嘗試使用更寬泛的搜索詞或移除過濾器。
3. 連接錯誤：請檢查你的互聯網連接和防火牆設置。

調試模式

設置 DEBUG 環境變量：

DEBUG=mcp:* npx @mcp/openverse

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

貢獻說明

歡迎貢獻代碼！請隨時提交拉取請求。

開發指南

1. 遵循 TypeScript 最佳實踐。
2. 為新功能添加測試。
3. 更新文檔。
4. 確保所有工具都有適當的錯誤處理。

致謝

• Openverse 提供 API 和開放許可內容。
• WordPress 維護 Openverse 項目。
• fastmcp 提供優秀的 MCP 框架。