devvo-ops-mcp 0.1.0 → 0.1.1

package/README.md

@@ -2,97 +2,71 @@
 
 Servidor MCP local para integrar clientes como Cursor, Codex, Claude Desktop e outros agentes ao gerenciador de projetos Devvo Ops. A primeira tool disponível é `get_task_by_key`, que consulta uma task por uma key como `TASK-100`.
 
-```text
-AI Client
-   ↓ MCP stdio
-Devvo Ops MCP
-   ↓ HTTP(S)
-Devvo Ops API
-```
-
-## Arquitetura
-
-O MCP é um cliente externo da API, embora seu código esteja atualmente no mesmo repositório.
-
-> Mesmo estando no mesmo repositório, o MCP não deve importar services, repositories, entities, controllers, banco de dados ou outras implementações internas da API.
+## Comece em poucos minutos
 
-```text
-CORRETO
-
-MCP
- ↓ HTTP
-API
- ↓
-Services
-```
+Requer Node.js 20 ou superior. O pacote é executado via `npx`, então o usuário não precisa clonar este repositório para usar o MCP.
 
-```text
-INCORRETO
+1. Faça login uma vez:
 
-MCP
- ↓ import
-TaskService
+```bash
+npx devvo-ops-mcp login
 ```
 
-Essa separação permite publicar o pacote independentemente no NPM, reduz acoplamento, evita dependência da implementação interna, mantém autenticação e autorização na API e permite que ambos evoluam separadamente.
-
-## Estrutura
+2. Configure o servidor no seu cliente MCP.
+3. Reinicie o cliente, quando necessário, e peça por uma task:
 
 ```text
-src/
-├── api/       # transporte HTTP, cliente da API e mapeamento de respostas
-├── auth/      # gerenciamento de tokens e persistência da sessão
-├── cli/       # prompts interativos do CLI
-├── tools/     # tools MCP, sem conhecimento de autenticação
-└── index.ts   # comandos CLI e servidor MCP stdio
+Mostre a TASK-100.
+O que precisa ser feito na TASK-100?
+Leia a TASK-100 e me explique como você implementaria.
 ```
 
-## Desenvolvimento
+### Codex
 
-Requer Node.js 20 ou superior.
+Pelo CLI:
 
 ```bash
-cd mcp
-npm install
-npm run build
-npm test
+codex mcp add devvo-ops -- npx -y devvo-ops-mcp
 ```
 
-A URL da API é configurada por `DEVVO_OPS_API_URL`. O valor padrão para desenvolvimento local é `http://localhost:3334`.
+Ou edite `~/.codex/config.toml`:
 
-## Autenticação
-
-```bash
-npx devvo-ops-mcp login
+```toml
+[mcp_servers.devvo-ops]
+command = "npx"
+args = ["-y", "devvo-ops-mcp"]
 ```
 
-```text
-email + senha
- ↓
-API
- ↓
-refresh token
- ↓
-~/.devvo-ops-mcp/auth.json
-```
+Depois, abra o Codex e use `/mcp` para conferir se o servidor foi carregado.
 
-A senha nunca é persistida. O access token permanece somente na memória do processo; apenas o refresh token e, opcionalmente, o email são gravados. O MCP renova tokens automaticamente e salva o novo refresh token quando a API faz rotação.
+### Claude Desktop, Cursor e clientes compatíveis
 
-O arquivo `~/.devvo-ops-mcp/auth.json` é uma credencial sensível: deve permanecer fora do repositório, nunca deve ser commitado, enviado ou compartilhado, e é removido no logout. O pacote solicita permissões `0700` para o diretório e `0600` para o arquivo quando o sistema operacional oferece suporte.
+Adicione o mesmo bloco no arquivo de configuração MCP do seu cliente:
 
-Comandos disponíveis:
+- Claude Desktop: `claude_desktop_config.json`
+- Cursor: `.cursor/mcp.json`
+- Outros clientes compatíveis: arquivo de configuração MCP indicado pelo cliente
 
-```bash
-npx devvo-ops-mcp login
-npx devvo-ops-mcp status
-npx devvo-ops-mcp logout
+```json
+{
+  "mcpServers": {
+    "devvo-ops": {
+      "command": "npx",
+      "args": ["-y", "devvo-ops-mcp"]
+    }
+  }
+}
 ```
 
-Executar o pacote sem subcomando inicia o servidor MCP via `stdio`.
+Não coloque email, senha, access token ou refresh token na configuração do cliente. Essas credenciais são gerenciadas pelo comando `login`.
+
+## Variáveis de ambiente
 
