nardoto-mcp-freesound 1.0.0

package/README.md

@@ -0,0 +1,20 @@
+# nardoto-mcp-freesound
+
+MCP server para buscar e baixar **efeitos sonoros (SFX) Creative Commons do Freesound** direto no chat.
+
+## Configuração
+- `FREESOUND_API_KEY` — Token grátis em https://freesound.org/apiv2/apply. Cobre busca + download do **preview MP3** (suficiente para ~90% dos SFX). O arquivo original (.wav/.flac) exigiria OAuth2 e está fora do escopo.
+
+## Tools
+- `search_sounds` — busca por texto, filtro de duração máxima.
+- `get_sound` — detalhes de um som.
+- `download_preview` — URL do preview MP3 (sem OAuth).
+
+Toda resposta traz a **licença** e o campo `uso_comercial` (CC0 = livre; CC-BY = com atribuição; CC-BY-NC = proibido monetizar).
+
+## Uso
+```
+npx -y nardoto-mcp-freesound
+```
+
+MIT · feito pelo Nardoto.

package/index.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * nardoto-mcp-freesound — MCP server pra buscar e baixar efeitos sonoros (SFX) Creative Commons do Freesound.
+ *
+ * Auth: FREESOUND_API_KEY (Token gratis em https://freesound.org/apiv2/apply).
+ * O Token cobre busca + download do PREVIEW comprimido (.mp3), que basta pra ~90% dos SFX em video.
+ * (O arquivo ORIGINAL .wav/.flac exigiria OAuth2 — fora do escopo deste MCP.)
+ * Toda resposta inclui a licenca e o campo "uso_comercial" (muito SFX e CC-BY-NC).
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+
+const KEY = process.env.FREESOUND_API_KEY
+const BASE = 'https://freesound.org/apiv2'
+const FIELDS = 'id,name,license,previews,username,duration,tags'
+
+async function fget(path, params) {
+  if (!KEY) throw new Error('Defina FREESOUND_API_KEY (Token gratis em freesound.org/apiv2/apply).')
+  const url = new URL(BASE + path)
+  for (const [k, v] of Object.entries(params || {})) {
+    if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, String(v))
+  }
+  const res = await fetch(url, { headers: { Authorization: 'Token ' + KEY, 'User-Agent': 'nardoto-mcp-freesound' } })
+  if (!res.ok) throw new Error(`Freesound HTTP ${res.status}`)
+  return res.json()
+}
+
+function usoComercial(license) {
+  const l = (license || '').toLowerCase()
+  if (/noncommercial|by-nc/.test(l)) return 'PROIBIDO em conteudo monetizado (licenca NonCommercial).'
+  if (/creative commons 0|cc0|publicdomain|\/zero\//.test(l)) return 'Livre, dominio publico (CC0) — sem atribuicao.'
+  return 'Permitido com atribuicao ao autor (confira a licenca).'
+}
+
+function fmtSound(s) {
+  const previews = s.previews || {}
+  return {
+    id: s.id,
+    name: s.name,
+    autor: s.username,
+    duration_s: s.duration,
+    tags: Array.isArray(s.tags) ? s.tags.slice(0, 12) : undefined,
+    preview_mp3: previews['preview-hq-mp3'] || previews['preview-lq-mp3'] || null,
+    license: s.license,
+    uso_comercial: usoComercial(s.license),
+  }
+}
+
+const TOOLS = [
+  {
+    name: 'search_sounds',
+    description: 'Busca efeitos sonoros e samples Creative Commons no Freesound. Retorna a licenca, o aviso de uso comercial e a URL do preview MP3.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Termo de busca (ex: "vento deserto", "multidao", "passos cascalho")' },
+        limit: { type: 'number', description: 'Maximo de resultados (1-50, padrao 12)' },
+        max_duration_s: { type: 'number', description: 'Duracao maxima em segundos (filtro opcional)' },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'get_sound',
+    description: 'Detalhes de um som pelo id (licenca, autor, preview MP3).',
+    inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'ID do som' } }, required: ['id'] },
+  },
+  {
+    name: 'download_preview',
+    description: 'Retorna a URL do preview MP3 de um som (download direto, sem OAuth) junto com a licenca e o aviso de uso comercial.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'ID do som' } }, required: ['id'] },
+  },
+]
+
+const server = new Server({ name: 'nardoto-mcp-freesound', version: '1.0.0' }, { capabilities: { tools: {} } })
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params
+  try {
+    if (name === 'search_sounds') {
+      if (!args.query) throw new Error('query obrigatoria')
+      const params = { query: args.query, fields: FIELDS, page_size: Math.min(Math.max(Number(args.limit) || 12, 1), 50) }
+      if (args.max_duration_s) params.filter = `duration:[0 TO ${Number(args.max_duration_s)}]`
+      const data = await fget('/search/text/', params)
+      const sounds = (data.results || []).map(fmtSound)
+      return { content: [{ type: 'text', text: JSON.stringify({ count: sounds.length, total: data.count, sounds, aviso: 'Confira "uso_comercial": muito SFX e CC-BY-NC (proibido monetizar).' }, null, 2) }] }
+    }
+    if (name === 'get_sound' || name === 'download_preview') {
+      if (!args.id) throw new Error('id obrigatorio')
+      const s = await fget(`/sounds/${encodeURIComponent(args.id)}/`, { fields: FIELDS })
+      return { content: [{ type: 'text', text: JSON.stringify(fmtSound(s), null, 2) }] }
+    }
+    return { content: [{ type: 'text', text: 'Tool desconhecida: ' + name }], isError: true }
+  } catch (e) {
+    return { content: [{ type: 'text', text: 'Erro: ' + (e?.message || String(e)) }], isError: true }
+  }
+})
+
+await server.connect(new StdioServerTransport())
+console.error('[nardoto-mcp-freesound] pronto (stdio)')

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "nardoto-mcp-freesound",
+  "version": "1.0.0",
+  "description": "MCP server para buscar e baixar efeitos sonoros Creative Commons do Freesound",
+  "type": "module",
+  "bin": {
+    "nardoto-mcp-freesound": "index.js"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "freesound",
+    "sfx",
+    "sound-effects",
+    "creative-commons",
+    "nardoto"
+  ],
+  "author": "Nardoto",
+  "license": "MIT"
+}