Unsplash API MCP Server

# Guia de Uso do Model Context Protocol (MCP)

Este documento fornece informações detalhadas sobre como usar a integração do Model Context Protocol (MCP) com a API Unsplash.

## Índice

- [Introdução ao MCP](#introdução-ao-mcp)
- [Configuração do Servidor MCP](#configuração-do-servidor-mcp)
- [Ferramentas MCP Disponíveis](#ferramentas-mcp-disponíveis)
- [Uso do MCP com Modelos de IA](#uso-do-mcp-com-modelos-de-ia)
  - [Claude](#claude)
  - [Outros Modelos Compatíveis com MCP](#outros-modelos-compatíveis-com-mcp)
- [Uso Avançado](#uso-avançado)
- [Solução de Problemas](#solução-de-problemas)

## Introdução ao MCP

O Model Context Protocol (MCP) é um padrão aberto que permite que modelos de IA interajam com ferramentas e serviços externos de forma estruturada. Ele fornece uma interface padronizada para que modelos de IA possam:

- Descobrir ferramentas disponíveis e suas capacidades
- Chamar ferramentas com parâmetros específicos
- Receber respostas estruturadas das ferramentas

Esta implementação usa o [FastAPI-MCP](https://github.com/tadata-org/fastapi-mcp), que converte automaticamente endpoints FastAPI em ferramentas MCP.

## Configuração do Servidor MCP

O servidor MCP é configurado no arquivo `src/app/api.py`:

```python
from fastapi_mcp import FastApiMCP

app = FastAPI(description="Unsplash API")

# Cria instância do FastAPI-MCP
mcp = FastApiMCP(app)

# Monta o servidor MCP
mcp.mount(mount_path="/mcp", transport="sse")
```

O servidor MCP está disponível em `/mcp` e usa Server-Sent Events (SSE) como mecanismo de transporte.

## Ferramentas MCP Disponíveis

O servidor MCP expõe as seguintes ferramentas:

### 1. Ferramenta de Busca (Search)

**Nome:** `search_photos`

**Descrição:** Busca imagens no Unsplash com base em uma consulta. Retorna metadados incluindo descrição, autor, links e curtidas.

**Parâmetros:**

- `query` (string): Termo de busca (Padrão: "nature")
- `page` (integer): Número da página (Padrão: 1)
- `per_page` (integer): Quantidade de fotos por página (Padrão: 10)
- `order_by` (string): Ordenação das fotos (Padrão: "relevant", Opções: "relevant", "latest")

**Exemplo de Chamada:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "mcp/call_tool",
  "params": {
    "name": "search_photos",
    "arguments": {
      "query": "mountains",
      "page": 1,
      "per_page": 5,
      "order_by": "latest"
    }
  }
}
```

### 2. Ferramenta de Fotos (Photos)

**Nome:** `get_photos`

**Descrição:** Recupera uma coleção de fotos do Unsplash. Retorna metadados incluindo descrição, autor, links e curtidas.

**Parâmetros:**

- `page` (integer): Número da página (Padrão: 1)
- `per_page` (integer): Quantidade de fotos por página (Padrão: 10)
- `order_by` (string): Ordenação das fotos (Padrão: "latest", Opções: "latest", "oldest", "popular")

**Exemplo de Chamada:**

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "mcp/call_tool",
  "params": {
    "name": "get_photos",
    "arguments": {
      "page": 1,
      "per_page": 5,
      "order_by": "popular"
    }
  }
}
```

### 3. Ferramenta de Fotos Aleatórias (Random)

**Nome:** `get_random_photos`

**Descrição:** Obtém fotos aleatórias do Unsplash com base em uma consulta opcional. Retorna metadados incluindo descrição, autor, links e curtidas.

**Parâmetros:**

- `query` (string): Termo de busca para filtrar as fotos aleatórias (Padrão: "nature")
- `count` (integer): Quantidade de fotos a serem retornadas (Padrão: 1, Máximo: 30)

**Exemplo de Chamada:**

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "mcp/call_tool",
  "params": {
    "name": "get_random_photos",
    "arguments": {
      "query": "ocean",
      "count": 3
    }
  }
}
```

## Uso do MCP com Modelos de IA

### Claude

Para usar a API Unsplash MCP com o Claude:

1. Inicie o servidor da API Unsplash:

   ```bash
   python main.py
   ```

2. No Claude Desktop:

   - Vá para Configurações > Ferramentas
   - Clique em "Adicionar Ferramenta"
   - Digite a URL do servidor MCP: `http://localhost:8000/mcp`
   - Nomeie a ferramenta (ex: "API Unsplash")
   - Clique em "Adicionar"

3. Na sua conversa com o Claude, você pode agora pedir para:
   - Buscar imagens no Unsplash
   - Obter fotos populares
   - Encontrar imagens aleatórias sobre tópicos específicos

Exemplos de prompts:

- "Encontre algumas fotos de paisagens montanhosas no Unsplash"
- "Mostre-me as fotos mais populares no Unsplash agora"
- "Obtenha 3 fotos aleatórias de oceano do Unsplash"

### Outros Modelos Compatíveis com MCP

Para outros modelos compatíveis com MCP, consulte a documentação específica sobre como conectar servidores MCP externos. A URL de conexão será:

```
http://seu-servidor:8000/mcp
```

## Uso Avançado

### Cliente MCP Personalizado

Você pode criar um cliente MCP personalizado para interagir com o servidor programaticamente:

```python
import requests
import json

class UnsplashMCPClient:
    def __init__(self, base_url="http://localhost:8000/mcp"):
        self.base_url = base_url
        self.jsonrpc_url = f"{base_url}/jsonrpc"
        self.request_id = 0

    def _make_request(self, method, params=None):
        self.request_id += 1
        payload = {
            "jsonrpc": "2.0",
            "id": self.request_id,
            "method": method
        }
        if params:
            payload["params"] = params

        response = requests.post(self.jsonrpc_url, json=payload)
        return response.json()

    def list_tools(self):
        return self._make_request("mcp/list_tools")

    def search_photos(self, query="nature", page=1, per_page=10, order_by="relevant"):
        return self._make_request("mcp/call_tool", {
            "name": "search_photos",
            "arguments": {
                "query": query,
                "page": page,
                "per_page": per_page,
                "order_by": order_by
            }
        })

    def get_photos(self, page=1, per_page=10, order_by="latest"):
        return self._make_request("mcp/call_tool", {
            "name": "get_photos",
            "arguments": {
                "page": page,
                "per_page": per_page,
                "order_by": order_by
            }
        })

    def get_random_photos(self, query="nature", count=1):
        return self._make_request("mcp/call_tool", {
            "name": "get_random_photos",
            "arguments": {
                "query": query,
                "count": count
            }
        })

# Exemplo de uso
if __name__ == "__main__":
    client = UnsplashMCPClient()

    # Listar ferramentas disponíveis
    tools = client.list_tools()
    print(json.dumps(tools, indent=2))

    # Buscar fotos de montanhas
    mountain_photos = client.search_photos("mountains", per_page=3)
    print(json.dumps(mountain_photos, indent=2))
```

## Solução de Problemas

### Problemas Comuns

1. **Conexão Recusada**

   Se você receber um erro "Connection Refused", verifique:

   - Se o servidor da API Unsplash está em execução
   - Se você está usando a porta correta (padrão: 8000)
   - Se não há problemas de firewall bloqueando a conexão

2. **Erros de Autenticação**

   Se você receber erros de autenticação do Unsplash:

   - Verifique se seu `UNSPLASH_CLIENT_ID` está configurado corretamente no arquivo `.env`
   - Verifique se sua chave de API Unsplash é válida e não excedeu os limites de taxa

3. **Erros de Protocolo MCP**

   Se você receber erros de protocolo MCP:

   - Verifique se está usando o formato JSON-RPC correto
   - Verifique se o nome da ferramenta e os parâmetros estão corretos
   - Certifique-se de que está usando o endpoint MCP correto (`/mcp/jsonrpc`)

### Depuração

Para habilitar o registro de depuração para o servidor MCP, modifique o arquivo `src/app/api.py`:

```python
import logging

# Configura o logger para requisições MCP com nível DEBUG
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("mcp_logger")
```

Isso fornecerá logs mais detalhados sobre requisições e respostas MCP.

### Obtendo Ajuda

Se você encontrar problemas não abordados neste guia:

1. Verifique a [documentação do FastAPI-MCP](https://github.com/tadata-org/fastapi-mcp)
2. Abra uma issue no repositório GitHub do projeto
3. Consulte a [especificação MCP](https://modelcontextprotocol.io) para detalhes do protocolo