Servidor MCP

Servidor Model Context Protocol para Mapfolio - Permite que los asistentes de IA interactúen con los datos de Mapfolio

Resumen

El Servidor MCP de Mapfolio es un servidor Model Context Protocol (MCP) que permite a los asistentes de IA y otros clientes compatibles con MCP interactuar con los datos y operaciones de Mapfolio. Proporciona acceso programático a empresas, proyectos, usuarios, perfiles de LinkedIn y funciones administrativas.

¿Qué es MCP?

Model Context Protocol (MCP) es un protocolo abierto que permite a los asistentes de IA acceder de forma segura a fuentes de datos y herramientas externas. Los servidores MCP exponen capacidades a través de una interfaz estandarizada, permitiendo a los asistentes de IA:

  • Consultar y recuperar datos
  • Realizar operaciones
  • Acceder a recursos
  • Integrarse con sistemas externos

Características

El Servidor MCP de Mapfolio proporciona funcionalidad integral:

Datos de Empresas

  • Buscar empresas con filtros avanzados
  • Obtener detalles de empresas por ID
  • Recuperar empresas por cantón y letra inicial
  • Obtener empresas aleatorias para muestreo
  • Acceder a estadísticas de visitas de empresas

Gestión de Proyectos

  • Crear y gestionar proyectos
  • Listar y filtrar proyectos de usuario
  • Actualizar detalles de proyectos
  • Eliminar proyectos
  • Añadir y eliminar empresas de proyectos

Perfiles de Usuario

  • Obtener información del perfil de usuario
  • Actualizar configuración del perfil
  • Listar proyectos de usuario
  • Gestionar claves API

Integración con LinkedIn

  • Obtener datos de perfiles de LinkedIn
  • Buscar perfiles de LinkedIn
  • Acceder a información de conexiones
  • Ver historial de versiones de perfiles
  • Obtener datos de empresas de LinkedIn

Operaciones Administrativas

  • Listar todos los usuarios (solo admin)
  • Crear nuevos usuarios (solo admin)
  • Gestionar claves API (solo admin)
  • Acceder a estadísticas del panel de administración

Estadísticas

  • Obtener estadísticas agregadas de empresas
  • Ver recuentos a nivel de cantón
  • Acceder a recuentos basados en letras
  • Obtener estadísticas de combinaciones de dos letras

Instalación

Requisitos Previos

  • Node.js >= 20.0.0
  • npm >= 10.0.0
  • Acceso a la instancia de Supabase de Mapfolio

Configuración

  1. Instalar dependencias:
cd mcp-server
npm install
  1. Configurar variables de entorno:
cp .env.example .env

Edite .env y configure:

# URL de la API de Mapfolio (por defecto: https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# Tipo de transporte: 'stdio' (por defecto) o 'http' para acceso remoto
MCP_TRANSPORT=stdio

# Puerto HTTP (solo se usa cuando MCP_TRANSPORT=http)
MCP_HTTP_PORT=3001

# Opcional: Autenticación por defecto (puede proporcionarse vía contexto MCP o encabezados HTTP)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here
  1. Compilar el servidor:
npm run build

Uso

Ejecutar el Servidor

Desarrollo Local (transporte stdio)

El servidor MCP usa transporte stdio por defecto (protocolo MCP estándar):

npm start

Para desarrollo con recarga automática:

npm run dev

Transporte HTTP (para acceso remoto)

Para ejecutar el servidor con transporte HTTP para pruebas locales:

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

Esto inicia un servidor HTTP en el puerto 3001 que acepta solicitudes JSON-RPC 2.0 sobre HTTP POST.

Despliegue en Vercel (Acceso Remoto)

El servidor MCP está disponible automáticamente vía HTTP cuando se despliega en Vercel:

  • Endpoint: https://your-app.vercel.app/api/mcp
  • Protocolo: JSON-RPC 2.0 sobre HTTP POST
  • Autenticación: Vía encabezado X-API-Key o encabezado Authorization: Bearer <token>

Ejemplo de solicitud:

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mapf_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Configuración del Cliente MCP

Claude Desktop

Despliegue local:

{
  "mcpServers": {
    "mapfolio": {
      "command": "node",
      "args": ["/path/to/mapfolio/mcp-server/dist/index.js"],
      "env": {
        "MAPFOLIO_API_URL": "https://mapfolio.app",
        "MAPFOLIO_API_KEY": "mapf_your_api_key_here"
      }
    }
  }
}

Cursor

Configure a través de la configuración MCP:

  • Comando: node
  • Args: ["/path/to/mapfolio/mcp-server/dist/index.js"]
  • Variables de entorno:
    • MAPFOLIO_API_URL: https://mapfolio.app
    • MAPFOLIO_API_KEY: Su clave API (opcional)

Autenticación

El servidor admite dos métodos de autenticación:

Autenticación con Clave API

Las claves API tienen el prefijo mapf_ y pueden:

  • Establecerse vía variable de entorno MAPFOLIO_API_KEY
  • Pasarse por solicitud vía parámetro apiKey en llamadas de herramientas

Autenticación con Token JWT

Los tokens JWT de Supabase pueden:

  • Establecerse vía variable de entorno MAPFOLIO_JWT_TOKEN
  • Pasarse por solicitud vía parámetro jwtToken en llamadas de herramientas

Prioridad de Autenticación

  1. Transporte HTTP: Los encabezados (X-API-Key o Authorization) tienen prioridad
  2. Credenciales por solicitud (apiKey o jwtToken en argumentos de herramientas)
  3. Variables de entorno (MAPFOLIO_API_KEY o MAPFOLIO_JWT_TOKEN)

