suite-timesheet-mcp 1.0.0

package/CONTRACT.md

@@ -0,0 +1,143 @@
+# Contrato
+
+A fonte deste contrato é o `CONTRACT.md` do repo da extensão (`suite-timesheet-importer`). Esta
+cópia existe para quem só clona este pacote. Se divergirem, manda o da extensão.
+
+## Ponte (opcional): o serviço manda comandos à extensão
+
+Um serviço que implemente estas três rotas passa a poder pedir leituras e propor lançamentos
+à extensão. Quem só quer entregar um ficheiro de horas não precisa delas.
+
+| método | rota | corpo / resposta |
+|---|---|---|
+| `POST` | `/bridge/contexto` | a extensão envia `{ano, mes, diasNoMes, projetos: [{option_id, nome, trancado}], lidoEm}` sempre que a Folha de Horas carrega ou muda de mês |
+| `GET` | `/bridge/next?wait=25` | responde `204` sem corpo se não houver comando ao fim de `wait` segundos, ou `200` com um comando |
+| `POST` | `/bridge/result/{id}` | a extensão publica o resultado do comando `id` |
+
+Comando: `{"id": "texto", "tipo": "estado" | "projetos" | "ler" | "propor" | "aplicar", "ano": 2026, "mes": 9}`.
+`propor` leva ainda `"linhas": [{option_id | project, date, hours}]`, `"espelho": false` e
+`"nome": "texto"`. O mês tem de ser o que a página mostra; caso contrário a resposta é
+`ERR_MES_DIFERENTE` e nada é lido nem escrito.
+
+### `aplicar`: escreve uma proposta pendente sem o clique no painel
+
+`aplicar` leva ainda `"proposta": "id"`, o `id` de um comando `propor` já entregue à extensão e
+ainda sem `final` (ou seja, com o painel aberto à espera de decisão). Em vez de esperar que o
+utilizador clique Aplicar, o cliente MCP (com a aprovação humana já dada no chat, e a aprovação
+da própria chamada da tool) manda escrever essa proposta diretamente.
+
+A extensão trata `aplicar` como um comando novo e independente (com o seu próprio `id`), que
+resolve o `propor` referido em `proposta`:
+
+- Escreve linha a linha, tal como faria depois do clique em Aplicar — mesmas validações (linhas
+  trancadas recusadas, sessão expirada para tudo), mesmo `report`.
+- Responde ao comando `aplicar` com `{"ok": true, "dados": {"estado": "aplicado" | "erro",
+  "report"?, "stopped"?, "erro"?}}` (uma só fase, sem `previa`) ou `{"ok": false, "erro":
+  {"code", "message"}}`.
+- Publica também o `final` do `propor` original (mesmo `{"fase": "final", "estado": ...}` de
+  sempre), para quem ainda estiver a chamar `resultado(<id do propor>)` continuar a funcionar.
+
+`ERR_PROPOSTA_DESCONHECIDA`: não há nenhum `propor` pendente com o `id` indicado em `proposta`
+(nunca existiu, já teve `final`, ou o `serve`/worker reiniciou e perdeu-o). `aplicar` nunca é
+bloqueado por `ERR_OCUPADO` — não é um novo `propor` à espera de painel, é a resolução de um que
+já existe.
+
+Resultado: `{"ok": true, "dados": ...}` ou `{"ok": false, "erro": {"code", "message"}}`.
+`propor` publica dois resultados com o mesmo `id`: primeiro `{"fase": "previa", "previa": {...}}`
+com o plano calculado (o painel abre nesse momento), e depois, quando o utilizador decide,
+`{"fase": "final", "estado": "aplicado" | "cancelado" | "erro", ...}`.
+
+A extensão continua a ser a única coisa que escreve no Suite, sempre depois de o utilizador
+clicar Aplicar no painel ou de aprovar a tool `aplicar` no cliente MCP (ver secção "aplicar"
+abaixo). Nunca submete o mês, nunca muda o mês.
+
+### Prazo de `/bridge/next`
+
+O `serve` tem de responder a `GET /bridge/next?wait=25` dentro de, aproximadamente, 28 segundos
+— mesmo sem comando (nesse caso, `204`). O worker pede `wait=25` (e este `serve` recusa um
+`wait` maior que 25), mas o Chrome mata um service worker MV3 cujo `fetch` demora mais de 30 s a
+resolver; um `serve` que ignore o `wait` ou que demore a responder além desse limite faz o
+worker perder o ciclo (e reentrar só ao alarme de 30 s seguinte), mesmo que a resposta acabe por
+chegar.
+
+### Formato de `dados` por tipo de comando
+
+Resultado com `"ok": true`, no campo `dados`:
+
+| `tipo` | forma de `dados` |
+|---|---|
+| `estado` | `{ano, mes, projetos: N, loteEmCurso: boolean}` — `projetos` é a contagem, não a lista |
+| `projetos` | `[{option_id, nome, trancado}]` |
+| `ler` | `{ano, mes, linhas: [{option_id, nome, status, dias: {D: horas}, total}], totaisPorDia: {D: horas}}` |
+| `propor`, fase `previa` | `{fase: 'previa', previa: {matriz, criar, atualizar, apagar, ignoradas, avisos, erros, bloqueio}}` — `criar`/`atualizar`/`apagar` são listas de `{option_id, projeto, dias}`; `bloqueio` é a mensagem em português ou `null` |
+| `propor`, fase `final` | `{fase: 'final', estado: 'aplicado' \| 'cancelado' \| 'erro', report?, motivo?, erro?}` — `report` só em `aplicado` (`{results, stopped, reconciliacao, skipped}`), `motivo` só em `cancelado`, `erro` (`{code, message}`) só em `erro` |
+| `aplicar` (uma só fase) | `{estado: 'aplicado' \| 'erro', report?, stopped?, erro?}` — sem `fase: 'previa'`; ver secção "aplicar" acima |
+
+### Códigos de erro
+
+`{"ok": false, "erro": {"code", "message"}}`. Códigos que o worker pode devolver:
+
+| código | motivo |
+|---|---|
+| `ERR_COMANDO` | corpo do comando malformado (id/tipo/ano/mes/linhas inválidos) |
+| `ERR_MES_DIFERENTE` | o comando pede um mês diferente do que a página do Suite tem aberto |
+| `ERR_SEM_CONTEXTO` | a Folha de Horas do Suite ainda não foi aberta nesta sessão |
+| `ERR_SEM_ABA` | não há nenhuma aba do Suite aberta (só em `propor`; sem aba o painel não abre) |
+| `ERR_OCUPADO` | já há uma proposta do MCP à espera de confirmação no painel, ou (no APPLY) uma proposta a ser calculada |
+| `ERR_LOTE_A_CORRER` | já está um lote a escrever no Suite (Aplicar), ou (no `propor`) já está um propor a ser calculado |
+| `ERR_SESSION` | o Suite devolveu HTML de login: a sessão expirou |
+| `ERR_MONTH_MISMATCH` | o read do Suite não cobre os projetos visíveis na página |
+| `ERR_PROPOSTA_DESCONHECIDA` | `aplicar` referiu, em `proposta`, um `id` sem `propor` pendente (só em `aplicar`) |
+| `ERR_DESCONHECIDO` | qualquer outro erro não classificado |
+
+Este `serve` acrescenta o seu próprio `ERR_EXPIRADO` (ver secção seguinte) e usa
+`ERR_SEM_CHROME`/`ERR_SEM_CONTEXTO` nas suas próprias rotas `/mcp/*` (ver "Rotas deste serve").
+
+### Um comando sem resposta nunca é respondido
+
+Se o service worker morrer (o Chrome pode matá-lo a qualquer momento fora de um fetch pendente)
+depois de o `serve` entregar um comando em `/bridge/next` mas antes de ele publicar o resultado
+em `/bridge/result/{id}`, esse comando fica sem resposta — o worker que reentra ao alarme
+seguinte não retoma comandos a meio, só pede o próximo.
+
+Este `serve` dá um timeout a cada comando pendente: expira com
+`{"ok": false, "erro": {"code": "ERR_EXPIRADO", ...}}` se nunca chega a ser entregue dentro do
+`timeout_s` do pedido que o enfileirou (defeito 30 s), ou se é um `propor` entregue mas que não
+devolveu a previa em 120 s. Um comando expirado torna-se final, o que também liberta o próximo
+`propor` bloqueado.
+
+## CORS
+
+A extensão chama o serviço a partir do service worker com `host_permissions` para
+`http://127.0.0.1/*`; **não** é preciso enviar cabeçalhos CORS.
+
+## Rotas deste `serve`
+
+### `/mcp/*` — só o `mcp.js` chama
+
+| método | rota | efeito |
+|---|---|---|
+| `GET` | `/mcp/estado` | contexto conhecido + `ponte: 'ligada' \| 'sem-chrome'` (ligada = long-poll ativo há menos de 40 s) + `ultimoMcp` (ISO do último pedido a `/mcp/*`, incluindo este) |
+| `POST` | `/mcp/comando` | enfileira, espera até `timeout_s` s pelo resultado (defeito 30, máximo 290; `aplicar` tem defeito 120 — escreve linha a linha), devolve `{id, estado, resultado?}` |
+| `GET` | `/mcp/comando/{id}?wait=N&fase=previa\|final` | espera pelo resultado de um comando já enfileirado; `fase` (defeito `final`) escolhe entre a pré-visualização ou o estado final de um `propor` |
+
+`ERR_SEM_CHROME`: sem long-poll recente (o worker não está a correr, ou a extensão não tem a
+permissão de `http://127.0.0.1/*`). `ERR_SEM_CONTEXTO`: a ponte está viva (o worker continua a
+fazer long-poll) mas o `serve` reiniciou depois de a página já ter carregado — falta um novo
+`POST /bridge/contexto`, que só volta a chegar quando a Folha de Horas recarregar.
+
+### Contrato antigo (ficheiro/serviço simples, sem MCP)
+
+Estas duas rotas são o mesmo contrato "serviço local" que o `CONTRACT.md` da extensão descreve
+para quem não precisa da ponte nem do MCP — só entregar horas por HTTP.
+
+| método | rota | efeito |
+|---|---|---|
+| `GET` | `/health` | `200 application/json` com `{nome: 'suite-timesheet-serve', versao, ultimoMcp, ponte}`; `ultimoMcp` é o ISO do último pedido a `/mcp/*` (ou `null` se nenhum desde o arranque) e `ponte` é o mesmo valor que `/mcp/estado`. A extensão usa `nome` para confirmar que é este serve (e não outro programa) a responder na porta — um corpo que não seja este JSON conta como "outro programa na porta". |
+| `GET` | `/timesheet?year=YYYY&month=M` | `200 application/json` com `{year, month, generated_at, rows}`; `rows` vem da última proposta aceite (por `propor`) para esse mês, ou `[]` |
+
+## O que este `serve` NÃO faz
+
+Não escreve no Suite, não fala com o Suite. Toda a escrita é feita pela extensão, dentro do
+browser, com a sessão do utilizador — sempre depois de o utilizador clicar Aplicar no painel ou
+de aprovar a tool `aplicar` no cliente MCP.

