JSONPlaceholder

Servidor MCP JSONPlaceholder

Um servidor moderno de Model Context Protocol (MCP) construído com FastMCP que fornece acesso à API JSONPlaceholder - uma API REST falsa e gratuita para testes e prototipagem.

Recursos

Este servidor MCP fornece Recursos, Ferramentas e Prompts para interagir com o JSONPlaceholder:

🔧 Ferramentas (Ações)

• get_posts - Recuperar todos os posts ou um post específico por ID
• get_users - Recuperar todos os usuários ou um usuário específico por ID
• get_comments - Recuperar comentários, opcionalmente filtrados por ID do post
• get_albums - Recuperar álbuns, opcionalmente filtrados por ID do usuário
• get_photos - Recuperar fotos, opcionalmente filtradas por ID do álbum
• get_todos - Recuperar tarefas (todos), opcionalmente filtradas por ID do usuário
• create_post - Criar um novo post (simulado)
• search_posts - Pesquisar posts por título ou conteúdo do corpo

📄 Recursos (Acesso a Dados)

• posts://all - Obter todos os posts como um recurso
• posts://{post_id} - Obter um post específico como um recurso
• users://all - Obter todos os usuários como um recurso
• users://{user_id} - Obter um usuário específico como um recurso

📝 Prompts (Modelos)

• analyze_post - Gerar prompt de análise para um post específico
• user_profile_summary - Criar análise abrangente do perfil do usuário

Como adicioná-lo ao cursor:

  "mcpServers": {
    "jsonplaceholder": {
      "command": "/Users/danielpopa/Projects/work/mcp-server/cursor_runner.sh",
      "args": []
    }
  }
} 

Pré-requisitos

• Python 3.10+
• uv gerenciador de pacotes

Instalação

1. Clone ou baixe este projeto
2. O projeto já está configurado com uv. Basta executar:

uv sync

Desenvolvimento e Testes

MCP Inspector (recomendado para desenvolvimento):

uv run mcp dev server.py

Isso abre uma interface web interativa para testar todas as ferramentas, recursos e prompts.

Execução direta do servidor:

uv run python server.py

Testar conectividade da API:

uv run python test_server.py

Integração com Claude Desktop

Instale diretamente no Claude Desktop:

uv run mcp install server.py --name "JSONPlaceholder API"

Exemplos de Uso

Depois de conectado a um cliente MCP, você pode:

Usar Ferramentas:

• "Obter todos os posts do JSONPlaceholder"
• "Mostre-me os detalhes do usuário com ID 1"
• "Pesquisar posts contendo 'dolor'"
• "Criar um novo post intitulado 'Test' com corpo 'Hello World' para o usuário 1"

Acessar Recursos:

• O cliente pode carregar posts://all para obter todos os posts como contexto
• Carregar users://5 para obter os detalhes do usuário 5 como informação de contexto

Usar Prompts:

• Use o prompt "analyze_post" com o ID do post 1 para análise detalhada do post
• Use "user_profile_summary" com o ID do usuário 2 para perfil abrangente do usuário

Informações da API

Este servidor usa a API JSONPlaceholder (https://jsonplaceholder.typicode.com/), que fornece:

• 100 posts
• 10 usuários
• 500 comentários
• 100 álbuns
• 5000 fotos
• 200 tarefas (todos)

Nenhuma chave de API é necessária, pois é completamente gratuito e público.

Arquitetura

Construído com FastMCP, este servidor demonstra padrões modernos de MCP:

• Configuração baseada em decoradores - Código limpo e Pythonico
• Type hints - Melhor experiência de desenvolvimento
• Async/await - Requisições HTTP eficientes
• Gerenciamento de recursos - Exposição adequada de dados para LLMs
• Modelos de prompt - Padrões de interação reutilizáveis
• Ferramentas de desenvolvimento - Testes e depuração integrados

Desenvolvimento

O servidor usa:

• FastMCP - Framework moderno de servidor MCP
• httpx - Cliente HTTP assíncrono
• Python 3.10+ - Recursos modernos de Python
• uv - Gerenciamento rápido de pacotes Python