Astro Blog MCP Server

MCP (Model Context Protocol) Server para automatizar la creación de posts en un blog Astro desplegado en Vercel.

🚀 Características

• ✅ Creación automática de posts vía API REST
• ✅ Integración directa con GitHub
• ✅ Validación y sanitización de inputs
• ✅ Seguridad con API Keys
• ✅ Rate limiting
• ✅ Trigger automático de deployments en Vercel
• ✅ Compatible con n8n y otras herramientas de automatización

📦 Instalación

1. Clona el repositorio

git clone <tu-repo>
cd astro-blog-mcp

2. Instala dependencias

pnpm install

3. Configura variables de entorno

Copia .env.example a .env y completa los valores:

cp .env.example .env

Variables requeridas:

• GITHUB_TOKEN: Personal Access Token de GitHub con permisos de repo
• GITHUB_OWNER: Tu usuario de GitHub
• GITHUB_REPO: Nombre del repositorio de tu blog
• GITHUB_BRANCH: Branch a usar (default: main)
• API_SECRET_KEY: Una clave secreta aleatoria de al menos 32 caracteres
• MCP_PORT: Puerto del servidor (default: 3000)
• DEPLOY_HOOK: (Opcional) Deploy Hook de Vercel

4. Compila el proyecto

pnpm build

🎯 Uso

Iniciar el servidor

Modo desarrollo:

pnpm dev

Modo producción:

pnpm start

Probar la API

pnpm test

🔑 Configuración de GitHub Token

1. Ve a GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Genera un nuevo token con estos permisos:
   • repo (acceso completo)
3. Copia el token y agrégalo a tu .env

🔗 Configuración de Vercel Deploy Hook

1. En tu proyecto de Vercel, ve a Settings → Git
2. En la sección "Deploy Hooks", crea un nuevo hook
3. Copia la URL y agrégala a DEPLOY_HOOK en tu .env

📡 API Endpoints

Health Check

GET /health

Validar configuración

GET /api/validate
Headers: x-api-key: YOUR_API_KEY

Crear un post

POST /api/posts
Headers:
  Content-Type: application/json
  x-api-key: YOUR_API_KEY

Body:
{
  "title": "Mi Nuevo Post",
  "description": "Descripción del post",
  "tags": ["astro", "blog"],
  "category": "Tutorial",
  "draft": false,
  "content": "# Contenido del post\n\nTexto aquí..."
}

Actualizar un post

PUT /api/posts/:fileName
Headers:
  Content-Type: application/json
  x-api-key: YOUR_API_KEY

Body: (mismo formato que crear)

🔌 Integración con n8n

Paso 1: Añadir Credentials

En n8n:

1. Ve a Credentials → New
2. Selecciona Header Auth
3. Configura:
   • Name: Astro Blog MCP
   • Header Name: x-api-key
   • Value: Tu API_SECRET_KEY

Paso 2: Crear Workflow

1. Añade un nodo HTTP Request
2. Configura:
   • Method: POST
   • URL: http://tu-servidor:3000/api/posts
   • Authentication: Selecciona las credentials creadas
   • Body Content Type: JSON
   • Body:

   {
     "title": "{{ $json.title }}",
     "description": "{{ $json.description }}",
     "tags": {{ $json.tags }},
     "category": "{{ $json.category }}",
     "content": "{{ $json.content }}"
   }
   

Ejemplo de Workflow n8n

{
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "http://localhost:3000/api/posts",
        "authentication": "predefinedCredentialType",
        "nodeCredentialType": "headerAuth",
        "sendBody": true,
        "bodyParameters": {
          "parameters": [
            {
              "name": "title",
              "value": "Nuevo Post desde n8n"
            },
            {
              "name": "description",
              "value": "Post creado automáticamente"
            },
            {
              "name": "tags",
              "value": ["automation", "n8n"]
            },
            {
              "name": "category",
              "value": "Automation"
            },
            {
              "name": "content",
              "value": "# Hola Mundo\n\nEste post fue creado por n8n"
            }
          ]
        }
      },
      "name": "Create Blog Post",
      "type": "n8n-nodes-base.httpRequest",
      "position": [250, 300]
    }
  ]
}

🐳 Deploy con Docker

docker build -t astro-blog-mcp .
docker run -p 3000:3000 --env-file .env astro-blog-mcp

🔒 Seguridad

• ✅ Autenticación con API Key
• ✅ Rate limiting (20 req/min)
• ✅ Validación de nombres de archivo (previene path traversal)
• ✅ Sanitización de inputs con Zod
• ✅ Timing-safe comparison para API keys
• ✅ CORS configurado

🧪 Testing

El proyecto incluye un script de prueba completo:

pnpm test

Esto probará:

1. Health check
2. Validación de acceso a GitHub
3. Creación de un post de prueba

📝 Formato de Posts

Los posts se crean con este front-matter:

---
title: Título del Post
published: 2025-10-25
description: "Descripción corta"
image: ""
tags: ["tag1", "tag2"]
category: "Categoría"
draft: false
---
Contenido del post aquí...

🛠️ Troubleshooting

Error: "Failed to validate GitHub access"

• Verifica que tu GITHUB_TOKEN sea válido
• Confirma que el token tenga permisos de repo
• Verifica que GITHUB_OWNER y GITHUB_REPO sean correctos

Error: "File already exists"

• El archivo ya existe en el repositorio
• Usa un nombre diferente o el endpoint PUT para actualizar

Error: "API key is required"

• Asegúrate de incluir el header x-api-key en tus requests
• Verifica que la API key coincida con API_SECRET_KEY

📚 Recursos

• GitHub API Docs
• Vercel Deploy Hooks
• n8n Documentation
• Astro Documentation

📄 Licencia

MIT