Firelinks.cc MCP

Crear y gestionar enlaces cortos para rastrear y distribuir tráfico.

GitHub
3

Documentación

Servidor MCP de Firelinks

Servidor MCP (Model Context Protocol) para la plataforma Firelinks, que permite a LLMs externos (Modelos de Lenguaje de Gran Escala) interactuar con la API de Firelinks - https://firelinks.cc/p/api

Descripción

Este servidor implementa el protocolo MCP desarrollado por Anthropic y proporciona un conjunto de herramientas para trabajar con la plataforma Firelinks:

  • Gestión de enlaces: crear, recuperar, editar enlaces cortos
  • Estadísticas: obtener estadísticas detalladas de clics, comparar períodos
  • Dominios: gestionar dominios personalizados
  • Servidores: obtener lista de servidores disponibles

Arquitectura

LLM client → HTTPS (mcp.firelinks.cc) → Node.js MCP Server → Firelinks API Backend

Requisitos

  • Node.js >= 20.0.0
  • Docker y Docker Compose (para contenedores)
  • Token de API de Firelinks

Instalación

Desarrollo Local

  1. Instalar dependencias:
cd mcp-server
npm install
  1. Crear el archivo .env basado en .env.example:
cp .env.example .env
  1. Configurar las variables de entorno en .env:
PORT=3000
LARAVEL_API_URL=https://firelinks.cc/api
NODE_ENV=development
  1. Iniciar el servidor:
npm start

O para modo de desarrollo con recarga automática:

npm run dev

Docker

  1. Construir la imagen:
docker build -t firelinks-mcp-server .
  1. Ejecutar el contenedor:
docker run -d \
  -p 3000:3000 \
  -e LARAVEL_API_URL=https://firelinks.cc/api \
  --name firelinks-mcp-server \
  firelinks-mcp-server

Docker Compose

docker-compose up -d

Uso

Endpoints

  • GET /health - verificación de salud del servidor
  • POST /mcp - endpoint principal de MCP (JSON-RPC 2.0)
  • GET /sse - Server-Sent Events para transmisión

Autenticación

Todas las solicitudes a /mcp requieren un token de autenticación en el encabezado:

Authorization: Bearer YOUR_API_TOKEN

Puedes obtener un token de API en tu cuenta de Firelinks.

Integración con Clientes LLM

Claude Desktop

Agregar a la configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "firelinks": {
      "url": "https://mcp.firelinks.cc/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Cursor

Agregar a la configuración de Cursor (mcp.json):

{
  "mcpServers": {
    "firelinks": {
      "url": "https://mcp.firelinks.cc/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Otros Clientes MCP

Para conectarse a otros clientes compatibles con MCP, usa:

  • URL: https://mcp.firelinks.cc/mcp
  • Transporte: HTTP
  • Autenticación: token Bearer en el encabezado Authorization

Herramientas Disponibles

Enlaces

  1. firelinks_create_link - crear enlace corto
  2. firelinks_get_link - obtener información del enlace
  3. firelinks_list_links - listar todos los enlaces
  4. firelinks_update_link_url - actualizar URL del enlace
  5. firelinks_add_reserve_url - agregar URL de reserva

Estadísticas

  1. firelinks_stat_days - estadísticas por días
  2. firelinks_stat_total - estadísticas totales para un período
  3. firelinks_stat_links - estadísticas para todos los enlaces
  4. firelinks_stat_clicks - estadísticas detalladas de clics
  5. firelinks_stat_compare - comparar dos períodos

Dominios

  1. firelinks_list_domains - listar dominios
  2. firelinks_create_domain - agregar dominio

Servidores

  1. firelinks_list_servers - listar servidores disponibles

Ejemplos de Solicitudes

Inicializar

curl -X POST https://mcp.firelinks.cc/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {},
    "id": 1
  }'

Listar Herramientas

curl -X POST https://mcp.firelinks.cc/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

Crear Enlace

curl -X POST https://mcp.firelinks.cc/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "firelinks_create_link",
      "arguments": {
        "url": "https://example.com",
        "type": "url",
        "redirect_type": 0,
        "code": "my-link"
      }
    },
    "id": 1
  }'

Parámetros requeridos:

  • url - Enlace válido con http o https
  • type - El tipo de enlace (usa "url" para enlaces web)
  • redirect_type - Tipo de redirección: 0 (301), 1 (302), 2 (303), 4 (META Refresh)

Parámetros opcionales:

  • link_name - Nombre del enlace
  • code - Código de enlace personalizado (debe ser único)
  • domain_id - ID del dominio
  • sub_domain - Subdominio
  • keywords - Palabras clave para búsqueda
  • keywords_mode - Lógica de búsqueda de palabras clave (1, 2 o 3)
  • group_id - ID del grupo de enlaces
  • options - Cadena de configuración adicional

Obtener Estadísticas

curl -X POST https://mcp.firelinks.cc/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "firelinks_stat_days",
      "arguments": {
        "date_from": "2024-01-01",
        "date_to": "2024-01-31"
      }
    },
    "id": 1
  }'

Estructura del Proyecto

mcp-server/
├── src/
│   ├── index.js              # Main Express server file
│   ├── lib/
│   │   ├── laravel-api.js    # HTTP client for Laravel API
│   │   └── mcp-handler.js    # MCP protocol handler
│   └── tools/
│       ├── links.js          # Tools for links
│       ├── statistics.js     # Tools for statistics
│       ├── domains.js        # Tools for domains
│       └── servers.js        # Tools for servers
├── package.json
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

Solución de Problemas

Error de Autenticación

Problema: Missing or invalid Authorization header

Solución: Asegúrate de que el encabezado de la solicitud contenga un token válido:

Authorization: Bearer YOUR_API_TOKEN

Tiempo de Espera Agotado en Solicitudes

Problema: Las solicitudes a la API de Laravel agotan el tiempo de espera

Solución:

  1. Verifica la disponibilidad de la API de Laravel
  2. Aumenta el tiempo de espera en src/lib/laravel-api.js
  3. Verifica la conectividad de red entre contenedores

El Servidor No Inicia

Problema: Error al iniciar

Solución:

  1. Revisa los registros: docker logs firelinks-mcp-server
  2. Asegúrate de que el puerto 3000 no esté en uso
  3. Verifica que las variables de entorno sean correctas

Licencia

MIT

Soporte

Para preguntas y soporte, contacta a support@firelinks.cc