Shortcut

Acesse e pesquise tickets no Shortcut.com.

GitHub

Documentação

Servidor MCP Shortcut.com

Uma implementação de um servidor Model Context Protocol (MCP) para acessar e pesquisar tickets no Shortcut.com.

Visão Geral

Este projeto implementa um servidor MCP que permite que o Claude e outros assistentes de IA compatíveis com MCP interajam com o sistema de gerenciamento de tickets do Shortcut.com. Com esta integração, os assistentes de IA podem:

  • Listar e pesquisar histórias (tickets) no Shortcut
  • Obter informações detalhadas sobre histórias específicas
  • Criar novas histórias
  • Atualizar histórias existentes
  • Adicionar comentários a histórias
  • Recuperar estados de fluxo de trabalho e projetos

Pré-requisitos

  • Python 3.10+
  • Token da API do Shortcut.com

Instalação

  1. Clone este repositório:

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

  2. Crie um ambiente virtual e instale as dependências:

    # 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. Crie um arquivo .env no diretório raiz do projeto com seu token da API do Shortcut:

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

Executando o Servidor

Inicie o servidor MCP usando:

python -m src.server

Configurando o Claude Desktop

Para usar este servidor MCP com o Claude Desktop:

  1. Edite o arquivo de configuração do Claude Desktop:

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

  2. Adicione a configuração do servidor MCP:

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

  3. Reinicie o Claude Desktop.

Capacidades MCP Disponíveis

Recursos

  • shortcut://stories - Acessar uma lista de histórias
  • shortcut://story/{story_id} - Acessar uma história específica

Ferramentas

  • list_stories - Listar histórias com filtragem opcional
  • search_stories - Pesquisar histórias usando consultas de texto
  • get_story_details - Obter informações detalhadas sobre uma história específica
  • create_story - Criar uma nova história
  • update_story - Atualizar uma história existente
  • add_comment - Adicionar um comentário a uma história
  • list_workflow_states - Listar todos os estados de fluxo de trabalho
  • list_projects - Listar todos os projetos

Prompts

  • create_bug_report - Gerar um modelo para relatórios de bugs
  • create_feature_request - Gerar um modelo para solicitações de recursos

Estrutura do Projeto

  • src/ - Diretório do código-fonte
    • server.py - Implementação principal do servidor MCP
    • config.py - Gerenciamento de configuração
    • shortcut_client.py - Cliente para a API do Shortcut
    • utils.py - Funções utilitárias e modelos de dados
  • requirements.txt - Dependências do projeto
  • .env - Variáveis de ambiente (não rastreadas no git)

Desenvolvimento

Adicionando Novas Capacidades

Para adicionar uma nova capacidade ao servidor MCP:

  1. Adicione novos métodos de API ao shortcut_client.py
  2. Defina modelos Pydantic em utils.py se necessário
  3. Implemente a funcionalidade MCP usando decoradores em server.py:
    • Use @mcp.resource() para recursos somente leitura
    • Use @mcp.tool() para ações que podem modificar dados
    • Use @mcp.prompt() para gerar modelos ou texto estruturado

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Licença MIT