Shortcut

Accede y busca tickets en Shortcut.com.

GitHub

Documentación

Servidor MCP de Shortcut.com

Una implementación de un servidor de Protocolo de Contexto de Modelo (MCP) para acceder y buscar tickets en Shortcut.com.

Descripción general

Este proyecto implementa un servidor MCP que permite a Claude y otros asistentes de IA compatibles con MCP interactuar con el sistema de gestión de tickets de Shortcut.com. Con esta integración, los asistentes de IA pueden:

  • Listar y buscar historias (tickets) en Shortcut
  • Obtener información detallada sobre historias específicas
  • Crear nuevas historias
  • Actualizar historias existentes
  • Agregar comentarios a historias
  • Recuperar estados de flujo de trabajo y proyectos

Requisitos previos

  • Python 3.10+
  • Token de API de Shortcut.com

Instalación

  1. Clona este repositorio:

    git clone https://github.com/yourusername/mcp-server-shortcut.git
cd mcp-server-shortcut

  2. Crea un entorno virtual e instala las dependencias:

    # Using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh  # For Mac/Linux
uv venv
source .venv/bin/activate  # On Mac/Linux or .venv\Scripts\activate on Windows
uv pip install -r requirements.txt

# Using pip
python -m venv venv
source venv/bin/activate  # On Mac/Linux or venv\Scripts\activate on Windows
pip install -r requirements.txt

  3. Crea un archivo .env en el directorio raíz del proyecto con tu token de API de Shortcut:

    SHORTCUT_API_TOKEN=your_token_here
SERVER_PORT=5000
SERVER_HOST=0.0.0.0
DEBUG_MODE=True

Ejecutar el servidor

Inicia el servidor MCP usando:

python -m src.server

Configurar Claude Desktop

Para usar este servidor MCP con Claude Desktop:

  1. Edita el archivo de configuración de Claude Desktop:

    • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Agrega la configuración del servidor MCP:

    {
  "mcpServers": {
    "shortcut": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": {
        "SHORTCUT_API_TOKEN": "your_token_here"
      }
    }
  }
}

  3. Reinicia Claude Desktop.

Capacidades MCP disponibles

Recursos

  • shortcut://stories - Accede a una lista de historias
  • shortcut://story/{story_id} - Accede a una historia específica

Herramientas

  • list_stories - Lista historias con filtrado opcional
  • search_stories - Busca historias usando consultas de texto
  • get_story_details - Obtiene información detallada sobre una historia específica
  • create_story - Crea una nueva historia
  • update_story - Actualiza una historia existente
  • add_comment - Agrega un comentario a una historia
  • list_workflow_states - Lista todos los estados de flujo de trabajo
  • list_projects - Lista todos los proyectos

Prompts

  • create_bug_report - Genera una plantilla para informes de errores
  • create_feature_request - Genera una plantilla para solicitudes de funciones

Estructura del proyecto

  • src/ - Directorio de código fuente
    • server.py - Implementación principal del servidor MCP
    • config.py - Gestión de configuración
    • shortcut_client.py - Cliente para la API de Shortcut
    • utils.py - Funciones de utilidad y modelos de datos
  • requirements.txt - Dependencias del proyecto
  • .env - Variables de entorno (no rastreadas en git)

Desarrollo

Agregar nuevas capacidades

Para agregar una nueva capacidad al servidor MCP:

  1. Agrega cualquier método nuevo de API a shortcut_client.py
  2. Define modelos de Pydantic en utils.py si es necesario
  3. Implementa la funcionalidad MCP usando decoradores en server.py:
    • Usa @mcp.resource() para recursos de solo lectura
    • Usa @mcp.tool() para acciones que pueden modificar datos
    • Usa @mcp.prompt() para generar plantillas o texto estructurado

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Licencia

Licencia MIT