@luanpdd/kit-mcp 1.28.0 → 1.30.0

package/kit/skills/supabase-edge-functions-mcp-server/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: supabase-edge-functions-mcp-server
+description: Use ao construir MCP server (Model Context Protocol) em Supabase Edge Functions com `mcp-lite` — scaffolding via `npm create mcp-lite@latest` template "Supabase Edge Functions (MCP server)", pattern dois apps Hono (root mounta em /<function-name>, inner handle /mcp), deno.json com imports `mcp-lite`/`hono`/`zod`, `verify_jwt=false` no template + auth no nível MCP, deploy a `https://<ref>.supabase.co/functions/v1/mcp-server/mcp` exposed para Claude/Cursor.
+---
+
+# Supabase — Edge Functions como MCP Server (`mcp-lite`) · 2026
+
+## Quando usar
+
+Carrega quando:
+
+- "criar MCP server", "Model Context Protocol server"
+- "mcp-lite supabase", "Claude tool customizado"
+- "expor Supabase como tool para LLM", "Cursor MCP edge function"
+- "MCP authentication", "StreamableHttpTransport mcp"
+
+> Pré-requisito: [`supabase-edge-functions`](../supabase-edge-functions/SKILL.md) (Deno + config.toml).
+> Complemento: [`supabase-edge-functions-auth`](../supabase-edge-functions-auth/SKILL.md) (autenticação em MCP via withSupabase).
+
+## Por que MCP em Edge Function
+
+| Vantagem | Detalhe |
+|---|---|
+| **Zero cold starts efetivos** | Edge runtime fica warm; baixa latência |
+| **Distribuição global** | Deploy 1x, executa próximo do user |
+| **Acesso direto Postgres** | `ctx.supabaseAdmin` queries sem hop adicional |
+| **Footprint mínimo** | `mcp-lite` é zero-deps TypeScript |
+| **Auth Supabase integrada** | RLS / Custom Claims / RBAC reusados |
+
+## Scaffolding canônico
+
+```bash
+npm create mcp-lite@latest
+# selecionar: "Supabase Edge Functions (MCP server)"
+cd my-mcp-server
+```
+
+Gera:
+
+```
+my-mcp-server/
+├── supabase/
+│   ├── config.toml                  # minimal — só edge runtime
+│   └── functions/
+│       └── mcp-server/
+│           ├── index.ts             # implementação
+│           └── deno.json
+├── package.json
+└── tsconfig.json
+```
+
+### `config.toml` mínimo (template)
+
+```toml
+project_id = "starter-mcp-supabase"
+
+[api]
+enabled = true
+port = 54321
+
+[edge_runtime]
+enabled = true
+policy = "per_worker"
+deno_version = 2
+```
+
+Sem DB / Storage / Studio — só Edge Functions runtime. Adicionar conforme necessidade.
+
+### `deno.json` per-function
+
+```json
+{
+  "compilerOptions": {
+    "lib": ["deno.window", "deno.ns"],
+    "strict": true
+  },
+  "imports": {
+    "hono": "npm:hono@^4.6.14",
+    "mcp-lite": "npm:mcp-lite@0.8.2",
+    "zod": "npm:zod@^4.1.12"
+  }
+}
+```
+
+## Pattern canônico — dois apps Hono
+
+```ts
+// supabase/functions/mcp-server/index.ts
+import { Hono } from 'hono'
+import { McpServer, StreamableHttpTransport } from 'mcp-lite'
+import { z } from 'zod'
+
+// PT-BR: instância MCP
+const mcp = new McpServer({
+  name: 'starter-mcp-supabase-server',
+  version: '1.0.0',
+  schemaAdapter: (schema) => z.toJSONSchema(schema as z.ZodType),
+})
+
+// PT-BR: tool exemplo — sum
+mcp.tool('sum', {
+  description: 'Adds two numbers together',
+  inputSchema: z.object({ a: z.number(), b: z.number() }),
+  handler: (args: { a: number; b: number }) => ({
+    content: [{ type: 'text', text: String(args.a + args.b) }],
+  }),
+})
+
+// PT-BR: bind a HTTP transport (Streamable HTTP)
+const transport = new StreamableHttpTransport()
+const httpHandler = transport.bind(mcp)
+
+// PT-BR: Supabase roteia tudo para /<function-name>/* → precisa de 2 apps
+const app = new Hono()
+const mcpApp = new Hono()
+
+mcpApp.get('/', (c) =>
+  c.json({
+    message: 'MCP Server on Supabase Edge Functions',
+    endpoints: { mcp: '/mcp', health: '/health' },
+  }),
+)
+
+mcpApp.all('/mcp', async (c) => {
+  // PT-BR: delega para mcp-lite httpHandler
+  return await httpHandler(c.req.raw)
+})
+
+mcpApp.get('/health', (c) => c.json({ ok: true }))
+
+// PT-BR: mount com o NOME da função — Supabase prefixa URL com /functions/v1/<name>
+app.route('/mcp-server', mcpApp)
+
+Deno.serve(app.fetch)
+```
+
+**Pegadinha-chave:** Supabase Edge roteia `https://<ref>.supabase.co/functions/v1/mcp-server/*` para sua função. Por isso o outer `app.route('/mcp-server', mcpApp)`. Sem isso, requests retornam 404.
+
+## Desenvolvimento local
+
+```bash
+# 1. levantar local
+supabase start
+
+# 2. servir função (no-verify-jwt durante dev — produção tem auth no MCP layer)
+supabase functions serve --no-verify-jwt mcp-server
+```
+
+Endpoint local: `http://localhost:54321/functions/v1/mcp-server/mcp`
+
+### Testar com Claude Code
+
+```bash
+claude mcp add my-mcp -t http http://localhost:54321/functions/v1/mcp-server/mcp
+```
+
+### Testar com MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+Adicionar a URL acima na UI.
+
+## Adicionar tools que tocam Supabase
+
+```ts
+import { createClient } from 'npm:@supabase/supabase-js@2.95.0'
+
+const SECRET = JSON.parse(Deno.env.get('SUPABASE_SECRET_KEYS')!)
+const supabase = createClient(Deno.env.get('SUPABASE_URL')!, SECRET['default'])
+
+mcp.tool('search_orders', {
+  description: 'Search orders by customer',
+  inputSchema: z.object({
+    customer_id: z.string(),
+    limit: z.number().min(1).max(50).default(10),
+  }),
+  handler: async ({ customer_id, limit }) => {
+    const { data, error } = await supabase
+      .from('orders')
+      .select('id, total, created_at')
+      .eq('customer_id', customer_id)
+      .limit(limit)
+    if (error) {
+      return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+  },
+})
+```
+
+## Deploy produção
+
+```bash
+supabase functions deploy --no-verify-jwt mcp-server
+```
+
+URL final: `https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp`
+
+## Autenticação MCP em produção
+
+Template usa `--no-verify-jwt`. Para produção, implemente auth no nível MCP seguindo [MCP Authorization spec](https://modelcontextprotocol.io/specification/draft/basic/authorization) — não no nível plataforma Supabase.
+
+### Pattern: auth via header customizado + validação no handler
+
+```ts
+mcpApp.all('/mcp', async (c) => {
+  // PT-BR: token MCP — pode ser API key custom ou JWT do user
+  const mcpToken = c.req.header('x-mcp-token')
+  if (!mcpToken || !await isValidMcpToken(mcpToken)) {
+    return c.json({ error: 'unauthorized' }, 401)
+  }
+  return await httpHandler(c.req.raw)
+})
+```
+
+### Pattern: bridge para Supabase Auth (user-scoped tools)
+
+```ts
+import { withSupabase } from 'npm:@supabase/server@1'
+
+mcpApp.all('/mcp', async (c) => {
+  // PT-BR: passar JWT do user via header x-supabase-jwt; tool exec usa ctx.supabase
+  const userJwt = c.req.header('x-supabase-jwt')
+  if (userJwt) {
+    // delegate to withSupabase wrapper para validar + scope client
+    return await withSupabase({ auth: 'user' }, async (req, ctx) => {
+      // anexar ctx.supabase ao mcp context para tools usarem RLS-aware client
+      (mcp as any).context = { supabase: ctx.supabase }
+      return await httpHandler(req)
+    })(c.req.raw)
+  }
+  return c.json({ error: 'jwt required' }, 401)
+})
+```
+
+## Best practices segurança
+
+- **Não exponha dados sensíveis** sem auth — tools `search_*` em prod sempre RLS-aware (`ctx.supabase` scoped)
+- **Valide inputs** — Zod schemas obrigatórios em cada tool
+- **Limite escopo** — só exponha tools necessárias
+- **Monitor uso** — `four-golden-signals` instrumentation no mcpApp `/mcp` handler
+- **Rate limit** — saturated MCP server abusa de DB; usar Supavisor pool config
+
+## Anti-patterns
+
+### AM1 — Esquecer `app.route('/<function-name>', mcpApp)`
+Single Hono app sem mount → 404 em prod. Supabase prefixa URL com nome da função.
+
+### AM2 — Tool sem `inputSchema` Zod
+Sem schema, MCP cliente envia qualquer formato. Crashes silenciosos.
+
+### AM3 — `service_role` em tool exposta sem auth
+`ctx.supabaseAdmin` bypassa RLS. MCP tool com admin client + sem auth = vazamento total. Use `'user'` mode.
+
+### AM4 — JWT em query param (URL log leak)
+`?jwt=...` é logado por proxies. Sempre header `x-mcp-token` ou `Authorization`.
+
+### AM5 — Tool retornando dados crus de query sem filtro
+LLM amplifica payload sensível. Limit + select específico (`select('id, name')`) — nunca `select('*')`.
+
+## Cross-suite handoffs
+
+| De | Para | Quando |
+|---|---|---|
+| Este skill | [`supabase-edge-functions-auth`](../supabase-edge-functions-auth/SKILL.md) | Adicionar `withSupabase` no MCP handler |
+| Este skill | [`supabase-edge-functions-limits`](../supabase-edge-functions-limits/SKILL.md) | Rate limit + idempotency em tools de write |
+| Este skill | [`four-golden-signals`](../four-golden-signals/SKILL.md) | Instrumentar `/mcp` handler |
+| Este skill | [`supabase-pgvector-rag`](../supabase-pgvector-rag/SKILL.md) | Tool `semantic_search` com embeddings |
+| Este skill | [`supabase-custom-claims-rbac`](../supabase-custom-claims-rbac/SKILL.md) | Tools com permission gate via `authorize()` |
+
+## Ver também
+
+- [`supabase-edge-functions`](../supabase-edge-functions/SKILL.md) — base
+- [`supabase-edge-functions-auth`](../supabase-edge-functions-auth/SKILL.md) — withSupabase
+- [`supabase-edge-functions-limits`](../supabase-edge-functions-limits/SKILL.md) — rate limit
+- [`supabase-edge-runtime-builtins`](../supabase-edge-runtime-builtins/SKILL.md) — Supabase.ai em tool
+- [`legacy-api-only-applications`](../legacy-api-only-applications/SKILL.md) — adapter pattern

package/kit/skills/supabase-edge-functions-testing/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: supabase-edge-functions-testing
+description: Use ao testar/debugar Edge Functions Supabase localmente — `deno test --allow-all` com `Deno.test`, folder structure `supabase/functions/tests/<fn>-test.ts`, `supabase start` + `supabase functions serve --env-file`, Chrome DevTools via `--inspect-mode brk` na porta 8083, `per_worker` policy para WebSocket/background, charset .env local, characterization tests para Edge Functions legadas.
+---
+
+# Supabase — Edge Functions Testing & Local Debug · 2026
+
+## Quando usar
+
+Carrega quando:
+
+- "testar Edge Function", "Deno test supabase function"
+- "supabase functions serve", "debug Edge Function", "Chrome DevTools deno"
+- "Edge Function não reload local", "per_worker policy"
+- "characterization test edge function", "snapshot golden output"
+
+> Pré-requisito: [`supabase-edge-functions`](../supabase-edge-functions/SKILL.md) (base Deno + env vars).
+> Complemento legacy: [`legacy-characterization-tests`](../legacy-characterization-tests/SKILL.md) — quando refatorar Edge Function sem testes.
+> Pattern API-only: [`legacy-api-only-applications`](../legacy-api-only-applications/SKILL.md) — adapter + fake provider para testes determinísticos.
+
+## Folder structure canônica
+
+```
+supabase/
+├── config.toml
+└── functions/
+    ├── _shared/
+    │   ├── supabase-admin.ts
+    │   └── cors.ts                       # ou import direto do SDK
+    ├── orders/
+    │   ├── index.ts
+    │   └── deno.json
+    ├── shipments/
+    │   ├── index.ts
+    │   └── deno.json
+    └── tests/                            # ⭐ canônico
+        ├── orders-test.ts                # nome-da-funcao + -test.ts
+        ├── shipments-test.ts
+        └── fixtures/
+            ├── orders-payload-1.json     # fixtures real-world
+            └── stripe-webhook-event.json
+```
+
+Diretrizes:
+- **`tests/` separado em `supabase/functions/`** — não é deployado (CLI bundling ignora).
+- **Sufixo `-test.ts`** — convenção Deno test runner.
+- **`fixtures/`** — payloads capturados em prod (sanitizados) via `mcp__supabase__get_logs` (ver agente `payload-capture-instrumenter`).
+
+## Pattern 1 — Test básico de Edge Function via HTTP
+
+```ts
+// supabase/functions/tests/orders-test.ts
+import { assert, assertEquals } from 'jsr:@std/assert@1'
+import { createClient } from 'npm:@supabase/supabase-js@2.95.0'
+import 'jsr:@std/dotenv@0.225.5/load'   // PT-BR: carrega .env automatically
+
+const SUPABASE_URL = Deno.env.get('SUPABASE_URL')!
+const SUPABASE_PUBLISHABLE_KEY = Deno.env.get('SUPABASE_PUBLISHABLE_KEY')!
+
+const supabase = createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, {
+  auth: { autoRefreshToken: false, persistSession: false, detectSessionInUrl: false },
+})
+
+Deno.test('orders — happy path', async () => {
+  const { data, error } = await supabase.functions.invoke('orders', {
+    body: { customer_id: 'test-1', items: [{ sku: 'A', qty: 2 }] },
+  })
+  assert(!error, `function returned error: ${error?.message}`)
+  assertEquals(data.status, 'pending')
+  assert(typeof data.order_id === 'string')
+})
+
+Deno.test('orders — validation error', async () => {
+  const { error } = await supabase.functions.invoke('orders', { body: {} })
+  // PT-BR: invoke retorna FunctionsHttpError quando status >= 400
+  assert(error, 'expected validation error')
+})
+```
+
+## Pattern 2 — Setup local + execução
+
+```bash
+# 1. levantar stack local (DB + Storage + Functions runtime)
+supabase start
+
+# 2. servir função com hot-reload (default)
+supabase functions serve orders --env-file .env.local
+
+# 3. em outro terminal: rodar tests
+deno test --allow-all supabase/functions/tests/orders-test.ts
+
+# 4. todos os tests
+deno test --allow-all supabase/functions/tests/
+```
+
+`.env.local` típico para tests:
+
+```
+SUPABASE_URL=http://localhost:54321
+SUPABASE_PUBLISHABLE_KEY=sb_publishable_local_default_key
+SUPABASE_SECRET_KEY=sb_secret_local_default_key
+```
+
+`supabase status` mostra as chaves locais.
+
+## Pattern 3 — Test com user JWT (RLS-aware)
+
+```ts
+import { createClient } from 'npm:@supabase/supabase-js@2.95.0'
+import { assertEquals } from 'jsr:@std/assert@1'
+
+const supabase = createClient(Deno.env.get('SUPABASE_URL')!, Deno.env.get('SUPABASE_PUBLISHABLE_KEY')!)
+
+Deno.test('notes — só vê suas próprias notas (RLS)', async () => {
+  await supabase.auth.signInWithPassword({ email: 'alice@test.local', password: 'alice-pwd' })
+  const { data } = await supabase.functions.invoke('notes')
+  assert(Array.isArray(data))
+  for (const note of data) assertEquals(note.owner_id, supabase.auth.getUser().data.user!.id)
+})
+```
+
+## Pattern 4 — Test determinístico para função API-only (adapter pattern)
+
+Para Edge Function que wrappa API externa (OpenAI, Stripe, Resend), injetar fake provider via env. Ver [`legacy-api-only-applications`](../legacy-api-only-applications/SKILL.md) e [`llm-as-dependency`](../skills/llm-as-dependency/SKILL.md).
+
+```ts
+// supabase/functions/_shared/openai-adapter.ts
+export interface LLMProvider {
+  complete(prompt: string): Promise<string>
+}
+
+export class OpenAIProvider implements LLMProvider {
+  async complete(prompt: string) { /* npm:openai */ }
+}
+
+export class FakeLLMProvider implements LLMProvider {
+  constructor(private fixture: Record<string, string>) {}
+  async complete(prompt: string) { return this.fixture[prompt] ?? 'fake response' }
+}
+
+// supabase/functions/chat/index.ts
+import { OpenAIProvider, FakeLLMProvider } from '../_shared/openai-adapter.ts'
+
+const provider = Deno.env.get('USE_FAKE_LLM') === '1'
+  ? new FakeLLMProvider({ 'hi': 'fake hello' })
+  : new OpenAIProvider()
+```
+
+```bash
+USE_FAKE_LLM=1 supabase functions serve chat
+deno test --allow-all supabase/functions/tests/chat-test.ts
+```
+
+## Pattern 5 — Characterization test (Edge Function legada)
+
+Captura comportamento atual como golden snapshot **antes** de refatorar. Ver [`pre-refactor-characterization`](../pre-refactor-characterization/SKILL.md).
+
+```ts
+import { assertEquals } from 'jsr:@std/assert@1'
+import payloads from './fixtures/orders-payloads.json' with { type: 'json' }
+
+Deno.test('orders — characterization (5 equivalence classes)', async (t) => {
+  for (const { name, input, expected_status } of payloads) {
+    await t.step(name, async () => {
+      const res = await fetch('http://localhost:54321/functions/v1/orders', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', apikey: Deno.env.get('SUPABASE_PUBLISHABLE_KEY')! },
+        body: JSON.stringify(input),
+      })
+      assertEquals(res.status, expected_status)
+      const body = await res.json()
+      await assertSnapshot(t, body)   // jsr:@std/testing/snapshot
+    })
+  }
+})
+```
+
+5 grupos canônicos: happy path · validation error · auth error · rate limit · downstream timeout.
+
+## Pattern 6 — Local debug com Chrome DevTools
+
+```bash
+# Serve em inspect mode — pausa na primeira linha
+supabase functions serve orders --inspect-mode brk
+```
+
+No Chrome:
+1. Navegar para `chrome://inspect`
+2. Clicar **Configure...** ao lado de "Discover network targets"
+3. Adicionar `127.0.0.1:8083` → **Done**
+4. Aguardar target aparecer; clicar **Open dedicated DevTools for Node**
+5. Mandar request: `curl http://localhost:54321/functions/v1/orders -d '{}'`
+6. DevTools pausa na primeira linha → **Sources** → `file:///home/deno/functions/orders/index.ts`
+7. Set breakpoints, step through.
+
+Modos: `brk` (pausa primeira linha) ou `wait` (aguarda debugger antes de qualquer execução).
+
+## Pattern 7 — Background task / WebSocket local
+
+```toml
+# supabase/config.toml
+[edge_runtime]
+policy = "per_worker"        # mantém isolate alive entre requests
+```
+
+Sem `per_worker`, isolate termina após request — `EdgeRuntime.waitUntil` é cortado, WebSocket fecha. Caveat: hot-reload **desativado**; restart manual:
+
+```bash
+# Ctrl+C e relançar
+supabase functions serve orders
+```
+
+## Pattern 8 — Test de erro client-side
+
+```ts
+import {
+  FunctionsHttpError,
+  FunctionsRelayError,
+  FunctionsFetchError,
+} from 'npm:@supabase/supabase-js@2.95.0'
+
+Deno.test('orders — error classification', async () => {
+  const { error } = await supabase.functions.invoke('orders', { body: { bad: true } })
+  if (error instanceof FunctionsHttpError) {
+    const body = await error.context.json()
+    assertEquals(body.code, 'VALIDATION')
+  } else if (error instanceof FunctionsRelayError) {
+    // gateway↔supabase issue
+  } else if (error instanceof FunctionsFetchError) {
+    // função inalcançável (down)
+  }
+})
+```
+
+## Logging gotchas durante debug
+
+```ts
+// ⚠ Errado — Headers não é enumerable em JSON.stringify
+console.log(`Headers: ${JSON.stringify(req.headers)}`)   // sempre "{}"
+
+// ✓ Certo
+console.log('Headers:', JSON.stringify(Object.fromEntries(req.headers), null, 2))
+```
+
+Limites runtime hospedado:
+- Custom log message: até **10.000 chars**
+- Log event threshold: **100 events / 10s**
+
+Em prod, logs aparecem em [Functions > seu nome > Logs] no Dashboard. Em dev, no terminal do `supabase functions serve`.
+
+## Anti-patterns
+
+### AT1 — Test direto contra prod
+Sempre `supabase start` local + `SUPABASE_URL=http://localhost:54321`. Test em prod = dados reais sujos + custo.
+
+### AT2 — Mockar Supabase client inteiro
+Prefira `supabase start` (DB real, schema real). Mocks divergem de produção e mascaram bugs de migration (ver feedback do projeto v1.20+).
+
+### AT3 — Hot-reload com `per_worker`
+Quando necessário (WebSocket/background), aceite restart manual. Não tente forçar hot-reload com `per_worker` — comportamento indefinido.
+
+### AT4 — Esquecer `--env-file`
+Sem `--env-file`, env vars custom não chegam na função (apenas as Supabase pre-populadas). 401 em produção mas verde local.
+
+### AT5 — Test que escreve sem cleanup
+Use `beforeEach`/`afterEach` ou `Deno.test` com setup/teardown via `t.step`. Estado entre testes corrompe assertions.
+
+## Ver também
+
+- [`supabase-edge-functions`](../supabase-edge-functions/SKILL.md) — base
+- [`supabase-edge-functions-auth`](../supabase-edge-functions-auth/SKILL.md) — autenticar tests com user JWT
+- [`supabase-edge-functions-limits`](../supabase-edge-functions-limits/SKILL.md) — status codes esperados
+- [`supabase-pgtap-testing`](../supabase-pgtap-testing/SKILL.md) — tests de DB/RLS (complementar)
+- [`legacy-characterization-tests`](../legacy-characterization-tests/SKILL.md) — pré-refactor
+- [`legacy-api-only-applications`](../legacy-api-only-applications/SKILL.md) — adapter + fake provider
+- [`pre-refactor-characterization`](../pre-refactor-characterization/SKILL.md) — payload capture
+- [`ai-prompt-characterization`](../ai-prompt-characterization/SKILL.md) — Edge Functions com LLM