-## Uso em um cliente MCP
+Por padrão, o MCP usa a API oficial do Devvo Ops: `https://devvo-ops-backend-791587092728.us-central1.run.app`.
 
-Faça login primeiro e adicione uma configuração equivalente à seguinte no cliente:
+Use `DEVVO_OPS_API_URL` apenas se precisar apontar para outro ambiente, como desenvolvimento local ou staging.
+
+Configuração MCP completa com `DEVVO_OPS_API_URL`:
 
 ```json
 {
@@ -101,55 +75,45 @@ Faça login primeiro e adicione uma configuração equivalente à seguinte no cl
       "command": "npx",
       "args": ["-y", "devvo-ops-mcp"],
       "env": {
-        "DEVVO_OPS_API_URL": "https://api.example.com"
+        "DEVVO_OPS_API_URL": "http://localhost:3334"
       }
     }
   }
 }
 ```
 
-Não coloque email, senha, access token ou refresh token nessa configuração.
+## Autenticação
 
-Exemplos de solicitações:
+```bash
+npx devvo-ops-mcp login
+```
 
 ```text
-Mostre a TASK-100.
-O que precisa ser feito na TASK-100?
-Leia a TASK-100 e me explique como você implementaria.
+email + senha
+ ↓
+API
+ ↓
+refresh token
+ ↓
+~/.devvo-ops-mcp/auth.json
 ```
 
-## MCP Inspector
+A senha nunca é persistida. O access token permanece somente na memória do processo; apenas o refresh token e, opcionalmente, o email são gravados. O MCP renova tokens automaticamente e salva o novo refresh token quando a API faz rotação.
 
-Depois do build, teste o transporte e a tool com:
+O arquivo `~/.devvo-ops-mcp/auth.json` é uma credencial sensível: deve permanecer fora do repositório, nunca deve ser commitado, enviado ou compartilhado, e é removido no logout. O pacote solicita permissões `0700` para o diretório e `0600` para o arquivo quando o sistema operacional oferece suporte.
 
-```bash
-npx @modelcontextprotocol/inspector node dist/index.js
-```
+## Comandos
 
-Também é possível inspecionar diretamente o código TypeScript durante o desenvolvimento:
+Use estes comandos para gerenciar a sessão local:
 
 ```bash
-npx @modelcontextprotocol/inspector npx tsx src/index.ts
-```
-
-## Boas práticas para novas tools
-
-Toda nova tool deve manter o fluxo:
-
-```text
-Tool
- ↓
-ApiClient
- ↓
-API
+npx devvo-ops-mcp login
+npx devvo-ops-mcp status
+npx devvo-ops-mcp logout
 ```
 
-Nunca use:
+Para iniciar o servidor MCP manualmente via `stdio`:
 
-```text
-Tool
- ↓
-Service interno
+```bash
+npx -y devvo-ops-mcp
 ```
-
-As tools devem ter responsabilidade pequena e schemas claros, não conhecer autenticação, não acessar banco diretamente, não duplicar regras de negócio da API, retornar apenas contexto útil ao LLM e utilizar o `ApiClient` compartilhado.

package/dist/config.js

@@ -1,4 +1,4 @@
-const DEFAULT_API_URL = 'http://localhost:3334';
+const DEFAULT_API_URL = 'https://devvo-ops-backend-791587092728.us-central1.run.app';
 export function getApiBaseUrl(environment = process.env) {
     const configuredUrl = environment.DEVVO_OPS_API_URL?.trim() || DEFAULT_API_URL;
     try {

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEhD,MAAM,UAAU,aAAa,CAAC,cAAiC,OAAO,CAAC,GAAG;IACxE,MAAM,aAAa,GAAG,WAAW,CAAC,iBAAiB,EAAE,IAAI,EAAE,IAAI,eAAe,CAAC;IAE/E,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;QACnC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;AACH,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,eAAe,GAAG,4DAA4D,CAAC;AAErF,MAAM,UAAU,aAAa,CAAC,cAAiC,OAAO,CAAC,GAAG;IACxE,MAAM,aAAa,GAAG,WAAW,CAAC,iBAAiB,EAAE,IAAI,EAAE,IAAI,eAAe,CAAC;IAE/E,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;QACnC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devvo-ops-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Servidor MCP local para consultar o Devvo Ops.",
   "type": "module",
   "license": "UNLICENSED",