Bluesky MCP

Servidor Bluesky MCP

Un servidor Model Context Protocol (MCP) que proporciona acceso integral a Bluesky/AT Protocol para asistentes de IA. Construido en TypeScript, desplegado en Vercel y totalmente compatible con el transporte HTTP Streamable de MCP (versión de protocolo 2025-03-26).

Características

• Operaciones de publicaciones — Crear publicaciones, obtener publicaciones, ver me gusta y republicaciones
• Gestión de feeds — Línea temporal, feeds personalizados, feeds de autor
• Motor de búsqueda — Buscar publicaciones y usuarios/actores
• Acceso a perfiles — Ver perfiles, conteos de seguidores, biografías (individual y por lotes)
• Visualización de hilos — Explorar hilos de publicaciones y conversaciones
• Marcadores — Crear, eliminar y listar marcadores privados
• Verificación de edad — Iniciar flujo, obtener configuración y estado
• Gestión segura de credenciales — Credenciales inyectadas por solicitud mediante cabeceras, nunca almacenadas
• HTTP Streamable — Soporte completo de transporte MCP (POST + GET + OPTIONS)
• Autenticación multi-cliente — Tres métodos de credenciales para diferentes clientes MCP
• Listo para Vercel — Despliegue serverless sin estado

---

Inicio rápido

1. Desplegar en Vercel

Haz clic en el botón de arriba, o clona y despliega manualmente:

git clone https://github.com/Ravishka17/Bluesky-MCP.git
cd Bluesky-MCP
vercel

2. Crear una contraseña de aplicación de Bluesky

1. Inicia sesión en Bluesky
2. Ve a Configuración → Contraseñas de aplicación
3. Crea una nueva contraseña de aplicación
4. Anota tu handle (p. ej. yourname.bsky.social) y la contraseña generada

3. Conecta tu cliente de IA

Endpoint MCP: https://your-app.vercel.app/mcp

---

Autenticación

Las credenciales nunca se almacenan en el servidor. Se envían por solicitud mediante cabeceras HTTP y se mantienen en memoria solo durante la duración de esa solicitud.

Se admiten tres métodos de credenciales, con el siguiente orden de prioridad:

Método 1 — Dos cabeceras separadas

Mejor para: HuggingChat, curl, cualquier cliente que admita cabeceras personalizadas.

Cabecera	Valor
X-BLUESKY-IDENTIFIER	Tu handle o correo electrónico
X-BLUESKY-PASSWORD	Tu contraseña de aplicación

curl -X POST https://your-app.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -H "X-BLUESKY-IDENTIFIER: yourname.bsky.social" \
  -H "X-BLUESKY-PASSWORD: your-app-password" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Método 2 — Cabecera única combinada

Mejor para: Mistral Vibe CLI, clientes con un solo campo api_key_header.

Formato: handle:app-password (se divide solo en el primer carácter de dos puntos, por lo que las contraseñas que contengan dos puntos son seguras)

X-BLUESKY-CREDENTIALS: yourname.bsky.social:your-app-password

Método 3 — Autorización Bearer

Mejor para: MCP Playground, clientes compatibles con OpenAI, cualquier herramienta que utilice la cabecera Authorization.

Authorization: Bearer yourname.bsky.social:your-app-password

---

Configuración del cliente

HuggingChat

En el diálogo Añadir servidor MCP, expande HTTP Headers y añade:

Nombre de cabecera	Valor
X-BLUESKY-IDENTIFIER	yourname.bsky.social
X-BLUESKY-PASSWORD	your-app-password

Claude Desktop

{
  "mcpServers": {
    "bluesky": {
      "type": "http",
      "url": "https://your-app.vercel.app/mcp",
      "headers": {
        "X-BLUESKY-IDENTIFIER": "yourname.bsky.social",
        "X-BLUESKY-PASSWORD": "your-app-password"
      }
    }
  }
}

Claude Code / CLI

claude mcp add bluesky --transport http https://your-app.vercel.app/mcp

Mistral Vibe (~/.vibe/config.toml)

[[mcp_servers]]
name = "bluesky"
transport = "streamable-http"
url = "https://your-app.vercel.app/mcp"
api_key_env = "BLUESKY_CREDENTIALS"
api_key_header = "X-BLUESKY-CREDENTIALS"
api_key_format = "{}"

Luego establece en ~/.vibe/.env:

BLUESKY_CREDENTIALS=yourname.bsky.social:your-app-password

Clientes basados en YAML (config.yaml)

Para herramientas como Hermes Agent (Nous Research) y otros clientes MCP configurados con YAML:

mcp_servers:
  bluesky:
    url: https://your-app.vercel.app/mcp
    headers:
      X-BLUESKY-CREDENTIALS: "${BLUESKY_CREDENTIALS}"

Configura en tu shell o en el archivo .env:

BLUESKY_CREDENTIALS=yourname.bsky.social:your-app-password

Ejemplo de Hermes Agent (config.yaml):

mcp_servers:
  bluesky:
    url: https://your-app.vercel.app/mcp
    headers:
      X-BLUESKY-CREDENTIALS: "${BLUESKY_CREDENTIALS}"

MCP Playground

• URL del servidor remoto: https://your-app.vercel.app/mcp
• Cabecera de autenticación: Bearer yourname.bsky.social:your-app-password

Cliente MCP genérico

Configura el tipo de transporte streamable-http con la URL del endpoint y cualquiera de los tres métodos de autenticación anteriores.

---

Herramientas MCP

Operaciones de publicaciones

