README.md•5.87 kB
# 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
```bash
git clone <tu-repo>
cd astro-blog-mcp
```
### 2. Instala dependencias
```bash
pnpm install
```
### 3. Configura variables de entorno
Copia `.env.example` a `.env` y completa los valores:
```bash
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
```bash
pnpm build
```
## 🎯 Uso
### Iniciar el servidor
**Modo desarrollo:**
```bash
pnpm dev
```
**Modo producción:**
```bash
pnpm start
```
### Probar la API
```bash
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
```bash
GET /health
```
### Validar configuración
```bash
GET /api/validate
Headers: x-api-key: YOUR_API_KEY
```
### Crear un post
```bash
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
```bash
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:
```json
{
"title": "{{ $json.title }}",
"description": "{{ $json.description }}",
"tags": {{ $json.tags }},
"category": "{{ $json.category }}",
"content": "{{ $json.content }}"
}
```
### Ejemplo de Workflow n8n
```json
{
"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
```bash
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:
```bash
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:
```yaml
---
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](https://docs.github.com/rest)
- [Vercel Deploy Hooks](https://vercel.com/docs/deployments/deploy-hooks)
- [n8n Documentation](https://docs.n8n.io/)
- [Astro Documentation](https://docs.astro.build/)
## 📄 Licencia
MIT