使用说明

项目简介

本项目 'unsplash-mcp-server' 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在为大型语言模型（LLM）应用提供便捷的图片搜索功能。它利用 Unsplash API 强大的图片库，通过 MCP 协议将图片搜索能力以标准化的方式提供给 LLM 客户端。

主要功能点

Unsplash 图片搜索: 通过 'searchPhotos' 工具，根据关键词从 Unsplash 平台搜索高质量图片。
MCP 协议支持: 遵循 MCP 协议标准，易于与各种支持 MCP 协议的 LLM 客户端集成。
工具化能力: 将 Unsplash 图片搜索封装为可被 LLM 调用的工具 (Tool)，实现功能扩展。
Java 开发: 使用 Java 和 Spring Boot 框架开发，稳定可靠，易于维护和扩展。
标准 Stdio 传输: 默认使用标准输入输出 (Stdio) 作为 MCP 服务器与客户端的通信协议。

安装步骤

克隆仓库

git clone https://github.com/JavaProgrammerLB/unsplash-mcp-server.git
cd unsplash-mcp-server

编译打包 确保已安装 Maven 和 JDK 17 或更高版本。执行 Maven 命令进行编译和打包：
```
mvn clean package
```
编译成功后，会在 'target' 目录下生成 'unsplash-mcp-server-1.0.jar' 文件。
获取 Unsplash Access Key
- 访问 Unsplash Developer 网站并创建一个应用。
- 在应用详情页中找到 Access Key，这是访问 Unsplash API 的凭证。

服务器配置

MCP 客户端需要配置 MCP 服务器的启动信息，以下是 'unsplash-mcp-server' 的标准 JSON 格式配置示例。请根据实际情况修改 'command' 和 'env' 部分。

{
  "mcpServers": {
    "unsplash": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true", // 启用 Stdio 传输协议
        "-Dspring.main.web-application-type=none", // 关闭 Web 应用功能，仅作为 MCP 服务器运行
        "-Dlogging.pattern.console=", // 关闭控制台日志输出，可选
        "-jar",
        "/ABSOLUTE/PATH/target/unsplash-mcp-server-1.0.jar" //  替换为 jar 文件的绝对路径
      ],
      "env": {
        "UNSPLASH_ACCESS_KEY": "${YOUR UNSPLASH ACCESS KEY}" // 替换为你的 Unsplash Access Key
      }
    }
  }
}

配置参数说明:

'server name': 'unsplash' - 服务器名称，客户端用于标识和调用。
'command': 'java' - 运行 MCP 服务器的命令，这里使用 Java 运行时环境。
'args': 启动参数列表，包括：
- '-Dspring.ai.mcp.server.stdio=true': 必须，指定使用 Stdio 作为 MCP 服务器的传输协议。
- '-Dspring.main.web-application-type=none': 推荐，禁用 Spring Boot 的 Web 应用功能，使服务器更专注于 MCP 服务。
- '-Dlogging.pattern.console=': 可选，用于精简控制台输出，生产环境可能需要调整日志配置。
- '-jar /ABSOLUTE/PATH/target/unsplash-mcp-server-1.0.jar': 必须，指定要运行的 JAR 文件路径，请替换为实际的绝对路径。
'env': 环境变量配置，用于传递敏感信息或配置参数。
- 'UNSPLASH_ACCESS_KEY': 必须，用于配置 Unsplash API 的 Access Key，请务必替换为你在 Unsplash 开发者平台申请的 Access Key。

注意: '/ABSOLUTE/PATH/target/unsplash-mcp-server-1.0.jar' 需要替换为 'unsplash-mcp-server-1.0.jar' 文件在您本地文件系统中的绝对路径。'${YOUR UNSPLASH ACCESS KEY}' 需要替换为您在 Unsplash 开发者平台申请的 Access Key。

基本使用方法

确保 MCP 服务器已根据上述配置启动并运行。
在 LLM 客户端中，配置并连接到名为 'unsplash' 的 MCP 服务器。
LLM 可以通过调用 'searchPhotos' 工具来使用 Unsplash 图片搜索功能。
'searchPhotos' 工具接受以下参数（均为字符串类型）：
- 'query': 搜索关键词 (必填)。例如："house", "cat", "mountain"。
- 'page': 页码 (可选)。默认为第一页。
- 'perPage': 每页图片数量 (可选)。默认为 1。
- 'orderBy': 排序方式 (可选)。可选值：'relevant' (相关性，默认), 'latest' (最新)。
- 'color': 颜色 (可选)。例如："black_and_white", "yellow", "green"。
- 'orientation': 图片方向 (可选)。可选值：'landscape', 'portrait', 'squarish'。
LLM 客户端调用 'searchPhotos' 工具后，MCP 服务器会向 Unsplash API 发起请求，并将搜索结果以 JSON 格式返回给客户端。返回的 JSON 结构包含了搜索到的图片信息，例如图片 ID、描述、URL、尺寸等。

示例 LLM 指令:

例如，如果 LLM 客户端希望搜索关于 "two house" 的图片，可以指示 MCP 服务器调用 'searchPhotos' 工具，并设置 'query' 参数为 "two house"。服务器将返回包含 "two house" 相关图片的 JSON 数据，LLM 可以根据这些数据进行后续处理，例如将图片描述写入文档，或者将图片 URL 提供给用户。

{
  "tool_calls": [
    {
      "id": "call_unsplash_search",
      "type": "function",
      "function": {
        "name": "searchPhotos",
        "arguments": "{\"query\": \"two house\"}"
      }
    }
  ]
}

关键词