Herramienta	Descripción	Autenticación requerida
create_post	Crear una nueva publicación (máx. 300 caracteres, respuesta/idioma opcional)	✅
get_posts	Obtener publicaciones específicas por URI (hasta 25)	❌
get_likes	Obtener usuarios que dieron me gusta a una publicación	❌
get_reposted_by	Obtener usuarios que republicaron una publicación	❌
like_post	Dar me gusta a una publicación	✅
repost_post	Republicar una publicación	✅

Operaciones de feed

Herramienta	Descripción	Autenticación requerida
get_timeline	Obtener la línea temporal de inicio (cuentas seguidas)	✅
get_feed	Obtener publicaciones de un generador de feeds (URI at://)	❌
get_author_feed	Obtener publicaciones de un usuario específico	❌
get_thread	Obtener hilo de publicaciones con respuestas y padres	❌

Operaciones de perfil

Herramienta	Descripción	Autenticación requerida
get_profile	Obtener perfil detallado de un solo usuario	❌
get_profiles	Obtener perfiles de varios usuarios (lote, hasta 25)	❌
get_suggestions	Obtener usuarios sugeridos para seguir	✅

Operaciones de búsqueda

Herramienta	Descripción	Autenticación requerida
search_posts	Buscar publicaciones por palabra clave, autor, idioma, menciones	❌
search_actors	Buscar usuarios por nombre o handle	❌
search_actors_typeahead	Autocompletar búsqueda de usuarios	❌

Operaciones de cuenta

Herramienta	Descripción	Autenticación requerida
get_preferences	Obtener preferencias de cuenta y filtros de contenido	✅
update_email	Actualizar la dirección de correo electrónico asociada a la cuenta	✅

Operaciones de servidor / gestión de cuentas

Herramienta	Descripción	Autenticación requerida
admin_send_email	Enviar un correo electrónico como administrador de PDS	✅
confirm_email	Confirmar una dirección de correo electrónico mediante un token de verificación	✅
create_account	Crear una nueva cuenta Bluesky/AT Protocol	❌
create_app_password	Crear una nueva contraseña de aplicación para la cuenta	✅
create_invite_code	Crear un único código de invitación	✅
create_invite_codes	Crear múltiples códigos de invitación a la vez	✅
create_session	Crear una sesión de autenticación (inicio de sesión)	❌
deactivate_account	Desactivar la cuenta autenticada	✅
delete_account	Eliminar permanentemente la cuenta autenticada	✅
delete_session	Invalidar la sesión actual	✅
describe_server	Obtener información del servidor PDS	❌
get_account_invite_codes	Obtener códigos de invitación de la cuenta	✅
get_service_auth	Obtener un JWT firmado para autenticación de servicio	✅
get_session	Obtener detalles de la sesión actual	✅
list_app_passwords	Listar todas las contraseñas de aplicación	✅
refresh_session	Refrescar tokens de sesión	✅

Operaciones de marcadores

Herramienta	Descripción	Autenticación requerida
create_bookmark	Guardar una publicación como marcador privado	✅
delete_bookmark	Eliminar un marcador por URI	✅
get_bookmarks	Listar todos los marcadores privados	✅

Operaciones de verificación de edad

Herramienta	Descripción	Autenticación requerida
begin_age_assurance	Iniciar el flujo de verificación de edad	✅
get_age_assurance_config	Obtener configuración del proveedor de verificación de edad	✅
get_age_assurance_state	Obtener el estado actual de verificación de edad	✅

Utilidad

Herramienta	Descripción	Autenticación requerida
test_connectivity	Probar conexión y verificar estado de autenticación	❌

---

Prompts MCP

Prompt	Descripción
bluesky_usage_guide	Guía completa para tareas de Bluesky
search_posts_template	Plantilla para buscar publicaciones
compose_post	Plantilla para componer publicaciones

---

Verificar el despliegue

# Health check
curl https://your-app.vercel.app/health

# Check available auth methods
curl https://your-app.vercel.app/mcp

# Test MCP initialize
curl -X POST https://your-app.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

---

Seguridad

1. Las credenciales nunca se almacenan — ni en variables de entorno de Vercel, ni en git, ni en disco
2. Inyección por solicitud — las credenciales se pasan en cabeceras y se mantienen en memoria solo para esa solicitud
3. Tres métodos de autenticación — flexibles para cualquier cliente sin comprometer la seguridad
4. Sanitización de entradas — todas las entradas se validan y sanitizan antes de llegar a la API de Bluesky
5. Límite de velocidad — límites escalonados para operaciones de lectura vs. escritura
6. Cabeceras de seguridad — X-Frame-Options, X-Content-Type-Options, etc.

---

Desarrollo

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

Para desarrollo local, las credenciales pueden pasarse mediante cabeceras en cada solicitud. No se necesitan variables de entorno.

---

Arquitectura

Bluesky-MCP/
├── app/
│   ├── mcp/route.ts        # MCP endpoint — credential extraction + transport
│   ├── health/route.ts     # Health check
│   ├── layout.tsx
│   └── page.tsx
├── src/
│   ├── mcp-server.ts       # MCP server — tool routing, credential injection
│   ├── bluesky-client.ts   # Bluesky API client (all methods)
│   ├── handlers.ts         # Tool handlers
│   ├── toolDefinitions.ts  # Tool schemas
│   ├── sanitize.ts         # Input sanitization
│   ├── middleware.ts       # Rate limiting, security headers
│   ├── types.ts            # TypeScript types
│   └── utils.ts            # Utilities
├── vercel.json
└── package.json

---

Licencia

Este proyecto se publica en el dominio público bajo The Unlicense.

Este es software libre y sin restricciones. Cualquier persona es libre de copiar, modificar, publicar, usar, compilar, vender o distribuir este software, para cualquier propósito, comercial o no comercial, y por cualquier medio, sin condiciones ni restricciones.