package/LICENSE

@@ -0,0 +1,99 @@
+suite-timesheet-mcp — Source-Available License
+Copyright (c) 2026 Willian Saez. All rights reserved.
+
+The English text below is the governing version. The Portuguese translation that follows is
+provided for convenience; if the two differ, the English text prevails.
+
+-------------------------------------------------------------------------------
+ENGLISH
+-------------------------------------------------------------------------------
+
+1. Definitions. "Software" means the source code, documentation and other files in this
+   repository and in any package built from it. "You" means the individual or legal entity
+   exercising the permissions granted by this license.
+
+2. Permitted use. Subject to the conditions of this license, you may:
+   a) view and read the Software;
+   b) download, install and run unmodified copies of the Software, including through package
+      tools such as npm or npx, solely for your own personal use or for the internal business
+      purposes of your organization, by you and your organization's employees and contractors.
+
+3. Restrictions. Except as expressly permitted in section 2, you may not, in whole or in part:
+   a) modify, adapt, translate or create derivative works of the Software;
+   b) copy the Software, except for the copies strictly necessary for the use permitted in
+      section 2 (including those made automatically by package managers and caches);
+   c) distribute, publish, sublicense, sell, rent, lend or otherwise make the Software available
+      to any third party, including by hosting copies, mirrors or forks of it on any platform or
+      offering it as a service;
+   d) remove or alter this license or any copyright notice.
+
+   A fork created through a code-hosting platform's own features (for example, under the terms
+   of service of GitHub) grants no rights beyond viewing it on that platform; any other use of
+   such a fork is subject to the restrictions above.
+
+4. Reservation of rights. All rights not expressly granted are reserved by the copyright holder.
+   No right is granted to any trademark, name or logo.
+
+5. Termination. This license terminates automatically if you breach any of its terms. Upon
+   termination you must stop using the Software and delete all copies in your possession.
+
+6. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+   PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+7. Limitation of liability. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER DEALINGS IN THE
+   SOFTWARE, INCLUDING ANY DATA ENTERED INTO THIRD-PARTY SYSTEMS THROUGH IT.
+
+8. Other permissions. Any use not permitted by this license, including contributions,
+   modifications or redistribution, requires the prior written permission of the copyright
+   holder.
+
+-------------------------------------------------------------------------------
+PORTUGUÊS (tradução)
+-------------------------------------------------------------------------------
+
+1. Definições. "Software" designa o código-fonte, a documentação e os demais ficheiros deste
+   repositório e de qualquer pacote gerado a partir dele. "Tu" designa a pessoa singular ou
+   coletiva que exerce as permissões concedidas por esta licença.
+
+2. Uso permitido. Nas condições desta licença, podes:
+   a) ver e ler o Software;
+   b) descarregar, instalar e executar cópias não modificadas do Software, incluindo através de
+      ferramentas de pacotes como npm ou npx, exclusivamente para uso pessoal ou para fins
+      internos da tua organização, por ti e pelos colaboradores e prestadores de serviços dessa
+      organização.
+
+3. Restrições. Salvo o expressamente permitido na secção 2, não podes, no todo ou em parte:
+   a) modificar, adaptar, traduzir ou criar obras derivadas do Software;
+   b) copiar o Software, exceto as cópias estritamente necessárias ao uso permitido na secção 2
+      (incluindo as feitas automaticamente por gestores de pacotes e caches);
+   c) distribuir, publicar, sublicenciar, vender, alugar, emprestar ou de outra forma
+      disponibilizar o Software a terceiros, incluindo alojar cópias, espelhos ou forks dele em
+      qualquer plataforma ou oferecê-lo como serviço;
+   d) remover ou alterar esta licença ou qualquer aviso de direitos de autor.
+
+   Um fork criado através das funcionalidades de uma plataforma de alojamento de código (por
+   exemplo, ao abrigo dos termos de serviço do GitHub) não confere nenhum direito além de o
+   ver nessa plataforma; qualquer outro uso desse fork está sujeito às restrições acima.
+
+4. Reserva de direitos. Todos os direitos não expressamente concedidos ficam reservados ao
+   titular dos direitos de autor. Não é concedido nenhum direito sobre marcas, nomes ou logótipos.
+
+5. Cessação. Esta licença cessa automaticamente se violares qualquer dos seus termos. Com a
+   cessação, deves deixar de usar o Software e apagar todas as cópias em teu poder.
+
+6. Sem garantia. O SOFTWARE É FORNECIDO "TAL COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO,
+   EXPRESSA OU IMPLÍCITA, INCLUINDO, SEM LIMITAÇÃO, AS GARANTIAS DE COMERCIABILIDADE, ADEQUAÇÃO
+   A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO.
+
+7. Limitação de responsabilidade. EM CASO ALGUM O TITULAR DOS DIREITOS DE AUTOR SERÁ
+   RESPONSÁVEL POR QUALQUER RECLAMAÇÃO, DANO OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO
+   CONTRATUAL, EXTRACONTRATUAL OU OUTRA, DECORRENTE DO SOFTWARE, DO SEU USO OU DE OUTRAS
+   OPERAÇÕES COM ELE, INCLUINDO QUAISQUER DADOS INTRODUZIDOS EM SISTEMAS DE TERCEIROS ATRAVÉS
+   DELE.
+
+8. Outras permissões. Qualquer uso não permitido por esta licença, incluindo contribuições,
+   modificações ou redistribuição, requer autorização prévia e por escrito do titular dos
+   direitos de autor.

