@dewtech/dare-cli 3.3.0 → 3.5.0

package/templates/ide/cursor/.cursor/rules/skill-mcp-server.mdc

@@ -1,367 +1,367 @@
----
-description: Padrões DARE para servidores MCP (Model Context Protocol da Anthropic) em TypeScript ou Python. Tools, resources, prompts; transports stdio/SSE/HTTP; validação Zod/Pydantic; autorização por tool; observabilidade; testes; publicação.
-globs: **/*.ts,**/*.py,package.json,pyproject.toml,claude_desktop_config.json
-alwaysApply: false
----
-
-# Skill: MCP Server DARE
-
-Você é um especialista em servidores MCP (Model Context Protocol). Esta skill garante MCP servers **bem estruturados, seguros, testáveis e publicáveis**, expondo tools/resources/prompts via stdio, SSE ou HTTP.
-
-## O que é MCP em 30 segundos
-
-Protocolo aberto da Anthropic para conectar agentes (Claude Code, Claude Desktop, Cursor, etc.) a fontes de dados e ações externas. Server expõe:
-
-- **Tools** — funções chamáveis pelo agente
-- **Resources** — dados leitáveis (URI + mimeType)
-- **Prompts** — templates parametrizados
-
-Transports:
-
-| Transport | Quando usar |
-|---|---|
-| **stdio** | Server local, agente spawnea processo |
-| **SSE** | Server remoto, streaming bidirectional |
-| **HTTP** | Server remoto stateless |
-
----
-
-## Stack canônica
-
-### TypeScript
-
-- Node 20+ + TS 5.5+
-- `@modelcontextprotocol/sdk` SDK oficial
-- Zod para schemas
-- vitest
-
-### Python
-
-- Python 3.11+
-- `mcp` (SDK oficial, `pip install mcp`)
-- Pydantic v2
-- pytest + pytest-asyncio
-
----
-
-## Estrutura
-
-```
-mcp-meu-server/
-├── package.json   (ou pyproject.toml)
-├── src/
-│   ├── index.ts             ← stdio entrypoint
-│   ├── server.ts            ← criação do MCP Server
-│   ├── tools/
-│   │   ├── create_issue.ts
-│   │   └── search_issues.ts
-│   ├── resources/
-│   ├── prompts/
-│   ├── schemas/
-│   └── lib/                 ← clientes externos
-└── tests/
-```
-
----
-
-## Exemplo TypeScript (stdio)
-
-```typescript
-// src/index.ts
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { z } from 'zod';
-
-const CreateIssueInput = z.object({
-  title: z.string().min(1).max(255),
-  description: z.string().optional(),
-  priority: z.enum(['low', 'medium', 'high']).default('medium'),
-  team_id: z.string().uuid(),
-});
-
-const server = new Server(
-  { name: 'meu-server', version: '1.0.0' },
-  { capabilities: { tools: {}, resources: {}, prompts: {} } }
-);
-
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: [{
-    name: 'create_issue',
-    description: 'Create a new issue in Linear with the given title, description, and priority',
-    inputSchema: CreateIssueInput.shape,
-  }],
-}));
-
-server.setRequestHandler(CallToolRequestSchema, async (req) => {
-  if (req.params.name !== 'create_issue') throw new Error('unknown tool');
-  const input = CreateIssueInput.parse(req.params.arguments);
-  const result = await linearClient.createIssue(input);
-  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-});
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-```
-
----
-
-## Exemplo Python (stdio)
-
-```python
-import asyncio
-from mcp.server import Server
-from mcp.server.stdio import stdio_server
-from mcp.types import Tool, TextContent
-from pydantic import BaseModel, Field
-
-app = Server("meu-server")
-
-class CreateIssueInput(BaseModel):
-    title: str = Field(min_length=1, max_length=255)
-    description: str | None = None
-    priority: str = Field(default="medium", pattern="^(low|medium|high)$")
-    team_id: str
-
-@app.list_tools()
-async def list_tools() -> list[Tool]:
-    return [
-        Tool(
-            name="create_issue",
-            description="Create a new issue in Linear",
-            inputSchema=CreateIssueInput.model_json_schema(),
-        )
-    ]
-
-@app.call_tool()
-async def call_tool(name: str, arguments: dict) -> list[TextContent]:
-    if name != "create_issue":
-        raise ValueError(f"unknown tool: {name}")
-    input_data = CreateIssueInput.model_validate(arguments)
-    result = await linear_client.create_issue(input_data)
-    return [TextContent(type="text", text=result.model_dump_json())]
-
-async def main():
-    async with stdio_server() as (read, write):
-        await app.run(read, write, app.create_initialization_options())
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
----
-
-## Resources
-
-```typescript
-server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-  resources: [{
-    uri: 'linear://schema',
-    name: 'Linear Issue Schema',
-    mimeType: 'application/json',
-  }],
-}));
-
-server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
-  if (req.params.uri === 'linear://schema') {
-    return {
-      contents: [{
-        uri: req.params.uri,
-        mimeType: 'application/json',
-        text: JSON.stringify(schema),
-      }],
-    };
-  }
-  throw new Error('unknown resource');
-});
-```
-
----
-
-## Prompts
-
-```typescript
-server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-  prompts: [{
-    name: 'triage_issue',
-    description: 'Triage an issue and assign priority',
-    arguments: [
-      { name: 'description', description: 'Issue description', required: true },
-    ],
-  }],
-}));
-
-server.setRequestHandler(GetPromptRequestSchema, async (req) => ({
-  messages: [{
-    role: 'user',
-    content: {
-      type: 'text',
-      text: `Triage this issue and suggest a priority:\n\n${req.params.arguments?.description}`,
-    },
-  }],
-}));
-```
-
----
-
-## Autorização por tool
-
-```typescript
-// Tool destrutiva exige confirm explícito
-if (input.confirm !== 'YES_I_AM_SURE') {
-  throw new Error('this tool requires confirmation');
-}
-
-// Tool admin
-if (!callerHasRole('admin')) {
-  throw new Error('admin only');
-}
-```
-
----
-
-## Observabilidade
-
-**Crítico em stdio:** o protocolo MCP usa **stdout**. Logs SEMPRE em stderr.
-
-```typescript
-console.error(JSON.stringify({
-  ts: new Date().toISOString(),
-  tool: req.params.name,
-  duration_ms: Date.now() - start,
-  success: true,
-  // sem args (PII), sem result completo (pode ter PII)
-}));
-```
-
----
-
-## Testes
-
-```typescript
-// Unit
-import { test, expect } from 'vitest';
-test('valida input correto', () => {
-  const valid = CreateIssueInput.parse({
-    title: 'Test',
-    team_id: '550e8400-e29b-41d4-a716-446655440000',
-  });
-  expect(valid.priority).toBe('medium');
-});
-
-test('rejeita team_id inválido', () => {
-  expect(() => CreateIssueInput.parse({
-    title: 'Test',
-    team_id: 'not-uuid',
-  })).toThrow();
-});
-
-// E2E com client MCP
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-
-const transport = new StdioClientTransport({ command: 'node', args: ['dist/index.js'] });
-const client = new Client({ name: 'test', version: '0.0.0' }, { capabilities: {} });
-await client.connect(transport);
-const tools = await client.listTools();
-expect(tools.tools.map(t => t.name)).toContain('create_issue');
-```
-
----
-
-## Antipatterns
-
-| AP | Antipattern | Por quê |
-|---|---|---|
-| AP-01 | Logs no stdout (stdio) | Quebra o protocolo MCP |
-| AP-02 | Tool sem schema de input | Cliente passa lixo |
-| AP-03 | Sem validação no server | Confia no client (errado) |
-| AP-04 | Tool destrutiva sem confirm | Agente apaga sem querer |
-| AP-05 | Secrets em código | Use env vars |
-| AP-06 | Tool name vago (`do_thing`) | Agente não sabe quando usar |
-| AP-07 | Description curto/vago | Agente erra na escolha |
-| AP-08 | Resource sem mimeType | Cliente não parseia |
-| AP-09 | Tool sem error handling | Erro vira crash em vez de mensagem |
-
----
-
-## Publicação
-
-### Pré-requisitos
-
-- `README.md` com:
-  - Instalação e configuração
-  - Lista de tools/resources/prompts
-  - Variáveis de ambiente
-  - Exemplo `claude_desktop_config.json`
-- `LICENSE` (MIT recomendado)
-- `package.json`/`pyproject.toml` versionado
-
-### Distribuição
-
-| Stack | Comando |
-|---|---|
-| TypeScript | `npm publish` |
-| Python | `python -m build && twine upload dist/*` |
-| Docker (SSE/HTTP) | multi-stage build + push para registry |
-
-### Config no Claude Desktop
-
-```json
-{
-  "mcpServers": {
-    "meu-server": {
-      "command": "node",
-      "args": ["/abs/path/to/dist/index.js"],
-      "env": {
-        "LINEAR_API_KEY": "lin_api_..."
-      }
-    }
-  }
-}
-```
-
----
-
-## Aplicação por fase DARE
-
-### Design
-- Definir capabilities (tools, resources, prompts) com nomes e descrições claras
-- Decidir transport (stdio/SSE/HTTP)
-- Listar variáveis de ambiente necessárias
-
-### Blueprint
-- Estrutura de pastas
-- Schemas Zod/Pydantic por tool
-- Estratégia de autorização
-
-### Tasks
-- Por tool: 1 task (schema + handler + teste)
-- Task de configuração transport + entrypoint
-- Task de publicação (README + LICENSE + CI release)
-
-### Execute
-- Ralph Loop:
-  ```bash
-  npm run lint && npm test && npm run build
-  # ou
-  ruff check . && mypy . && pytest
-  ```
-
----
-
-## Checklist final
-
-- [ ] Transport escolhido (stdio/SSE/HTTP) com justificativa
-- [ ] Cada tool tem name descritivo, description completa, input schema
-- [ ] Validação Zod/Pydantic no início de cada handler
-- [ ] Tools destrutivas exigem `confirm`
-- [ ] Logs em stderr (stdio) com JSON estruturado
-- [ ] Secrets via env vars, nunca em código
-- [ ] Testes unit + E2E com client MCP
-- [ ] README + LICENSE MIT
-- [ ] Publicação configurada (npm/PyPI/Docker)
-
----
-
-Skill licenciada MIT — parte do DARE Method v3.
+---
+description: Padrões DARE para servidores MCP (Model Context Protocol da Anthropic) em TypeScript ou Python. Tools, resources, prompts; transports stdio/SSE/HTTP; validação Zod/Pydantic; autorização por tool; observabilidade; testes; publicação.
+globs: **/*.ts,**/*.py,package.json,pyproject.toml,claude_desktop_config.json
+alwaysApply: false
+---
+
+# Skill: MCP Server DARE
+
+Você é um especialista em servidores MCP (Model Context Protocol). Esta skill garante MCP servers **bem estruturados, seguros, testáveis e publicáveis**, expondo tools/resources/prompts via stdio, SSE ou HTTP.
+
+## O que é MCP em 30 segundos
+
+Protocolo aberto da Anthropic para conectar agentes (Claude Code, Claude Desktop, Cursor, etc.) a fontes de dados e ações externas. Server expõe:
+
+- **Tools** — funções chamáveis pelo agente
+- **Resources** — dados leitáveis (URI + mimeType)
+- **Prompts** — templates parametrizados
+
+Transports:
+
+| Transport | Quando usar |
+|---|---|
+| **stdio** | Server local, agente spawnea processo |
+| **SSE** | Server remoto, streaming bidirectional |
+| **HTTP** | Server remoto stateless |
+
+---
+
+## Stack canônica
+
+### TypeScript
+
+- Node 20+ + TS 5.5+
+- `@modelcontextprotocol/sdk` SDK oficial
+- Zod para schemas
+- vitest
+
+### Python
+
+- Python 3.11+
+- `mcp` (SDK oficial, `pip install mcp`)
+- Pydantic v2
+- pytest + pytest-asyncio
+
+---
+
+## Estrutura
+
+```
+mcp-meu-server/
+├── package.json   (ou pyproject.toml)
+├── src/
+│   ├── index.ts             ← stdio entrypoint
+│   ├── server.ts            ← criação do MCP Server
+│   ├── tools/
+│   │   ├── create_issue.ts
+│   │   └── search_issues.ts
+│   ├── resources/
+│   ├── prompts/
+│   ├── schemas/
+│   └── lib/                 ← clientes externos
+└── tests/
+```
+
+---
+
+## Exemplo TypeScript (stdio)
+
+```typescript
+// src/index.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+const CreateIssueInput = z.object({
+  title: z.string().min(1).max(255),
+  description: z.string().optional(),
+  priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  team_id: z.string().uuid(),
+});
+
+const server = new Server(
+  { name: 'meu-server', version: '1.0.0' },
+  { capabilities: { tools: {}, resources: {}, prompts: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: 'create_issue',
+    description: 'Create a new issue in Linear with the given title, description, and priority',
+    inputSchema: CreateIssueInput.shape,
+  }],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  if (req.params.name !== 'create_issue') throw new Error('unknown tool');
+  const input = CreateIssueInput.parse(req.params.arguments);
+  const result = await linearClient.createIssue(input);
+  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+---
+
+## Exemplo Python (stdio)
+
+```python
+import asyncio
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+from pydantic import BaseModel, Field
+
+app = Server("meu-server")
+
+class CreateIssueInput(BaseModel):
+    title: str = Field(min_length=1, max_length=255)
+    description: str | None = None
+    priority: str = Field(default="medium", pattern="^(low|medium|high)$")
+    team_id: str
+
+@app.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="create_issue",
+            description="Create a new issue in Linear",
+            inputSchema=CreateIssueInput.model_json_schema(),
+        )
+    ]
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name != "create_issue":
+        raise ValueError(f"unknown tool: {name}")
+    input_data = CreateIssueInput.model_validate(arguments)
+    result = await linear_client.create_issue(input_data)
+    return [TextContent(type="text", text=result.model_dump_json())]
+
+async def main():
+    async with stdio_server() as (read, write):
+        await app.run(read, write, app.create_initialization_options())
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Resources
+
+```typescript
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [{
+    uri: 'linear://schema',
+    name: 'Linear Issue Schema',
+    mimeType: 'application/json',
+  }],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  if (req.params.uri === 'linear://schema') {
+    return {
+      contents: [{
+        uri: req.params.uri,
+        mimeType: 'application/json',
+        text: JSON.stringify(schema),
+      }],
+    };
+  }
+  throw new Error('unknown resource');
+});
+```
+
+---
+
+## Prompts
+
+```typescript
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: [{
+    name: 'triage_issue',
+    description: 'Triage an issue and assign priority',
+    arguments: [
+      { name: 'description', description: 'Issue description', required: true },
+    ],
+  }],
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (req) => ({
+  messages: [{
+    role: 'user',
+    content: {
+      type: 'text',
+      text: `Triage this issue and suggest a priority:\n\n${req.params.arguments?.description}`,
+    },
+  }],
+}));
+```
+
+---
+
+## Autorização por tool
+
+```typescript
+// Tool destrutiva exige confirm explícito
+if (input.confirm !== 'YES_I_AM_SURE') {
+  throw new Error('this tool requires confirmation');
+}
+
+// Tool admin
+if (!callerHasRole('admin')) {
+  throw new Error('admin only');
+}
+```
+
+---
+
+## Observabilidade
+
+**Crítico em stdio:** o protocolo MCP usa **stdout**. Logs SEMPRE em stderr.
+
+```typescript
+console.error(JSON.stringify({
+  ts: new Date().toISOString(),
+  tool: req.params.name,
+  duration_ms: Date.now() - start,
+  success: true,
+  // sem args (PII), sem result completo (pode ter PII)
+}));
+```
+
+---
+
+## Testes
+
+```typescript
+// Unit
+import { test, expect } from 'vitest';
+test('valida input correto', () => {
+  const valid = CreateIssueInput.parse({
+    title: 'Test',
+    team_id: '550e8400-e29b-41d4-a716-446655440000',
+  });
+  expect(valid.priority).toBe('medium');
+});
+
+test('rejeita team_id inválido', () => {
+  expect(() => CreateIssueInput.parse({
+    title: 'Test',
+    team_id: 'not-uuid',
+  })).toThrow();
+});
+
+// E2E com client MCP
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const transport = new StdioClientTransport({ command: 'node', args: ['dist/index.js'] });
+const client = new Client({ name: 'test', version: '0.0.0' }, { capabilities: {} });
+await client.connect(transport);
+const tools = await client.listTools();
+expect(tools.tools.map(t => t.name)).toContain('create_issue');
+```
+
+---
+
+## Antipatterns
+
+| AP | Antipattern | Por quê |
+|---|---|---|
+| AP-01 | Logs no stdout (stdio) | Quebra o protocolo MCP |
+| AP-02 | Tool sem schema de input | Cliente passa lixo |
+| AP-03 | Sem validação no server | Confia no client (errado) |
+| AP-04 | Tool destrutiva sem confirm | Agente apaga sem querer |
+| AP-05 | Secrets em código | Use env vars |
+| AP-06 | Tool name vago (`do_thing`) | Agente não sabe quando usar |
+| AP-07 | Description curto/vago | Agente erra na escolha |
+| AP-08 | Resource sem mimeType | Cliente não parseia |
+| AP-09 | Tool sem error handling | Erro vira crash em vez de mensagem |
+
+---
+
+## Publicação
+
+### Pré-requisitos
+
+- `README.md` com:
+  - Instalação e configuração
+  - Lista de tools/resources/prompts
+  - Variáveis de ambiente
+  - Exemplo `claude_desktop_config.json`
+- `LICENSE` (MIT recomendado)
+- `package.json`/`pyproject.toml` versionado
+
+### Distribuição
+
+| Stack | Comando |
+|---|---|
+| TypeScript | `npm publish` |
+| Python | `python -m build && twine upload dist/*` |
+| Docker (SSE/HTTP) | multi-stage build + push para registry |
+
+### Config no Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "meu-server": {
+      "command": "node",
+      "args": ["/abs/path/to/dist/index.js"],
+      "env": {
+        "LINEAR_API_KEY": "lin_api_..."
+      }
+    }
+  }
+}
+```
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Definir capabilities (tools, resources, prompts) com nomes e descrições claras
+- Decidir transport (stdio/SSE/HTTP)
+- Listar variáveis de ambiente necessárias
+
+### Blueprint
+- Estrutura de pastas
+- Schemas Zod/Pydantic por tool
+- Estratégia de autorização
+
+### Tasks
+- Por tool: 1 task (schema + handler + teste)
+- Task de configuração transport + entrypoint
+- Task de publicação (README + LICENSE + CI release)
+
+### Execute
+- Ralph Loop:
+  ```bash
+  npm run lint && npm test && npm run build
+  # ou
+  ruff check . && mypy . && pytest
+  ```
+
+---
+
+## Checklist final
+
+- [ ] Transport escolhido (stdio/SSE/HTTP) com justificativa
+- [ ] Cada tool tem name descritivo, description completa, input schema
+- [ ] Validação Zod/Pydantic no início de cada handler
+- [ ] Tools destrutivas exigem `confirm`
+- [ ] Logs em stderr (stdio) com JSON estruturado
+- [ ] Secrets via env vars, nunca em código
+- [ ] Testes unit + E2E com client MCP
+- [ ] README + LICENSE MIT
+- [ ] Publicação configurada (npm/PyPI/Docker)
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.