# Ekyte MCP Server

Servidor MCP (Model Context Protocol) que permite ao Claude (e outras IAs) interagir com a plataforma **Ekyte** para gestão de tarefas e apontamento de horas.

Toda a API usada é a **interna** (`https://api.ekyte.com/api/...`), autenticada por **JWT Bearer** (mesmo token que o front `app.ekyte.com` envia). Não usa a API pública `/v1.x`.

**Autoria:** desenvolvido por **Pietro Piai** com contribuição de **Paulo D'Elia**, ambos da **V4 Ferraz Piai** (unidade franqueada da V4 Company). Liberado para qualquer franquia ou pessoa da V4 Company subir sua própria instância.

**Repositório:** https://github.com/FerrazPiai/ekyte_mcp_server

---

## Sumário

- [Pré-requisitos](#pré-requisitos)
- [Instalação rápida via PRD (recomendado)](#instalação-rápida-via-prd-recomendado)
- [Tools Disponíveis](#tools-disponíveis)
  - [Leitura (read-only)](#leitura-read-only)
  - [Escrita (destrutivo — pede confirmação)](#escrita-destrutivo--pede-confirmação)
- [Fluxo recomendado para criar uma tarefa](#fluxo-recomendado-para-criar-uma-tarefa)
- [Fluxo recomendado para editar uma tarefa](#fluxo-recomendado-para-editar-uma-tarefa)
- [Configuração](#configuração)
  - [Como extrair o `EKYTE_BEARER_TOKEN`](#como-extrair-o-ekyte_bearer_token-passo-a-passo)
  - [Como descobrir o `EKYTE_COMPANY_ID`](#como-descobrir-o-ekyte_company_id)
- [Deploy — escolha sua plataforma](#deploy)
- [Conexão com o Claude](#conexão-com-o-claude)
  - [Claude Code (CLI)](#claude-code-cli--transporte-http-remoto)
  - [Claude Desktop — stdio local](#claude-desktop--transporte-stdio-local)
  - [Claude Desktop — HTTP remoto](#claude-desktop--transporte-http-remoto-com-mcp-remoto-instalado-no-easypanel)
- [Skill do Claude para operar o Ekyte com segurança](#skill-do-claude-para-operar-o-ekyte-com-segurança)
- [Desenvolvimento local](#desenvolvimento-local)
- [Arquitetura](#arquitetura)
- [Endpoints que a MCP usa](#endpoints-que-a-mcp-usa-referência)

---

## Pré-requisitos

Antes de começar, tenha em mãos:

- Conta ativa no **Ekyte** com acesso a `app.ekyte.com` (para extrair o JWT e o `company_id`).
- Um dos cenários de deploy:
  - **Easypanel** rodando num VPS (Hostinger, DigitalOcean, Hetzner, etc.) — caminho recomendado.
  - Ou **qualquer servidor com Docker** (Ubuntu/Debian + Docker + Docker Compose).
  - Ou apenas **máquina local** com Node 18+ (se quiser usar só no Claude Desktop em stdio, sem deploy).
- Conta Claude (**Claude Code CLI** ou **Claude Desktop**) onde a MCP será conectada.
- Conta no **GitHub** (para fazer fork do repositório — opcional mas recomendado, facilita atualizações futuras).

---

## Instalação rápida via PRD (recomendado)

O repo inclui o arquivo **[`PRD-INSTALACAO-MCP-EKYTE.md`](./PRD-INSTALACAO-MCP-EKYTE.md)** — um PRD (Product Requirements Document) pronto para o Claude Code executar a instalação sozinho, do zero ao smoke test. É o caminho mais rápido se você já tem Claude Code instalado e só quer "ligar" a MCP.

**Como usar:**

1. Clone o repo:
   ```bash
   git clone https://github.com/FerrazPiai/ekyte_mcp_server.git
   cd ekyte_mcp_server
   ```
2. Abra o Claude Code dentro dessa pasta:
   ```bash
   claude
   ```
3. Mande o Claude executar o PRD:
   ```
   Executa este PRD de instalação: @PRD-INSTALACAO-MCP-EKYTE.md
   ```

O Claude vai guiar você por:

- Obter o `EKYTE_BEARER_TOKEN` e `EKYTE_COMPANY_ID` (instruções passo-a-passo no DevTools)
- Instalar dependências e buildar (`npm install && npm run build`), quando for modo local
- Registrar a MCP no Claude Code em um dos dois modos:
  - **3A — Stdio local:** a MCP roda na sua máquina (precisa de Node 18+ e credenciais locais)
  - **3B — HTTP remoto:** aponta para um servidor já hospedado (EasyPanel, Coolify, Railway, etc.) — zero setup local
- Validar com smoke test (`claude mcp list` + pedir uma listagem de workspaces no chat)

> O PRD inclui **troubleshooting** para os erros comuns (401, 500, build falhou, MCP não aparece em `claude mcp list`). Se algo quebrar durante a instalação, é só pedir "resolve pelo troubleshooting do PRD".

Se preferir fazer manualmente (sem o PRD), as seções abaixo cobrem cada parte isolada: [Configuração](#configuração) → [Deploy](#deploy) → [Conexão com o Claude](#conexão-com-o-claude).

---

## Tools Disponíveis

### Leitura (read-only)

| Tool | Descrição |
|------|-----------|
| `ekyte_list_workspaces` | Lista workspaces (clientes) da empresa |
| `ekyte_list_users` | Lista usuários/membros (com UUID) |
| `ekyte_list_task_types` | Lista tipos de tarefa (template + workflow_id) |
| `ekyte_list_phases` | Lista fases de um workflow (para descobrir `phase_id`) |
| `ekyte_list_tasks` | Lista tarefas com filtros (workspace, status, datas, etc.) |
| `ekyte_list_task_flow_phases` | Lista as fases de uma tarefa específica, com executor/datas/esforço POR FASE |
| `ekyte_get_task` | Detalhes de uma tarefa específica |
| `ekyte_list_time_entries` | Lista apontamentos de horas |

### Escrita (destrutivo — pede confirmação)

| Tool | Descrição |
|------|-----------|
| `ekyte_create_task` | Cria nova tarefa (fase única ou **multi-fase**, com executor diferente por fase) |
| `ekyte_update_task` | Edita campos top-level da tarefa (título, descrição, executor/fase atuais, prioridade) |
| `ekyte_update_phase` | Edita uma FASE específica da tarefa (executor, esforço, datas) — sem alterar as outras fases |
| `ekyte_complete_task` | Marca tarefa como concluída |
| `ekyte_add_task_comment` | Adiciona comentário na timeline |
| `ekyte_create_time_entry_with_task` | Aponta horas em tarefa específica |
| `ekyte_create_time_entry_without_task` | Aponta horas avulso |
| `ekyte_delete_time_entry` | Remove apontamento |

## Fluxo recomendado para criar uma tarefa

### Fase única (simples)

1. `ekyte_list_workspaces` → `workspace_id`
2. `ekyte_list_task_types` → `task_type_id` (+ `workflow_id` associado)
3. `ekyte_list_phases(workflow_id)` → `phase_id` inicial
4. `ekyte_list_users` → `executor_id` (UUID)
5. `ekyte_create_task` com os 4 IDs + datas + tempo estimado

### Multi-fase (executor diferente por fase)

1–3 iguais ao fluxo acima (listar workspaces, task types, phases)
4. `ekyte_list_users` → descobrir UUIDs dos responsáveis
5. `ekyte_create_task` passando o array `phases`:
   ```json
   {
     "title": "Campanha X",
     "workspace_id": 12345,
     "task_type_id": 67890,
     "phase_start_date": "2026-04-22",
     "phase_due_date": "2026-04-30",
     "phases": [
       {"phase_id": 111, "executor_id": "00000000-0000-0000-0000-000000000001", "effort_minutes": 60, "phase_due_date": "2026-04-24"},
       {"phase_id": 222, "executor_id": "00000000-0000-0000-0000-000000000002", "effort_minutes": 90, "phase_due_date": "2026-04-27"},
       {"phase_id": 333, "executor_id": "00000000-0000-0000-0000-000000000003", "effort_minutes": 30, "phase_due_date": "2026-04-30"}
     ]
   }
   ```
   A tarefa começa na **primeira fase** da lista. Top-level (`executor_id`, `phase_id`) são ignorados.

## Fluxo recomendado para editar uma tarefa

### Editar campos gerais (fase atual, título, prioridade, etc.)
- Use `ekyte_update_task`
- Campos: `title`, `description`, `executor_id` (fase atual), `phase_id` (muda a fase ativa), `phase_start_date`, `phase_due_date`, `priority_group` (35=Baixa, 50=Média, 60=Alta, 90=Urgente)

### Editar uma fase específica (não-atual) — trocar quem faz o quê
1. `ekyte_list_task_flow_phases(task_id)` → ver todas as fases e seus `phase_id`
2. `ekyte_update_phase(task_id, phase_id, executor_id=..., effort_minutes=..., phase_start_date=..., phase_due_date=...)`
- Ex: "mudar o responsável pela fase Execução da tarefa #123" sem mexer nas outras

## Configuração

### Variáveis de ambiente

```env
EKYTE_BEARER_TOKEN=seu_jwt_aqui        # obrigatório
EKYTE_COMPANY_ID=1234                  # obrigatório (numérico)
TRANSPORT=http                         # "http" p/ servidor remoto, "stdio" p/ Claude Desktop local
PORT=3000                              # porta HTTP (default 3000)
```

### Como extrair o `EKYTE_BEARER_TOKEN` (passo-a-passo)

1. Entre em `https://app.ekyte.com` com sua conta e faça login.
2. Abra o **DevTools** do navegador (`F12` no Chrome/Edge, ou `Ctrl+Shift+I`).
3. Vá na aba **Network** (Rede).
4. Clique em qualquer tela do Ekyte (lista de tarefas, workspaces etc.) para gerar tráfego.
5. Filtre as requisições por `api.ekyte.com` — clique em qualquer uma delas.
6. Na aba **Headers** → **Request Headers**, localize a linha:
   ```
   Authorization: Bearer eyJhbGciOi...<string longa>
   ```
7. Copie **só o que vem depois de `Bearer `** — esse é o valor de `EKYTE_BEARER_TOKEN`.

> ⚠️ **Validade:** o JWT do Ekyte expira em ~6 meses. Quando o MCP começar a retornar erro `401 Unauthorized`, repita o processo e atualize a variável no Easypanel (ou no `.env` local).

### Como descobrir o `EKYTE_COMPANY_ID`

Na mesma aba **Network** do DevTools, observe a URL das requisições para `api.ekyte.com`. Elas têm o formato:

```
https://api.ekyte.com/api/companies/1234/workspaces
                                   ^^^^
                                   esse é o company_id
```

O número que aparece depois de `/companies/` é o seu `EKYTE_COMPANY_ID`. Cada unidade/empresa tem o seu — **use o da sua unidade**, não copie o de outro time.

## Deploy

Esta MCP é um container Docker (Node 20-alpine) que expõe HTTP na porta `3000`. Qualquer plataforma que aceite `Dockerfile` + domínio HTTPS funciona. Clique na plataforma que você usa para ir direto ao passo-a-passo:

| [Easypanel](#easypanel) | [Coolify](#coolify) | [Railway](#railway) | [Render](#render) | [Fly.io](#flyio) | [VPS genérico](#vps-genérico-ubuntu--docker-compose--nginx) |
|---|---|---|---|---|---|
| Self-hosted, painel visual, SSL automático — stack original do projeto | Self-hosted open-source, alternativa direta ao Easypanel | Cloud gerenciado, deploy em 2min via GitHub, ~$5/mês | Cloud gerenciado, plano Free (com sleep) ou Starter $7/mês | Edge global, deploy por CLI, ótimo para latência distribuída | Ubuntu + Docker Compose + Nginx + Certbot (qualquer VPS) |

### Easypanel

O Easypanel faz o build do Dockerfile, configura SSL automático (Let's Encrypt) e injeta as env vars. Fluxo completo:

#### 1. Fork do repositório (recomendado)

Acesse https://github.com/FerrazPiai/ekyte_mcp_server e clique em **Fork** para copiar o repo para sua conta. Isso permite puxar atualizações futuras com um clique, sem perder seu histórico.

> Alternativa: use o repositório original direto, mas você não terá controle sobre atualizações.

#### 2. Criar o serviço no Easypanel

1. Entre no painel do seu Easypanel → selecione o **projeto** onde quer rodar o MCP (ou crie um novo).
2. Clique em **+ Service** → **App**.
3. Dê um nome ao serviço, por exemplo `ekyte-mcp`.
4. Na aba **Source**:
   - **Type:** `GitHub` (ou `Git` genérico)
   - **Repository:** `https://github.com/SEU-USUARIO/ekyte_mcp_server` (ou o original se não fez fork)
   - **Branch:** `main`
   - **Build Path:** `/` (raiz)
5. Na aba **Build**:
   - **Type:** `Dockerfile`
   - **Dockerfile Path:** `Dockerfile` (já existe na raiz)

#### 3. Configurar as variáveis de ambiente

Na aba **Environment** do serviço, adicione:

```env
EKYTE_BEARER_TOKEN=eyJhbGciOi...          # seu JWT extraído do DevTools
EKYTE_COMPANY_ID=1234                     # o ID da sua unidade
TRANSPORT=http
PORT=3000
NODE_ENV=production
```

Salve e clique em **Deploy**.

#### 4. Expor a porta e configurar o domínio

1. Na aba **Domains** do serviço, clique em **+ Add Domain**.
2. **Host:** `ekyte-mcp.seu-dominio.com` (use um subdomínio que aponte para o IP do Easypanel).
3. **Path:** `/`
4. **Port:** `3000`
5. Marque **HTTPS** (o Easypanel cuida do Let's Encrypt).
6. Salve — em ~30s o SSL é emitido.

#### 5. Configurar healthcheck (opcional, mas recomendado)

Na aba **Deploy** → **Health Check**:
- **Path:** `/health`
- **Port:** `3000`
- **Interval:** 30s

> ⚠️ Não adicione `HEALTHCHECK` no Dockerfile — deixe o Easypanel cuidar disso via HTTP probe. O Dockerfile já está configurado assim de propósito.

#### 6. Verificar se subiu

```bash
curl https://ekyte-mcp.seu-dominio.com/health
# resposta esperada:
# {"status":"ok","server":"ekyte-mcp-server","version":"1.0.0"}
```

Endpoint MCP final: `https://ekyte-mcp.seu-dominio.com/mcp`

#### 7. Atualizar depois de mudanças no código

- **Se fez fork:** faça `git pull` do upstream no seu fork → Easypanel detecta e rebuilda automaticamente (se tiver auto-deploy ligado) ou clique em **Deploy** manual.
- **Trocar o JWT expirado:** só editar `EKYTE_BEARER_TOKEN` em **Environment** → **Deploy** → pronto.

### Coolify

[Coolify](https://coolify.io/) é uma PaaS open-source e self-hosted, alternativa direta ao Heroku, Vercel ou Netlify — ótima opção se você quer rodar o MCP server na sua própria infra com SSL automático, deploy via Git e zero vendor lock-in.

#### Pré-requisitos

- Instância do Coolify v4 rodando (veja [coolify.io/docs](https://coolify.io/docs/installation))
- Servidor com Docker instalado e gerenciado pelo Coolify (pode ser o próprio host do Coolify ou um remoto via SSH)
- Domínio ou subdomínio apontando para o IP do servidor (ex: `mcp.seudominio.com.br` com registro A)

#### Passo-a-passo

1. **Criar o projeto e a aplicação**
   - No dashboard do Coolify, entre em um Project existente (ou crie um novo) e clique em **+ New Resource**
   - Escolha **Public Repository** (ou **Private Repository (with GitHub App)** se preferir receber webhooks de push)
   - Cole a URL: `https://github.com/FerrazPiai/ekyte_mcp_server`

2. **Configurar branch e build pack**
   - **Branch:** `main`
   - **Build Pack:** `Dockerfile` (o Coolify detecta automaticamente o `Dockerfile` na raiz — não precisa informar caminho customizado)
   - **Base Directory:** `/` (padrão)

3. **Configurar porta e rede**
   - Em **General > Network**, defina **Ports Exposes** como `3000`
   - Deixe **Ports Mappings** vazio (o Coolify gerencia via proxy Traefik interno)

   > ⚠️ O Coolify só roteia tráfego para portas declaradas em `EXPOSE` no Dockerfile. O Dockerfile deste projeto já faz `EXPOSE 3000`.

4. **Adicionar variáveis de ambiente**
   - Vá em **Environment Variables** e adicione as 5 variáveis obrigatórias:

   ```env
   EKYTE_BEARER_TOKEN=seu_jwt_longo_aqui
   EKYTE_COMPANY_ID=123
   TRANSPORT=http
   PORT=3000
   NODE_ENV=production
   ```

   - Marque `EKYTE_BEARER_TOKEN` como **Is Secret?** para mascarar o valor nos logs e na UI

5. **Configurar domínio e SSL**
   - Em **General > Domains**, informe a URL completa com `https://`, por exemplo: `https://mcp.seudominio.com.br`
   - O Coolify emite e renova o certificado Let's Encrypt automaticamente via Traefik — não precisa configurar nada além do domínio
   - Deixe **Force HTTPS Redirect** ativado

6. **Configurar healthcheck**
   - Em **Healthchecks**, ative **Enabled**
   - **Path:** `/health` — **Port:** `3000` — **Method:** `GET`
   - **Interval:** `30` — **Timeout:** `10` — **Retries:** `3`

7. **Deploy**
   - Clique em **Deploy** no topo da tela
   - Acompanhe os logs em **Deployments > Logs**; o primeiro build leva 1-2 min

#### Verificação

```bash
curl https://mcp.seudominio.com.br/health
# {"status":"ok","server":"ekyte-mcp-server","version":"1.0.0"}
```

Endpoint MCP final: `https://mcp.seudominio.com.br/mcp`

#### Atualizações futuras

- **Automático (recomendado):** em **Webhooks**, copie a URL gerada pelo Coolify e cole em **Settings > Webhooks** do repositório no GitHub (evento: `push`). Todo `git push` na branch `main` dispara redeploy.
- **Manual:** clique em **Redeploy** no topo da página da aplicação a qualquer momento.

> ⚠️ Se você trocar o `EKYTE_BEARER_TOKEN`, o Coolify **não** reinicia o container sozinho — clique em **Restart** ou **Redeploy** para aplicar a nova env var.

### Railway

A [Railway](https://railway.com) é uma plataforma cloud PaaS que faz deploy direto do GitHub em ~2 minutos, com HTTPS automático em domínios `*.up.railway.app`. O plano Trial oferece $5 de crédito único para testar, e o plano Hobby custa $5/mês com recursos suficientes para rodar este MCP server 24/7.

> ⚠️ O plano Trial expira quando os $5 acabam. Para produção contínua, migre para o Hobby ($5/mês) — senão o Claude perde acesso quando o serviço for suspenso.

#### Pré-requisitos

- Conta na Railway ([railway.com](https://railway.com)) — pode logar com GitHub
- Repositório `ekyte_mcp_server` no GitHub (recomendado fazer **fork** de `FerrazPiai/ekyte_mcp_server` para controlar quando redeployar)
- Token Ekyte (`EKYTE_BEARER_TOKEN`) e ID da empresa (`EKYTE_COMPANY_ID`) em mãos

#### Passo-a-passo (via UI web)

1. Logue em [railway.com](https://railway.com) e clique em **New Project** no canto superior direito do dashboard.
2. Selecione **Deploy from GitHub repo**. Se for a primeira vez, autorize a Railway a acessar sua conta GitHub (pode limitar a apenas o repositório `ekyte_mcp_server` em **Only select repositories**).
3. Escolha o repositório `ekyte_mcp_server` (seu fork ou o original). A Railway detecta automaticamente o `Dockerfile` na raiz e inicia o build — não precisa configurar buildpack.
4. Enquanto o primeiro build roda, clique no serviço recém-criado e abra a aba **Variables**. Clique em **Raw Editor** no canto superior direito e cole o bloco abaixo, substituindo os valores:

   ```env
   EKYTE_BEARER_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.seu-jwt-completo-aqui
   EKYTE_COMPANY_ID=12345
   TRANSPORT=http
   PORT=3000
   NODE_ENV=production
   ```

   Clique em **Update Variables**. A Railway faz um novo deploy automaticamente com as variáveis aplicadas.

   > ⚠️ Nunca commite o `EKYTE_BEARER_TOKEN` no repositório. Use sempre as Variables da Railway.

5. Vá em **Settings → Networking** e clique em **Generate Domain**. A Railway cria um domínio público do tipo `ekyte-mcp-production-xxxx.up.railway.app` com HTTPS via Let's Encrypt já configurado. Confirme a porta `3000` quando solicitado.
6. *(Opcional)* **Custom Domain:** ainda em **Settings → Networking**, clique em **Custom Domain**, informe seu domínio (ex: `mcp.seudominio.com`) e crie um registro **CNAME** no seu DNS apontando para o target fornecido pela Railway. O certificado TLS é emitido em ~1 minuto após a propagação.
7. *(Opcional)* **Healthcheck:** em **Settings → Deploy**, no campo **Healthcheck Path**, coloque `/health`. Isso faz a Railway aguardar o endpoint responder `200` antes de marcar o deploy como saudável — evita downtime em redeploys.

#### Verificação

```bash
curl https://ekyte-mcp-production-xxxx.up.railway.app/health
# {"status":"ok","server":"ekyte-mcp-server","version":"1.0.0"}
```

Endpoint MCP final: `https://ekyte-mcp-production-xxxx.up.railway.app/mcp`

#### Atualizações automáticas

Todo `git push` no branch `main` do repositório conectado dispara um novo build e deploy automaticamente — sem configuração adicional. Acompanhe em tempo real na aba **Deployments** do serviço. Para pausar, desative **Auto Deploy** em **Settings → Source**.

#### Alternativa: deploy via CLI

Se preferir linha de comando ao invés da UI web:

```bash
npm i -g @railway/cli
railway login                          # abre o browser para autenticar
railway init                           # cria projeto vinculado à pasta atual
railway up                             # envia o código e builda usando o Dockerfile
railway variables --set "EKYTE_BEARER_TOKEN=eyJ..." --set "EKYTE_COMPANY_ID=12345" \
                  --set "TRANSPORT=http" --set "PORT=3000" --set "NODE_ENV=production"
railway domain                         # gera o domínio público *.up.railway.app
```

### Render

[Render](https://render.com) é uma PaaS gerenciada que faz deploy direto do GitHub, com plano Free (dorme após 15min de inatividade) e domínio `*.onrender.com` grátis já com HTTPS/TLS automático — ideal para expor o MCP server ao Claude sem configurar proxy reverso.

#### Pré-requisitos

- Conta no [Render](https://dashboard.render.com) (signup com GitHub recomendado)
- Fork ou acesso ao repositório [`ekyte_mcp_server`](https://github.com/FerrazPiai/ekyte_mcp_server) no GitHub

#### Passo-a-passo (via dashboard)

1. No dashboard do Render, clique em **+ New** (canto superior direito) → **Web Service**.
2. Em **Source Code**, selecione **GitHub** e autorize o Render a acessar o repositório `ekyte_mcp_server`. Clique em **Connect** ao lado do repo.
3. Na tela de configuração, preencha:
   - **Name:** `ekyte-mcp` (será usado no subdomínio: `ekyte-mcp.onrender.com`)
   - **Project:** deixe em branco ou crie um novo (ex: `MCP Servers`)
   - **Language:** `Docker` (o Render detecta automaticamente o `Dockerfile` na raiz)
   - **Branch:** `main`
   - **Region:** `Oregon (US West)` ou `Frankfurt (EU)` — escolha a mais próxima dos usuários. No momento não há região brasileira; Oregon costuma ter latência aceitável a partir do Brasil.
   - **Dockerfile Path:** `./Dockerfile` (padrão)
   - **Instance Type:** `Free` para testes ou `Starter` ($7/mês) para uso contínuo sem sleep
4. Role até a seção **Environment Variables** e clique em **Add Environment Variable** para cada uma das variáveis abaixo:

   ```env
   EKYTE_BEARER_TOKEN=seu_jwt_longo_aqui
   EKYTE_COMPANY_ID=12345
   TRANSPORT=http
   PORT=3000
   NODE_ENV=production
   ```

   > ⚠️ Nunca commite esses valores no repositório. O Render criptografa env vars em repouso e só as expõe ao container em runtime.

5. Expanda **Advanced** e configure:
   - **Health Check Path:** `/health` (o Render vai fazer polling neste endpoint e reiniciar o serviço se falhar)
   - **Auto-Deploy:** `Yes` (padrão — cada `git push` na branch `main` dispara um novo deploy)
6. Clique em **Deploy Web Service** no final da página. O primeiro build leva cerca de 3-5 minutos.

#### Verificação

```bash
curl https://ekyte-mcp.onrender.com/health
# {"status":"ok","server":"ekyte-mcp-server","version":"1.0.0"}
```

Endpoint MCP final: `https://ekyte-mcp.onrender.com/mcp`

#### Atualizações

Com auto-deploy ativo, basta `git push origin main` — o Render detecta o commit, rebuilda a imagem Docker e faz rollout com zero-downtime. Acompanhe os logs em tempo real na aba **Logs** e faça rollback pela aba **Events**.

> ⚠️ **Atenção ao plano Free:** o serviço entra em sleep após 15 minutos sem requests. A primeira chamada após o sleep leva ~30 segundos para acordar o container, o que frequentemente excede o timeout do Claude ao conectar ao MCP. Para uso contínuo/produção, escolha:
>
> - Fazer upgrade para **Starter ($7/mês)** — sem sleep, 512MB RAM, sempre ativo
> - Configurar keep-alive externo (ex: cron-job.org ou UptimeRobot) fazendo `GET /health` a cada 10 minutos — funciona mas pode ser bloqueado pelo Render
> - Usar outro provider (Railway, Fly.io) se o Starter for proibitivo

### Fly.io

Fly.io é uma plataforma edge global que roda containers próximos aos usuários em dezenas de regiões. O deploy é feito inteiramente via CLI (`flyctl`), o que torna o fluxo simples e reproduzível — ideal para MCP servers que atendem clientes distribuídos. Todo app recebe automaticamente um domínio `*.fly.dev` com HTTPS gerenciado (Let's Encrypt).

#### Pré-requisitos

- Conta no [Fly.io](https://fly.io) (cadastro com GitHub ou email)
- Cartão de crédito cadastrado (obrigatório mesmo no tier gratuito — há limite de 3 VMs shared-cpu-1x pequenas grátis)
- CLI `flyctl` instalada localmente
- Git instalado

#### Passo 1 — Instalar o `flyctl`

**Windows (PowerShell):**

```powershell
pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"
```

**macOS / Linux:**

```bash
curl -L https://fly.io/install.sh | sh
```

Valide a instalação:

```bash
fly version
```

#### Passo 2 — Fazer login

```bash
fly auth login
```

Um navegador será aberto para autenticação. Após o login, o token fica salvo localmente.

#### Passo 3 — Clonar o repositório

```bash
git clone https://github.com/FerrazPiai/ekyte_mcp_server.git
cd ekyte_mcp_server
```

#### Passo 4 — Inicializar o app com `fly launch`

O comando abaixo detecta o `Dockerfile` existente e gera um `fly.toml` inicial, **sem fazer deploy ainda** (vamos ajustar configs antes):

```bash
fly launch --no-deploy
```

Responda às perguntas interativas:

- **App name:** escolha algo único, ex: `ekyte-mcp-seunome`
- **Region:** escolha a mais próxima (ex: `gru` para São Paulo, `gig` para Rio)
- **Postgres / Redis / Sentry:** responda `No` para todos
- **Deploy now:** responda `No`

#### Passo 5 — Ajustar o `fly.toml`

Abra o `fly.toml` gerado e garanta que ele tenha as seções abaixo. Exemplo mínimo pronto para copiar:

```toml
# fly.toml — configuração do MCP server Ekyte
app = "ekyte-mcp-seunome"
primary_region = "gru"

[build]
  # usa o Dockerfile multi-stage da raiz
  dockerfile = "Dockerfile"

[env]
  # variáveis NÃO sensíveis — ficam visíveis no dashboard
  TRANSPORT = "http"
  PORT = "3000"
  NODE_ENV = "production"

[http_service]
  internal_port = 3000        # porta exposta pelo container
  force_https = true          # redireciona HTTP -> HTTPS automaticamente
  auto_stop_machines = "stop" # economia: para a VM quando ociosa
  auto_start_machines = true  # religa na próxima request
  min_machines_running = 0

  [[http_service.checks]]
    grace_period = "10s"
    interval = "30s"
    method = "GET"
    timeout = "5s"
    path = "/health"

[[vm]]
  cpu_kind = "shared"
  cpus = 1
  memory_mb = 512
```

> ⚠️ **Atenção ao `internal_port`:** ele deve bater com a porta em que o app escuta dentro do container (3000). Se divergir, o Fly não consegue rotear requests e o healthcheck falha.

#### Passo 6 — Configurar os secrets (vars sensíveis)

No Fly, há **duas formas** de passar variáveis de ambiente para o container:

- **`[env]` no `fly.toml`** — valores em texto plano, visíveis no dashboard e no repo. Use para configs públicas (TRANSPORT, PORT, NODE_ENV).
- **Secrets (`fly secrets set`)** — valores criptografados em repouso, injetados como env vars em runtime mas **nunca expostos**. Use para tokens, chaves de API, credenciais.

O `EKYTE_BEARER_TOKEN` é um JWT longo com acesso à API Ekyte — **sempre** como secret:

```bash
fly secrets set \
  EKYTE_BEARER_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  EKYTE_COMPANY_ID=1234
```

> ⚠️ **Nunca** commite o `EKYTE_BEARER_TOKEN` no `fly.toml` nem em arquivos `.env` versionados. Secrets do Fly são o canal correto.

Confira os secrets cadastrados (o Fly mostra apenas o hash, nunca o valor):

```bash
fly secrets list
```

#### Passo 7 — Fazer o deploy

```bash
fly deploy
```

O Fly vai: subir o contexto do build → construir a imagem Docker remotamente → provisionar uma VM na região escolhida → rodar o healthcheck em `/health` → liberar tráfego quando o check passar.

Ao final, a URL aparece no log (algo como `https://ekyte-mcp-seunome.fly.dev`).

#### Passo 8 — Verificar

```bash
curl https://ekyte-mcp-seunome.fly.dev/health
# {"status":"ok","server":"ekyte-mcp-server","version":"1.0.0"}
```

Endpoint MCP final: `https://ekyte-mcp-seunome.fly.dev/mcp`

#### Atualizando o app

Sempre que houver mudanças no código:

```bash
git pull
fly deploy
```

O Fly faz rebuild + rolling deploy sem downtime perceptível.

#### Comandos úteis no dia a dia

```bash
fly logs              # tail dos logs em tempo real
fly status            # estado das VMs, região, última release
fly secrets list      # lista (apenas os nomes) dos secrets
fly apps open         # abre o app no navegador
fly ssh console       # abre shell dentro da VM (debug)
fly scale count 2     # escalar para 2 instâncias
fly releases          # histórico de deploys (útil para rollback)
```

> ⚠️ **Custo:** o tier gratuito cobre 3 VMs `shared-cpu-1x` com 256MB. Com `auto_stop_machines = "stop"` o app dorme quando ocioso — a primeira request depois disso demora ~1-2s para acordar a VM. Para workloads sempre quentes, setar `min_machines_running = 1` e acompanhar a cobrança em `fly.io/dashboard/billing`.

### VPS genérico (Ubuntu + Docker Compose + Nginx)

Caminho "hardcore" mas 100% portátil — funciona em qualquer VPS Ubuntu/Debian (Hostinger VPS, DigitalOcean Droplet, Hetzner Cloud, Contabo, Vultr, AWS Lightsail, etc.). Dá muito mais controle sobre a infra, mas exige configurar Nginx e SSL na mão. Se você quer algo plug-and-play, prefira um painel (Easypanel, Coolify); se quer entender tudo que está rodando, segue o fluxo abaixo.

#### Pré-requisitos

- VPS com Ubuntu 22.04+ (ou Debian 11+) e acesso SSH como `root` ou usuário com `sudo`
- Domínio próprio com um A-record apontando para o IP público do VPS (ex: `ekyte-mcp.seu-dominio.com` → `203.0.113.42`)
- Portas `22`, `80` e `443` liberadas no firewall do provedor (security group / cloud firewall)

> ⚠️ Em provedores como AWS Lightsail, DigitalOcean e Hetzner, o firewall do painel é **independente** do UFW do sistema. Libere as portas nos dois lugares, senão o Certbot não consegue validar o domínio.

#### Passo 1 — Instalar Docker e Docker Compose

```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
```

> ⚠️ Depois de rodar o `usermod`, saia do SSH (`exit`) e reconecte — o grupo `docker` só é aplicado em novas sessões. Sem isso, você vai precisar usar `sudo` em todo comando `docker`.

Confira se ficou OK:

```bash
docker --version
docker compose version
```

#### Passo 2 — Clonar o repositório

```bash
git clone https://github.com/FerrazPiai/ekyte_mcp_server.git
cd ekyte_mcp_server
```

#### Passo 3 — Criar o arquivo `.env`

Na raiz do projeto, crie um `.env` baseado no `.env.example`:

```bash
cp .env.example .env
nano .env
```

Conteúdo completo:

```env
EKYTE_BEARER_TOKEN=seu_jwt_longo_aqui
EKYTE_COMPANY_ID=12345
TRANSPORT=http
PORT=3000
```

> ⚠️ Nunca commite o `.env` — ele já está no `.gitignore`. O token JWT da Ekyte dá acesso total à sua conta, trate como senha.

#### Passo 4 — Subir o container

```bash
docker compose up -d --build
docker compose logs -f
```

Em outra sessão SSH (ou `Ctrl+C` nos logs), valide que o health check responde localmente:

```bash
curl http://localhost:3000/health
```

Deve retornar `{"status":"ok",...}`. Se não responder, cheque os logs — normalmente é token inválido ou `EKYTE_COMPANY_ID` errado.

#### Passo 5 — Configurar Nginx como reverse proxy

Instale o Nginx:

```bash
sudo apt update
sudo apt install nginx -y
```

Crie o server block:

```bash
sudo nano /etc/nginx/sites-available/ekyte-mcp
```

Cole o conteúdo abaixo (troque `ekyte-mcp.seu-dominio.com` pelo seu domínio real):

```nginx
server {
    listen 80;
    listen [::]:80;
    server_name ekyte-mcp.seu-dominio.com;

    client_max_body_size 10M;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        "upgrade";

        proxy_connect_timeout 120s;
        proxy_send_timeout    120s;
        proxy_read_timeout    120s;
    }
}
```

Ative o site, teste a configuração e recarregue o Nginx:

```bash
sudo ln -s /etc/nginx/sites-available/ekyte-mcp /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
```

> ⚠️ Os timeouts de 120s são importantes: algumas tools do MCP (como listagens grandes da Ekyte) podem levar mais de 30s. Sem isso, o Nginx corta a conexão antes do Claude receber a resposta.

#### Passo 6 — SSL com Certbot (Let's Encrypt grátis)

```bash
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d ekyte-mcp.seu-dominio.com
```

O Certbot vai pedir seu e-mail, aceitar os termos e perguntar se quer redirecionar HTTP para HTTPS — responda **sim**. Ele reescreve o server block automaticamente, adiciona os blocos `listen 443 ssl` e instala um cron de renovação automática (`/etc/cron.d/certbot`).

> ⚠️ Se o A-record do domínio ainda não propagou, o Certbot falha com erro de validação. Confira com `dig +short ekyte-mcp.seu-dominio.com` antes de rodar — propagação DNS pode levar de 5 minutos a algumas horas.

#### Passo 7 — Verificar o deploy

```bash
curl https://ekyte-mcp.seu-dominio.com/health
# {"status":"ok","server":"ekyte-mcp-server","version":"1.0.0"}
```

Endpoint MCP final: `https://ekyte-mcp.seu-dominio.com/mcp`

#### Passo 8 — Atualizar depois de mudanças no repo

```bash
cd ~/ekyte_mcp_server
git pull
docker compose up -d --build
```

O Nginx e o Certbot continuam funcionando normalmente — só o container Node é recriado.

#### Dica final — Firewall com UFW

Feche tudo que não é essencial:

```bash
sudo ufw allow 22
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enable
```

> ⚠️ Rode o `ufw allow 22` **antes** de habilitar o UFW, senão você se tranca fora do SSH e vai precisar usar o console web do provedor para recuperar o acesso.

## Conexão com o Claude

### Claude Code (CLI) — transporte HTTP remoto

No diretório do projeto onde você vai usar a MCP, crie `.mcp.json`:

```json
{
  "mcpServers": {
    "ekyte": {
      "type": "http",
      "url": "https://ekyte-mcp.seu-dominio.com/mcp"
    }
  }
}
```

Ou no escopo de usuário, via CLI:

```bash
claude mcp add --transport http ekyte https://ekyte-mcp.seu-dominio.com/mcp --scope user
```

Teste: `claude mcp list` deve mostrar `ekyte ✓ connected`.

### Claude Desktop — transporte stdio local

Rode o servidor em modo `stdio` (sem HTTP). No `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ekyte": {
      "command": "node",
      "args": ["C:/caminho/para/ekyte-mcp-server/dist/index.js"],
      "env": {
        "EKYTE_BEARER_TOKEN": "seu_jwt",
        "EKYTE_COMPANY_ID": "1234",
        "TRANSPORT": "stdio"
      }
    }
  }
}
```

### Claude Desktop — transporte HTTP remoto (com MCP remoto instalado no EasyPanel)

```json
{
  "mcpServers": {
    "ekyte": {
      "url": "https://ekyte-mcp.seu-dominio.com/mcp"
    }
  }
}
```

## Skill do Claude para operar o Ekyte com segurança

Conectar a MCP só dá ao Claude *acesso* às tools. Sem contexto adicional, a IA pode chutar IDs de workspace, inventar datas ou criar tarefa no cliente errado — especialmente em operações destrutivas.

O repo inclui uma **skill pronta** em [`.claude/skills/ekyte/`](./.claude/skills/ekyte/) que resolve isso: ensina o Claude a sempre listar antes de criar, confirmar todos os dados com o usuário antes de operações destrutivas, usar UUIDs corretos, formato `AAAA-MM-DD` para datas e filtrar listagens por workspace para performance.

**Se você seguiu o [PRD de instalação](#instalação-rápida-via-prd-recomendado), a skill já foi instalada automaticamente** em `~/.claude/skills/ekyte/` junto com a MCP — nada a fazer aqui.

Se instalou a MCP manualmente e quer adicionar a skill depois, a forma mais rápida é pedir no chat do Claude Code:

> *"Instala a skill do Ekyte seguindo o Passo 5 (Local) ou Passo 3 (Remoto) do [PRD-INSTALACAO-MCP-EKYTE.md](./PRD-INSTALACAO-MCP-EKYTE.md)"*

O Claude executa os comandos abaixo automaticamente — essa seção documenta o que ele faz (útil se você preferir rodar manualmente ou auditar antes).

### O que a skill garante

- **Nunca cria tarefa sem confirmar:** sempre lista workspaces, task types, phases e usuários antes de chamar `ekyte_create_task`, e valida todos os dados com o usuário.
- **Nunca inventa IDs:** `executor_id` sempre é UUID (ex: `00000000-0000-0000-0000-000000000001`), nunca número — a skill lembra disso.
- **Formato de datas correto:** `AAAA-MM-DD` (sem hora), `HH:MM` para horários, `end_time > start_time` em apontamentos.
- **Confirmação em operações destrutivas:** criar tarefa, completar tarefa, deletar apontamento, apontar horas — tudo pergunta antes de executar.
- **Performance:** usa `search` nas listagens (evita paginar 600+ workspaces), filtra `list_tasks` por workspace_id, avisa quando listagem pode demorar (10-30s).
- **Sabe a diferença entre** `ekyte_update_task` (fase atual) e `ekyte_update_phase` (fase específica não-atual) — bug comum quando a IA não tem contexto.

### Como instalar a skill (one-liner, sem clonar o repo)

Ideal para quem só usa a MCP via HTTP remoto. Baixa os dois arquivos do GitHub direto para `~/.claude/skills/ekyte/`:

**Linux / macOS (bash/zsh):**

```bash
mkdir -p ~/.claude/skills/ekyte && \
  curl -fsSL -o ~/.claude/skills/ekyte/SKILL.md \
    https://raw.githubusercontent.com/FerrazPiai/ekyte_mcp_server/main/.claude/skills/ekyte/SKILL.md && \
  curl -fsSL -o ~/.claude/skills/ekyte/reference.md \
    https://raw.githubusercontent.com/FerrazPiai/ekyte_mcp_server/main/.claude/skills/ekyte/reference.md
```

**Windows (PowerShell):**

```powershell
$dst = "$env:USERPROFILE\.claude\skills\ekyte"
New-Item -ItemType Directory -Force -Path $dst | Out-Null
$base = "https://raw.githubusercontent.com/FerrazPiai/ekyte_mcp_server/main/.claude/skills/ekyte"
Invoke-WebRequest -Uri "$base/SKILL.md"     -OutFile "$dst\SKILL.md"
Invoke-WebRequest -Uri "$base/reference.md" -OutFile "$dst\reference.md"
```

Pronto — a skill fica disponível **em qualquer sessão** do Claude Code/Desktop, independente de projeto.

### Como instalar a skill (via git clone)

Se você já **clonou o repo** para fazer deploy local, copiar a skill para o global é instantâneo:

```bash
# Linux / macOS
mkdir -p ~/.claude/skills
cp -r .claude/skills/ekyte ~/.claude/skills/

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse .claude\skills\ekyte "$env:USERPROFILE\.claude\skills\"
```

Alternativa **sem copiar** (per-project): se você abre o Claude Code **dentro da pasta do repo**, a skill é detectada automaticamente via `.claude/skills/ekyte/` — sem precisar instalar no global.

### Usando a skill

Depois de instalada, é só pedir em linguagem natural:

> *"Crie uma tarefa no Ekyte para o cliente X, fase Y, responsável Z"*
> *"Quantas horas foram apontadas essa semana no workspace Acme?"*
> *"Liste as tarefas ativas do responsável Fulano"*

O Claude invoca a skill `ekyte` automaticamente (Code ou Desktop) e segue o fluxo correto: lista → confirma → executa. Para forçar invocação explícita, use `/ekyte <o que quer fazer>`.

### Atualizando a skill

Quando o repo receber updates no `SKILL.md` ou `reference.md`, basta rodar o one-liner (ou `git pull` + `cp -r` se instalou via clone) de novo — ele sobrescreve os arquivos locais com a versão mais recente do `main`.

> ⚠️ Sem a skill, o Claude pode criar tarefas no workspace errado, chutar UUIDs de usuário ou pular a confirmação em operações destrutivas. Se reinstalar a MCP em outra máquina, reinstale a skill também (o PRD cuida disso automaticamente).

## Desenvolvimento local

```bash
npm install
npm run build

# Modo stdio (default) — para Claude Desktop
EKYTE_BEARER_TOKEN=xxx EKYTE_COMPANY_ID=1234 npm start

# Modo HTTP — simula o deploy EasyPanel
EKYTE_BEARER_TOKEN=xxx EKYTE_COMPANY_ID=1234 TRANSPORT=http npm start

# Hot reload
npm run dev
```

Smoke test rápido (HTTP):

```bash
curl http://localhost:3000/health
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Arquitetura

```
src/
├── index.ts               # Entry point (stdio + HTTP streamable)
├── constants.ts           # Base URL, timeouts, limites
├── types.ts               # Tipos do Ekyte
├── services/
│   └── ekyte-client.ts    # Cliente axios + helpers companyUrl / companyV2Url
├── schemas/
│   ├── common.ts          # Schemas Zod compartilhados
│   ├── task.ts            # Schemas de tarefas e fases
│   └── time-entry.ts      # Schemas de apontamentos
└── tools/
    ├── read-tools.ts      # Tools de leitura
    └── write-tools.ts     # Tools de escrita
```

## Endpoints que a MCP usa (referência)

Todos com `Authorization: Bearer <jwt>` e base `https://api.ekyte.com`:

| Método | Path | Tool |
|--------|------|------|
| GET | `/api/companies/{id}/workspaces` | list_workspaces |
| GET | `/api/companies/{id}/users` | list_users |
| GET | `/api/companies/{id}/task-types` | list_task_types |
| GET | `/api/companies/{id}/workflows/{wf}` | list_phases (retorna `phases[]`) |
| GET | `/api/v2/companies/{id}/ctc-tasks` | list_tasks |
| GET | `/api/v2/companies/{id}/ctc-tasks/{task}` | get_task |
| GET | `/api/v2/companies/{id}/ctc-tasks/{task}/flow-phases` | list_task_flow_phases |
| POST | `/api/companies/{id}/ctc-tasks` | create_task (suporta `flow[]` multi-fase) |
| PATCH | `/api/v2/companies/{id}/ctc-tasks/{task}` | update_task / complete_task |
| PATCH | `/api/v2/companies/{id}/ctc-tasks/{task}/flow-phase/{phase}` | update_phase |
| POST | `/api/v2/companies/{id}/ctc-tasks/{task}/comments` | add_task_comment |
| GET | `/api/companies/{id}/time-trackings/data/details` | list_time_entries |
| POST | `/api/companies/{id}/workspaces/{ws}/time-trackings` | create_time_entry_* |
| PATCH | `/api/companies/{id}/workspaces/{ws}/time-trackings/{id}` | delete_time_entry |