JSONPlaceholder

Servidor MCP de JSONPlaceholder

Un servidor moderno de Model Context Protocol (MCP) construido con FastMCP que proporciona acceso a la API de JSONPlaceholder: una API REST falsa y gratuita para pruebas y prototipos.

Características

Este servidor MCP proporciona Recursos, Herramientas y Prompts para interactuar con JSONPlaceholder:

🔧 Herramientas (Acciones)

• get_posts - Obtener todas las publicaciones o una publicación específica por ID
• get_users - Obtener todos los usuarios o un usuario específico por ID
• get_comments - Obtener comentarios, opcionalmente filtrados por ID de publicación
• get_albums - Obtener álbumes, opcionalmente filtrados por ID de usuario
• get_photos - Obtener fotos, opcionalmente filtradas por ID de álbum
• get_todos - Obtener tareas, opcionalmente filtradas por ID de usuario
• create_post - Crear una nueva publicación (simulada)
• search_posts - Buscar publicaciones por título o contenido del cuerpo

📄 Recursos (Acceso a datos)

• posts://all - Obtener todas las publicaciones como recurso
• posts://{post_id} - Obtener una publicación específica como recurso
• users://all - Obtener todos los usuarios como recurso
• users://{user_id} - Obtener un usuario específico como recurso

📝 Prompts (Plantillas)

• analyze_post - Generar un prompt de análisis para una publicación específica
• user_profile_summary - Crear un análisis completo del perfil de usuario

Cómo agregarlo a cursor:

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

Requisitos previos

• Python 3.10+
• uv gestor de paquetes

Instalación

1. Clona o descarga este proyecto
2. El proyecto ya está configurado con uv. Simplemente ejecuta:

uv sync

Desarrollo y Pruebas

MCP Inspector (recomendado para desarrollo):

uv run mcp dev server.py

Esto abre una interfaz web interactiva para probar todas las herramientas, recursos y prompts.

Ejecución directa del servidor:

uv run python server.py

Probar conectividad de la API:

uv run python test_server.py

Integración con Claude Desktop

Instala directamente en Claude Desktop:

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

Ejemplos de uso

Una vez conectado a un cliente MCP, puedes:

Usar Herramientas:

• "Obtener todas las publicaciones de JSONPlaceholder"
• "Muéstrame los detalles del usuario con ID 1"
• "Buscar publicaciones que contengan 'dolor'"
• "Crear una nueva publicación titulada 'Test' con cuerpo 'Hello World' para el usuario 1"

Acceder a Recursos:

• El cliente puede cargar posts://all para obtener todas las publicaciones como contexto
• Cargar users://5 para obtener los detalles del usuario 5 como información de fondo

Usar Prompts:

• Usa el prompt "analyze_post" con el ID de publicación 1 para un análisis detallado de la publicación
• Usa "user_profile_summary" con el ID de usuario 2 para un perfilado completo del usuario

Información de la API

Este servidor utiliza la API de JSONPlaceholder (https://jsonplaceholder.typicode.com/), que proporciona:

• 100 publicaciones
• 10 usuarios
• 500 comentarios
• 100 álbumes
• 5000 fotos
• 200 tareas

No se requiere clave de API, ya que es completamente gratuita y pública.

Arquitectura

Construido con FastMCP, este servidor demuestra patrones MCP modernos:

• Configuración basada en decoradores - Código limpio y pitónico
• Type hints - Mejor experiencia de desarrollo
• Async/await - Solicitudes HTTP eficientes
• Gestión de recursos - Exposición adecuada de datos a los LLM
• Plantillas de prompts - Patrones de interacción reutilizables
• Herramientas de desarrollo - Pruebas y depuración integradas

Desarrollo

El servidor utiliza:

• FastMCP - Marco de trabajo moderno para servidores MCP
• httpx - Cliente HTTP asíncrono
• Python 3.10+ - Características modernas de Python
• uv - Gestión rápida de paquetes de Python