Servidor MCP lineal

Una implementación Node.js de un servidor MCP para integración lineal.

Acerca de

Este servidor MCP (Protocolo de contexto de modelo) proporciona una interfaz estandarizada para que los modelos de IA interactúen con la funcionalidad de seguimiento de problemas lineal.

Características principales

• Implementación del protocolo MCP estándar para Linear utilizando el SDK oficial de MCP

• Soporte para buscar problemas, leer detalles, actualizar y comentar.

Related MCP server: Linear MCP Server

Empezando

Prerrequisitos

• Node.js (v18 o posterior)

• Clave API lineal

Instalación

1. Clonar el repositorio

2. Instalar dependencias

npm install

3. Cree un archivo .env en el directorio raíz con su clave API lineal

LINEAR_API_KEY=your_linear_api_key_here

Ejecución del servidor

Iniciar el servidor:

npm start

Para el desarrollo con vigilancia de archivos:

just dev

Para el desarrollo con registro de depuración:

just debug

O bien, configure las variables de entorno manualmente:

LOG_LEVEL=DEBUG NODE_ENV=development node src/index.js

Los registros se escribirán en el archivo logs/mcp-linear.log para evitar interferir con el transporte STDIO.

Uso con MCP Inspector

El servidor se ejecuta en modo stdio, lo que significa que puedes conectarte a él con el Inspector MCP.

1. Inicie el servidor en una terminal:

npm start

2. Visite el inspector basado en web en: https://inspector.modelcontextprotocol.ai

3. Seleccione "stdio" como tipo de transporte

4. Introduzca el siguiente comando:

node /path/to/mcp-linear/src/index.js

5. Haga clic en "Conectar" para conectarse a su servidor en ejecución

Uso con Claude Desktop

Agregue lo siguiente a su archivo de configuración de Claude Desktop (normalmente en ~/.config/Claude Desktop/claude_desktop_config.json ):

{
  "mcp": {
    "servers": [
      {
        "name": "Linear",
        "command": "node /path/to/mcp-linear/src/index.js",
        "env": {
          "LINEAR_API_KEY": "your_linear_api_key_here"
        }
      }
    ]
  }
}

Uso con cursor

Para el cursor, agregue lo siguiente a su configuración:

{
  "ai.mcp.servers": [
    {
      "name": "Linear",
      "command": "node /path/to/mcp-linear/src/index.js",
      "env": {
        "LINEAR_API_KEY": "your_linear_api_key_here"
      }
    }
  ]
}

Probando su integración

Para verificar su configuración:

1. Configure el servidor MCP en la configuración de Claude Desktop o Cursor

2. Reinicia tu aplicación

3. Pregunta: "Buscar problemas de Linear que contengan 'bug'"

4. El asistente debe detectar y utilizar el servidor Linear MCP para recuperar resultados

Estructura del proyecto

/
├── src/                     # Source code
│   ├── effects/             # Effects implementation
│   │   ├── linear/          # Linear API effects
│   │   │   └── types/       # Linear type definitions
│   │   └── logging/         # Logging effects for safe logging with STDIO
│   ├── tools/               # MCP tools implementation
│   │   ├── types/           # Tool type definitions
│   │   └── utils/           # Tool utility functions
│   ├── utils/               # Utility modules
│   │   └── config/          # Configuration utilities
│   └── index.js             # Main entry point
├── docs/                    # Documentation
│   └── llm_context/         # Documentation for LLMs
├── logs/                    # Log files (created at runtime)
└── package.json             # Project configuration

Herramientas disponibles

El servidor MCP expone las siguientes herramientas:

• list_issues - Lista de problemas lineales (también llamados tickets) con varias opciones de filtrado (asignado, estado, etc.)

• get_issue - Obtenga información detallada sobre un problema lineal específico por ID

• list_members - Lista de miembros del equipo lineal con filtrado opcional por nombre

• list_projects - Lista de proyectos lineales con filtrado opcional por equipo, nombre y estado de archivo

• get_project - Obtenga información detallada sobre un proyecto lineal específico, incluidos problemas, miembros y más

• list_teams - Lista de equipos lineales con detalles sobre sus miembros, proyectos y problemas

• add_comment - Agrega un comentario a un problema específico de Linear

• create_issue - Crea un nuevo problema en Linear con título, descripción, prioridad y asignado personalizables

Para compatibilidad con versiones anteriores, también están disponibles los siguientes alias de herramientas:

• list_tickets - Alias para list_issues

• get_ticket - Alias para get_issue

Solución de problemas

Si tiene problemas con el servidor Linear MCP:

1. Comprueba tu clave de API lineal : Asegúrate de haber configurado una clave de API lineal válida en tu archivo .env o en las variables de entorno. Las claves de API lineales deben empezar por "lin api ".

2. Habilitar el registro de depuración :

   a. Al iniciar el servidor MCP:

   just debug
   # or
   LOG_LEVEL=DEBUG NODE_ENV=development node src/index.js

   b. En la configuración de su cliente (Claude Desktop, Cursor, etc.):

   "env": {
     "LINEAR_API_KEY": "your_linear_api_key_here",
     "LOG_LEVEL": "DEBUG"
   }

   c. Al llamar a las herramientas directamente, agregue el parámetro de depuración:

   {
     "debug": true
   }

3. Comprobar los archivos de registro : examine los registros en el archivo logs/mcp-linear.log para obtener información detallada sobre los errores.

4. Verificar el acceso a la API lineal : asegúrese de que su clave de API lineal tenga los permisos adecuados y de que pueda acceder a la API lineal directamente.

Arquitectura

La aplicación sigue una arquitectura basada en efectos:

• Efectos : Las operaciones con efectos secundarios están aisladas en el directorio effects :

  • linear : proporciona acceso a la API lineal mediante el SDK lineal oficial

  • logging : registro seguro que no interfiere con el transporte STDIO

• Herramientas : Implementaciones de herramientas MCP que utilizan efectos para efectos secundarios:

  • Cada herramienta sigue un patrón consistente con la validación de entrada utilizando Zod

  • Las herramientas se exponen a través del protocolo MCP a través del servidor.

  • Cada herramienta puede acceder al cliente lineal a través del efecto lineal

• Utilidades : Módulos de utilidad para configuración y funcionalidad común

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.