Autenticación de Transporte HTTP

Cuando se usa el endpoint HTTP (/api/mcp), la autenticación se proporciona vía encabezados HTTP:

  • Clave API: X-API-Key: mapf_your_api_key
  • Token JWT: Authorization: Bearer your_jwt_token

Herramientas Disponibles

El servidor proporciona 30+ herramientas en 6 categorías:

Herramientas de Empresas

  • search_companies - Buscar con filtros
  • get_company - Obtener empresa por ID
  • get_companies_by_canton_letter - Obtener por cantón y letra
  • get_random_companies - Obtener muestras aleatorias
  • get_company_visits - Obtener estadísticas de visitas

Herramientas de Proyectos

  • create_project - Crear nuevo proyecto
  • list_projects - Listar proyectos de usuario
  • get_project - Obtener detalles del proyecto
  • update_project - Actualizar proyecto
  • delete_project - Eliminar proyecto
  • add_companies_to_project - Añadir empresas
  • remove_companies_from_project - Eliminar empresas

Herramientas de Usuario

  • get_user_profile - Obtener perfil
  • update_user_profile - Actualizar perfil
  • get_user_projects - Listar proyectos
  • get_user_api_keys - Listar claves API

Herramientas de LinkedIn

  • get_linkedin_profile - Obtener perfil
  • search_linkedin_profiles - Buscar perfiles
  • get_linkedin_connections - Obtener conexiones
  • get_linkedin_profile_versions - Obtener historial de versiones
  • get_linkedin_companies - Obtener datos de empresas

Herramientas de Administración (Solo Admin)

  • list_all_users - Listar todos los usuarios
  • create_user - Crear usuario
  • get_user_details - Obtener detalles de usuario
  • list_api_keys - Listar todas las claves API
  • create_api_key - Crear clave API
  • revoke_api_key - Revocar clave API
  • get_admin_stats - Obtener estadísticas de administración

Herramientas de Estadísticas

  • get_company_stats - Obtener estadísticas agregadas
  • get_canton_counts - Obtener recuentos de cantones
  • get_letter_counts - Obtener recuentos de letras
  • get_two_letter_counts - Obtener recuentos de dos letras

Recursos

El servidor proporciona acceso basado en recursos:

  • mapfolio://company/{id} - Datos de empresa
  • mapfolio://project/{id} - Datos de proyecto
  • mapfolio://user/{id} - Perfil de usuario
  • mapfolio://linkedin-profile/{id} - Perfil de LinkedIn

Los recursos pueden incluir autenticación vía parámetros de consulta:

  • mapfolio://company/{id}?apiKey=mapf_...
  • mapfolio://company/{id}?jwtToken=...

Ejemplo de Uso

Buscar Empresas

{
  "tool": "search_companies",
  "arguments": {
    "query": "technology",
    "cantons": ["ZH", "BE"],
    "page": 1,
    "limit": 20
  }
}

Crear Proyecto

{
  "tool": "create_project",
  "arguments": {
    "name": "Tech Companies Zurich",
    "searchType": "company",
    "searchQuery": "technology",
    "isPublic": false
  }
}

Obtener Detalles de Empresa

{
  "tool": "get_company",
  "arguments": {
    "companyId": "company-uuid-here"
  }
}

Manejo de Errores

Todas las herramientas devuelven errores en un formato consistente:

{
  "error": "Mensaje de error"
}

Escenarios de error comunes:

  • 401 No Autorizado: Autenticación inválida o faltante
  • 403 Prohibido: Permisos insuficientes
  • 404 No Encontrado: Recurso no encontrado
  • 500 Error Interno del Servidor: Error del lado del servidor

Arquitectura Solo API

El servidor MCP utiliza solicitudes HTTP a mapfolio.app en lugar de acceso directo a la base de datos. Esto significa:

  • ✅ No se necesitan credenciales de Supabase - Funciona solo con URL de API y clave API
  • ✅ Fácil despliegue en Vercel - Desplegar como función serverless
  • ✅ Seguro - Todas las solicitudes pasan por la API de Mapfolio con autenticación
  • ✅ Escalable - Se beneficia del límite de velocidad y caché de la API de Mapfolio

Actualmente Disponible vía API

  • ✅ Búsqueda y recuperación de empresas
  • ✅ Estadísticas de empresas (recuentos de cantones, recuentos de letras)
  • ✅ Empresas aleatorias
  • ✅ Visitas de empresas

Próximamente (Requiere Endpoints de API)

  • ⏳ Gestión de proyectos (crear, listar, actualizar, eliminar)
  • ⏳ Gestión de perfiles de usuario
  • ⏳ Acceso a perfiles de LinkedIn
  • ⏳ Operaciones administrativas

Estas características devolverán mensajes de error útiles hasta que se creen los endpoints de API.

Consideraciones de Seguridad

  1. Claves API: Almacenar de forma segura, nunca commitear en control de versiones
  2. Tokens JWT: Los tokens expiran, manejar la actualización apropiadamente
  3. Límite de Velocidad de API: Respeta los límites de velocidad de la API de Mapfolio
  4. Solo HTTPS: Siempre usar HTTPS para solicitudes de API
  5. Operaciones de Administración: Requieren autenticación de administrador explícita (cuando los endpoints estén disponibles)

Desarrollo

Verificación de Tipos

npm run type-check

Compilación

npm run build

Modo de Desarrollo

npm run dev

Documentación

Para documentación completa, consulte el README del Servidor MCP.

Soporte

Para problemas o preguntas:

Licencia

MIT