API de Unsplash: FastAPI + FastMCP

Bifurcado de unsplash-api por @aliosmankaya

Tabla de contenido

• Descripción general

• Prerrequisitos

• Instalación

• Configuración

• Correr

• Puntos finales de API

  • Buscar

  • Fotos

  • Aleatorio

• Integración MCP

  • Descripción general de MCP

  • Puntos finales de MCP

  • Uso de modelos de IA

  • Cliente de ejemplo

• Desarrollo

• Licencia

Related MCP server: Unsplash Smart MCP Server

Descripción general

Este proyecto proporciona una API para acceder al servicio Unsplash, lo que permite buscar, listar y obtener imágenes aleatorias. Además, integra el Protocolo de Contexto de Modelo (MCP), lo que permite que modelos de IA como Claude interactúen directamente con la API de Unsplash.

FastAPI-MCP FastAPI

Prerrequisitos

Antes de utilizar la API de Unsplash, debes:

1. Regístrate como desarrollador en Unsplash

2. Obtenga su clave de acceso

3. Configure la clave como UNSPLASH_CLIENT_ID en el archivo .env

Instalación

Usando pip

# Clone the repository
git clone https://github.com/your-username/unsplash-api-mcp.git
cd unsplash-api-mcp

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit the .env file and add your UNSPLASH_CLIENT_ID

Usando Docker

# Clone the repository
git clone https://github.com/your-username/unsplash-api-mcp.git
cd unsplash-api-mcp

# Configure environment variables
cp .env.example .env
# Edit the .env file and add your UNSPLASH_CLIENT_ID

# Build and start the container
docker compose up -d

Configuración

Cree un archivo .env en la raíz del proyecto con el siguiente contenido:

UNSPLASH_CLIENT_ID=your_access_key_here

Correr

En la zona

python main.py

La API estará disponible en http://localhost:8000 .

Con Docker

docker compose up -d

La API estará disponible en http://localhost:8000 .

Acceda a la documentación interactiva de la API en http://localhost:8000/docs .

Puntos finales de API

Buscar

Punto final para buscar imágenes en Unsplash.

Punto final: /search

Método: GET

Parámetros:

• query : término de búsqueda (predeterminado: "naturaleza")

• page : Número de página (Predeterminado: 1)

• per_page : Número de fotos por página (Predeterminado: 10)

• order_by : Orden de fotos (Predeterminado: "relevante", Opciones: "relevante", "más reciente")

Ejemplo de solicitud:

GET /search?query=mountains&page=1&per_page=5&order_by=latest

Ejemplo de respuesta:

[
  {
    "alt_description": "mountain range under cloudy sky",
    "created_at": "2023-05-15T12:34:56Z",
    "username": "Photographer Name",
    "image_link": "https://images.unsplash.com/photo-...",
    "download_link": "https://unsplash.com/photos/...",
    "likes": 123
  },
  ...
]

Fotos

Punto final para enumerar fotos desde la página de destino de Unsplash.

Punto final: /photos

Método: GET

Parámetros:

• page : Número de página (Predeterminado: 1)

• per_page : Número de fotos por página (Predeterminado: 10)

• order_by : Orden de fotos (Predeterminado: "más reciente", Opciones: "más reciente", "más antigua", "popular")

Ejemplo de solicitud:

GET /photos?page=1&per_page=5&order_by=popular

Ejemplo de respuesta:

[
  {
    "alt_description": "scenic view of mountains during daytime",
    "created_at": "2023-06-20T10:15:30Z",
    "username": "Photographer Name",
    "image_link": "https://images.unsplash.com/photo-...",
    "download_link": "https://unsplash.com/photos/...",
    "likes": 456
  },
  ...
]

Aleatorio

Punto final para obtener fotos aleatorias de Unsplash.

Punto final: /random

Método: GET

Parámetros:

• query : Término de búsqueda para filtrar fotos aleatorias (Predeterminado: "naturaleza")

• count : Número de fotos a devolver (Predeterminado: 1, Máximo: 30)

Ejemplo de solicitud:

GET /random?query=ocean&count=3

Ejemplo de respuesta:

[
  {
    "alt_description": "blue ocean waves crashing on shore",
    "created_at": "2023-04-10T08:45:22Z",
    "username": "Photographer Name",
    "image_link": "https://images.unsplash.com/photo-...",
    "download_link": "https://unsplash.com/photos/...",
    "likes": 789
  },
  ...
]

Para obtener más información sobre la API de Unsplash, consulte la documentación oficial .

Integración MCP

Descripción general de MCP

El Protocolo de Contexto de Modelo (MCP) permite que los modelos de IA interactúen directamente con las API y los servicios. Esta implementación utiliza FastAPI-MCP para exponer los endpoints de la API de Unsplash como herramientas MCP.

Puntos finales de MCP

El servidor MCP está disponible en /mcp y expone todos los puntos finales de API como herramientas MCP:

• buscar : Buscar imágenes en Unsplash

• fotos : Lista de fotos de la página de destino

• aleatorio : Consigue fotos aleatorias

Uso de modelos de IA

Los modelos de IA que admiten MCP pueden conectarse a esta API mediante:

http://your-server:8000/mcp

Para Claude, puedes configurar la conexión en la configuración del modelo o mediante API.

Cliente de ejemplo

Puedes probar el servidor MCP con un cliente Python simple:

import requests

def test_mcp_metadata():
    """Test if the MCP server is working correctly."""
    response = requests.get("http://localhost:8000/mcp/.well-known/mcp-metadata")
    if response.status_code == 200:
        print("MCP server working correctly!")
        print(f"Response: {response.json()}")
    else:
        print(f"Error: {response.text}")

def list_mcp_tools():
    """List the available tools in the MCP server."""
    response = requests.post(
        "http://localhost:8000/mcp/jsonrpc",
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "mcp/list_tools"
        }
    )
    if response.status_code == 200:
        print("Available MCP tools:")
        for tool in response.json()["result"]["tools"]:
            print(f"- {tool['name']}: {tool['description']}")
    else:
        print(f"Error: {response.text}")

if __name__ == "__main__":
    test_mcp_metadata()
    list_mcp_tools()

Para obtener más información sobre el uso de MCP, consulte el archivo MCP_USAGE.md .

Desarrollo

Para contribuir al desarrollo:

1. Clonar el repositorio

2. Instalar dependencias de desarrollo: pip install -r requirements.txt

3. Crea un archivo .env con tu clave API de Unsplash

4. Ejecute el servidor en modo de desarrollo: python main.py

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.