package/README.md

@@ -0,0 +1,202 @@
+# suite-timesheet-mcp
+
+Servidor MCP que deixa um assistente (Claude, GitHub Copilot, ou outro cliente MCP) **ler e
+propor horas** na Folha de Horas do Suite, através da extensão **Suite Timesheet Importer**.
+
+- **Nunca fala com o Suite.** Quem lê e escreve é a extensão, no teu browser, com a tua sessão.
+- **Nunca escreve sem ti.** Cada lançamento é uma proposta; só é escrito quando clicas Aplicar
+  no painel ou aprovas a tool `aplicar` no teu cliente MCP.
+- **Nunca submete meses** nem muda o mês aberto na página.
+- **Só local.** Escuta apenas em `127.0.0.1`, guarda tudo em memória, não tem telemetria.
+
+Detalhes e forma de verificar cada afirmação: [SECURITY.md](SECURITY.md).
+
+## Requisitos
+
+- Node.js ≥ 20 (`node -v`).
+- Chrome ou Edge com a extensão Suite Timesheet Importer instalada.
+- A Folha de Horas do Suite aberta, com sessão válida.
+
+## Instalação
+
+### 1. Ligar a ponte na extensão
+
+Nas **Opções** da extensão, liga **Ligação ao servidor local (ponte MCP)**, clica em
+**Guardar** e aceita a permissão para `http://127.0.0.1/*`. Depois recarrega a Folha de Horas.
+
+Este passo é manual e feito uma vez: sem ele a extensão nunca toca na rede local.
+
+### 2. Registar o servidor no teu cliente MCP
+
+Não é preciso clonar nada: o `npx` descarrega o pacote do npm e corre-o. `@1` fixa a versão
+principal: recebes as correções 1.x, nunca uma versão incompatível. A primeira execução demora
+alguns segundos; as seguintes usam a cache.
+
+**Claude Code**
+
+```bash
+claude mcp add --scope user suite-timesheet -- npx -y suite-timesheet-mcp@1
+```
+
+**GitHub Copilot (VS Code)**
+
+```bash
+code --add-mcp '{"name":"suite-timesheet","command":"npx","args":["-y","suite-timesheet-mcp@1"]}'
+```
+
+Depois recarrega a janela; as tools aparecem no modo **Agent** do Copilot.
+
+**Claude Desktop (inclui Cowork)**
+
+Em Definições → Programador → Editar configuração
+(`~/Library/Application Support/Claude/claude_desktop_config.json` no macOS,
+`%APPDATA%\Claude\claude_desktop_config.json` no Windows):
+
+```json
+{
+  "mcpServers": {
+    "suite-timesheet": {
+      "command": "npx",
+      "args": ["-y", "suite-timesheet-mcp@1"]
+    }
+  }
+}
+```
+
+Reinicia o Claude Desktop.
+
+**Outros clientes**
+
+O mesmo comando: `npx -y suite-timesheet-mcp@1`, por stdio. Atenção à
+chave do ficheiro de configuração: o VS Code usa `servers`, a maioria dos outros usa
+`mcpServers`.
+
+> Se o cliente não encontrar o `npx` (comum em apps abertas pelo Dock, que não herdam o PATH
+> do terminal), usa o caminho absoluto dado por `which npx`. No Windows, usa
+> `"command": "cmd"` com `"args": ["/c", "npx", "-y", "…"]`.
+
+### 3. Verificar
+
+Pede ao assistente: *"consulta o estado da ponte do Suite Timesheet"*. A tool `estado` deve
+responder com a ponte ligada e o mês visível na página. As Opções da extensão passam a mostrar
+"Claude ligado há N s" (o texto é o mesmo para qualquer cliente).
+
+## Instalação feita por um agente
+
+Se estás a pedir a um agente para instalar isto, ele deve seguir esta ordem e parar no primeiro
+passo que falhe:
+
+1. Confirmar `node -v` ≥ 20.
+2. Correr o comando do passo 2 correspondente ao cliente em uso.
+3. Pedir ao utilizador para fazer o passo 1 (Opções da extensão). O agente não o consegue fazer.
+4. Pedir ao utilizador para recarregar o cliente MCP, se o cliente o exigir.
+5. Chamar a tool `estado`. Sucesso = ponte ligada e mês visível. Qualquer `ERR_*`: ver
+   [Erros](#erros).
+
+O agente **não** deve pôr a tool `aplicar` em aprovação automática.
+
+## Usar
+
+Exemplos de pedidos:
+
+- *"Quantas horas tenho lançadas este mês no Suite?"* → `ler_mes`
+- *"Que projetos tenho disponíveis?"* → `projetos`
+- *"Lança 8 h no projeto X de segunda a sexta desta semana."* → `propor`, depois `aplicar`
+
+Lançar horas tem sempre duas fases:
+
+1. **`propor`** calcula o plano, abre o painel da extensão com a pré-visualização e devolve-a ao
+   assistente. Nada é escrito.
+2. **Confirmação**, de uma de duas formas:
+   - clicas **Aplicar** no painel, ou
+   - dizes OK no chat e aprovas a chamada da tool **`aplicar`** no cliente MCP.
+
+Por isso: **mantém a aprovação manual da tool `aplicar`**. Com ela em aprovação automática,
+qualquer proposta é escrita sem mais nenhuma confirmação. Linhas trancadas e propostas
+bloqueadas são sempre recusadas pela extensão.
+
+## Tools
+
+| tool | faz |
+|---|---|
+| `estado` | ponte ligada?, mês visível, nº de projetos, lote a correr |
+| `projetos` | projetos do dropdown da página: `option_id`, nome, trancado |
+| `ler_mes` | horas já lançadas no mês visível |
+| `propor` | calcula o plano, abre o painel, devolve a pré-visualização e um `id` |
+| `aplicar` | escreve a proposta `id` no Suite através da extensão |
+| `resultado` | espera pela decisão (painel ou `aplicar`): aplicado, cancelado, erro ou pendente |
+
+## Erros
+
+| erro | o que fazer |
+|---|---|
+| `ERR_SERVE_EM_BAIXO` | o serviço local não responde; reinicia o cliente MCP (ele arranca-o sozinho) |
+| `ERR_SEM_CHROME` | abre a Folha de Horas e confirma que a ponte está ligada nas Opções |
+| `ERR_SEM_CONTEXTO` | recarrega a Folha de Horas (o serviço reiniciou depois de a página carregar) |
+| `ERR_MES_DIFERENTE` | muda o mês na página; o MCP nunca o muda por ti |
+| `ERR_OCUPADO` | há uma proposta à espera no painel; aplica-a ou cancela-a primeiro |
+| `ERR_PROPOSTA_DESCONHECIDA` | o `id` passado a `aplicar` não corresponde a nenhuma proposta pendente |
+
+## Como funciona
+
+```
+cliente MCP ──stdio──▶ mcp.js ──HTTP──▶ serve.js ◀──long-poll── extensão ──▶ Suite
+                                        127.0.0.1                    │
+                                                              painel: Aplicar
+```
+
+1. O cliente MCP arranca o `mcp.js`. Se o serviço local (`serve.js`) não estiver a correr, o
+   `mcp.js` arranca-o em segundo plano, em `127.0.0.1:18765`.
+2. A extensão, com a Folha de Horas aberta, faz long-poll ao serviço e publica o mês visível.
+3. Cada tool enfileira um comando; a extensão executa-o no browser e devolve o resultado.
+
+O protocolo entre o serviço e a extensão está em [CONTRACT.md](CONTRACT.md).
+
+## Configuração avançada
+
+Variáveis de ambiente, no bloco `env` da configuração do cliente MCP:
+
+| variável | efeito |
+|---|---|
+| `SUITE_TIMESHEET_BASE` | outro endereço local, ex. `http://127.0.0.1:18770`; põe o mesmo nas Opções da extensão |
+| `SUITE_TIMESHEET_SEM_AUTOARRANQUE=1` | o `mcp.js` não arranca o serviço; corres tu `node serve.js [porta]` |
+
+Com o serviço gerido à mão, arranca-o **antes** de abrir a Folha de Horas, ou recarrega a página
+depois: a extensão só publica o contexto quando a página carrega ou muda de mês.
+
+As tools aceitam `timeout_s` até 290 s (útil em `resultado` com lotes grandes). Se o cliente
+cortar a chamada antes disso, aumenta o timeout do cliente MCP (no Claude Code, 60 s por defeito).
+
+## Atualizar
+
+As correções 1.x chegam ao reiniciar o cliente MCP (o `npx` volta a consultar o npm). Para uma
+versão principal nova, muda `@1` no comando. O serviço local fica a correr entre sessões; para
+ele pegar na versão nova, termina-o uma vez
+(`lsof -ti tcp:18765 | xargs kill`) e o `mcp.js` arranca o novo.
+
+## Limitações
+
+- Sem autenticação local: qualquer processo do teu utilizador consegue falar com o serviço.
+  Páginas web não conseguem. Ver [SECURITY.md](SECURITY.md).
+- Tudo em memória: reiniciar o serviço esquece propostas e contexto (recarrega a Folha de Horas).
+- Um mês de cada vez: o que está aberto na página.
+
+## Correr a partir de um clone
+
+```bash
+git clone https://github.com/williansaez/suite-timesheet-mcp.git
+cd suite-timesheet-mcp
+npm ci
+node --test
+```
+
+Para usar a cópia local num cliente, troca o comando `npx …` por
+`node /caminho/para/suite-timesheet-mcp/mcp.js`. Também dá para instalar diretamente de uma tag do
+GitHub, sem npm: `npx -y github:williansaez/suite-timesheet-mcp#v1.0.0` (precisa de `git`).
+
+## Licença
+
+Código disponível para consulta, **não open source**. Podes instalar e usar o pacote sem
+alterações, para uso pessoal ou interno da tua organização. Não é permitido alterá-lo,
+redistribuí-lo nem publicar cópias ou forks. Os termos completos (em inglês, com tradução para
+português) estão em [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,80 @@
+# Segurança
+
+Para quem precisa de decidir se pode correr este pacote numa máquina da empresa. Descreve o que
+ele faz, o que nunca faz, e como verificar cada afirmação.
+
+## Em uma frase
+
+Um processo local (`serve.js`) que guarda em memória uma fila de comandos entre o Claude e a
+extensão Suite Timesheet Importer, e um servidor MCP por stdio (`mcp.js`) que expõe seis tools ao
+Claude. Este pacote **nunca fala com o Suite**: quem lê e escreve no Suite é a extensão, dentro do
+browser, com a sessão do utilizador, e só depois de o utilizador clicar Aplicar no painel ou de
+aprovar a tool `aplicar` no cliente MCP (ver a tabela abaixo).
+
+## O que nunca faz (verificado pelo CI)
+
+| regra | como é garantida |
+|---|---|
+| Nunca contacta o Suite nem qualquer host externo | o código não contém nenhum URL além de `127.0.0.1` (guard no CI); o único `listen` é em `127.0.0.1`; o `mcp.js` só chama o `serve` local |
+| Nunca escreve no Suite, nem submete meses | não tem sessão, cookies nem endpoints do Suite; o endpoint de submissão não existe no código (guard no CI) |
+| Nunca provoca uma escrita sem confirmação humana | a tool `propor` só enfileira; a escrita só acontece com o clique em Aplicar no painel **ou** com a aprovação da tool `aplicar` no cliente MCP (ex.: Claude Code a pedir confirmação antes de correr a tool) — uma das duas é sempre exigida |
+| Nunca guarda dados em disco | fila, contexto e propostas vivem em memória; reiniciar o `serve` esquece tudo |
+| Nunca aceita pedidos de páginas web | recusa `Origin` que não seja `chrome-extension://`, `Host` que não seja `127.0.0.1`/`localhost`, e POST sem `application/json` |
+| Nunca contém dados reais | testes e exemplos só com projetos, ids e horas fictícios (guard de nomes de cliente no CI) |
+
+## Superfície de rede
+
+Só um socket: `127.0.0.1:18765` (porta configurável). Rotas:
+
+- `/bridge/*`: usadas pela extensão (long-poll, contexto da página, resultados).
+- `/mcp/*`: usadas pelo `mcp.js` na mesma máquina.
+- `/health`, `/timesheet`: contrato antigo do serviço local, só leitura. `/health` devolve a
+  identidade do serve (`nome`, `versao`) mais `ultimoMcp` (a hora do último pedido a `/mcp/*`,
+  ou `null`) e `ponte`; não expõe nada além disso — nem contexto, nem propostas.
+
+Corpo dos pedidos limitado a 1 MB. Ligações abortadas, URLs malformados e erros internos
+respondem com erro e nunca derrubam o processo.
+
+O `mcp.js` pode arrancar o `serve.js` (mesmo pacote, mesmo utilizador, só loopback) quando liga e
+não encontra nada a responder em `/health`; nunca arranca nem chama nenhum outro programa
+(`SUITE_TIMESHEET_SEM_AUTOARRANQUE=1` desliga isto).
+
+## Dados
+
+Em memória: o mês visível e a lista de projetos que a extensão publica, as propostas enviadas
+pelo Claude, e os resultados que a extensão devolve (prévia e resultado final). Resultados expiram
+ao fim de 1 h; comandos sem resposta expiram com `ERR_EXPIRADO`. Nada é registado além de uma
+linha por comando em `stderr` (tipo e mês, sem horas).
+
+## Dependências
+
+Uma, declarada e fixada em `package-lock.json`: `@modelcontextprotocol/sdk` (só importada por
+`mcp.js`). O `serve.js` usa apenas `node:http`. `npm audit` faz parte da verificação abaixo.
+
+## Limitações conhecidas
+
+- **Sem autenticação local.** Qualquer processo a correr com o teu utilizador consegue falar com
+  o `serve` (enfileirar um `propor`, ler o contexto). Páginas web não conseguem (ver acima). Um
+  `propor` malicioso ainda assim só chega ao Suite se clicares Aplicar no painel ou aprovares a
+  chamada da tool `aplicar` no cliente MCP.
+- **Sem TLS.** Loopback apenas; nada sai da máquina.
+- **Sem persistência.** Um reinício perde a fila; o MCP recebe `ERR_COMANDO_DESCONHECIDO` e repete.
+
+## Como a tua equipa pode verificar
+
+```bash
+npm ci
+node --test                       # 73 testes, sem rede além de loopback
+npm audit --omit=dev              # dependências conhecidas
+grep -rnoE "https?://[a-zA-Z0-9.-]+" --include='*.js' --exclude-dir=node_modules --exclude-dir=test .   # esperado: só 127.0.0.1
+grep -rniE "submitaction" --include='*.js' . --exclude-dir=node_modules | grep -v '/test/'      # esperado: vazio
+grep -rn "listen(" serve.js       # esperado: só 127.0.0.1
+```
+
+## Reportar um problema
+
+Encontraste uma forma de este pacote contactar algo fora da máquina, de aceitar pedidos de uma
+página web, ou de provocar uma escrita no Suite sem o clique em Aplicar nem a aprovação da tool
+`aplicar`? Abre um issue privado
+neste repositório com o rótulo `segurança` ou contacta o dono do repositório. Sem cookies, tokens
+nem dados reais no relatório.

package/lib/autoarranque.js

@@ -0,0 +1,90 @@
+// Auto-arranque do serve: o mcp.js chama isto antes de se ligar por stdio, para o utilizador
+// não ter de arrancar o `serve` à mão. Puro-ish: fetch, spawn e pausa são injetáveis (só
+// `spawnServeReal`, usado como valor por defeito, toca em node:child_process a sério).
+
+import { spawn as spawnReal } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const PORTA_POR_DEFEITO = 18765;
+
+function portaDe(base) {
+  try {
+    const porta = new URL(base).port;
+    return porta ? Number(porta) : PORTA_POR_DEFEITO;
+  } catch {
+    return PORTA_POR_DEFEITO;
+  }
+}
+
+// Só isto identifica um "serve" desta package: nome fixo devolvido por GET /health
+// (ver lib/rotas.js). Qualquer outra coisa na porta (outro programa, um proxy, etc.) não passa.
+function ehIdentidade(json) {
+  return Boolean(json) && typeof json === 'object' && json.nome === 'suite-timesheet-serve';
+}
+
+function pausaReal(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+// Arranca o serve.js real, desligado deste processo: detached (não morre com o mcp.js),
+// stdio 'ignore' (não herda nem escreve no stdio que o protocolo MCP usa) e unref() (não
+// impede o mcp.js de terminar enquanto o serve continua a correr).
+function spawnServeReal(porta) {
+  const caminhoServe = fileURLToPath(new URL('../serve.js', import.meta.url));
+  const filho = spawnReal(process.execPath, [caminhoServe, String(porta)], {
+    detached: true,
+    stdio: 'ignore',
+  });
+  filho.unref();
+  return filho;
+}
+
+// GET base/health, sem lançar: { ligou: false } se o fetch falhar (nada à escuta),
+// { ligou: true, status, json } caso contrário (json pode ser null se o corpo não for JSON).
+async function verHealth(base, fetchImpl) {
+  let resposta;
+  try {
+    resposta = await fetchImpl(`${base}/health`);
+  } catch {
+    return { ligou: false };
+  }
+  const json = await resposta.json().catch(() => null);
+  return { ligou: true, status: resposta.status, json };
+}
+
+/**
+ * Garante que há um `serve` desta package a responder em `base`. Nunca lança: devolve sempre
+ * { estado, detalhe }, com estado um de 'ja-corria' | 'arrancado' | 'porta-ocupada' | 'falhou'.
+ */
+export async function garantirServe({
+  base,
+  fetch: fetchImpl = globalThis.fetch,
+  spawn: spawnImpl,
+  pausa = pausaReal,
+  tentativas = 15,
+} = {}) {
+  const porta = portaDe(base);
+  const arrancar = spawnImpl ?? (() => spawnServeReal(porta));
+
+  const primeira = await verHealth(base, fetchImpl);
+
+  if (primeira.ligou) {
+    if (primeira.status === 200 && ehIdentidade(primeira.json)) {
+      return { estado: 'ja-corria', detalhe: `Já havia um serve a responder em ${base}.` };
+    }
+    // Responde, mas não é este serve: outro programa qualquer está nesta porta. Nunca arrancar
+    // o serve por cima disso.
+    return { estado: 'porta-ocupada', detalhe: `Na porta ${porta} responde outro programa.` };
+  }
+
+  // Nada à escuta: arrancar o serve e esperar que fique saudável.
+  arrancar();
+  for (let i = 0; i < tentativas; i += 1) {
+    await pausa(200);
+    const tentativa = await verHealth(base, fetchImpl);
+    if (tentativa.ligou && tentativa.status === 200 && ehIdentidade(tentativa.json)) {
+      return { estado: 'arrancado', detalhe: `Arranquei o serve em ${base}.` };
+    }
+  }
+  return { estado: 'falhou', detalhe: `Não consegui arrancar o serve em ${base} (tenta "node serve.js").` };
+}

package/lib/cliente.js

@@ -0,0 +1,30 @@
+// Cliente HTTP do serve, usado pelo mcp.js. fetch injetável para os testes.
+
+export function criarCliente({ base, fetch: fetchImpl = globalThis.fetch, comandoArranque = 'node serve.js' }) {
+  async function pedir(metodo, caminho, corpo) {
+    let resposta;
+    try {
+      resposta = await fetchImpl(`${base}${caminho}`, {
+        method: metodo,
+        headers: corpo ? { 'content-type': 'application/json' } : {},
+        body: corpo ? JSON.stringify(corpo) : undefined,
+      });
+    } catch (e) {
+      throw Object.assign(
+        new Error(`O serviço local não responde em ${base} (${e.message}). Arranca-o com: ${comandoArranque}`),
+        { code: 'ERR_SERVE_EM_BAIXO' },
+      );
+    }
+    const json = await resposta.json().catch(() => null);
+    if (!resposta.ok) {
+      const erro = json?.erro ?? { code: 'ERR_SERVE', message: `O serviço local devolveu HTTP ${resposta.status}.` };
+      throw Object.assign(new Error(erro.message), { code: erro.code });
+    }
+    return json;
+  }
+  return {
+    estado: () => pedir('GET', '/mcp/estado'),
+    comando: (corpo) => pedir('POST', '/mcp/comando', corpo),
+    resultado: (id, waitS, fase = 'final') => pedir('GET', `/mcp/comando/${encodeURIComponent(id)}?wait=${waitS}&fase=${fase}`),
+  };
+}

package/lib/contexto.js

@@ -0,0 +1,14 @@
+// Puro. O último contexto que a extensão publicou e a última proposta por mês.
+
+export function criarContexto({ agora = () => Date.now() } = {}) {
+  let atual = null;
+  const propostas = new Map();
+  const chave = (ano, mes) => `${ano}-${mes}`;
+  return {
+    guardar(ctx) { atual = { ...ctx, recebidoEm: agora() }; },
+    atual: () => atual,
+    mesVisivel: () => (atual ? { ano: atual.ano, mes: atual.mes } : null),
+    guardarProposta(ano, mes, linhas) { propostas.set(chave(ano, mes), linhas); },
+    proposta: (ano, mes) => propostas.get(chave(ano, mes)) ?? [],
+  };
+}