Kodus OSV

Servidor MCP OSV (Bun)

Servidor HTTP remoto do Model Context Protocol (MCP) que encapsula a API v1 do OSV para consultas sob demanda de vulnerabilidades em software de código aberto (exemplo de feed: https://osv.dev/list?q=%40NESTJS%2FCORE&ecosystem=npm). Exportado como ferramentas MCP para que agentes possam consultar o OSV diretamente.

Recursos

• Endpoint MCP HTTP transmitível em /mcp.
• Ferramentas: osv_query (alvo único) e osv_query_batch (múltiplos).
• URL base configurável (OSV_API_URL, padrão: https://api.osv.dev/v1).
• Schemas e validação claros para orientar LLMs (commit XOR version, regras de purl, paginação).

Início rápido

Pré-requisitos: Bun.

bun install
PORT=3000 HOST=0.0.0.0 OSV_API_URL=https://api.osv.dev/v1 bun run index.ts

Endpoint MCP: http://<host>:<port>/mcp.

Variáveis de ambiente:

• PORT / HOST: bind HTTP (padrão: 3000 / 0.0.0.0).
• OSV_API_URL: substitui a URL base do OSV.

Configuração do cliente MCP

• Claude Code CLI: claude mcp add --transport http mcp-osv http://localhost:3000/mcp
• VS Code: code --add-mcp "{\"name\":\"mcp-osv\",\"type\":\"http\",\"url\":\"http://localhost:3000/mcp\"}"
• MCP Inspector: npx @modelcontextprotocol/inspector -> conectar a http://localhost:3000/mcp Substitua localhost pelo seu host/porta se remoto.

Ferramentas e parâmetros

osv_query

{
  "commit": "sha OR",
  "version": "version string OR",
  "package": {
    "name": "required with ecosystem if not using purl",
    "ecosystem": "required with name if not using purl",
    "purl": "pkg:pypi/jinja2 // purl OR name+ecosystem; if version is present, omit @version here"
  },
  "pageToken": "optional pagination token from previous OSV response"
}

Regras:

• Use commit XOR version (um ou outro, nunca ambos).
• Se version estiver presente, package é obrigatório.
• package deve ser purl ou (name + ecosystem).
• Se version existir e package.purl for usado, omita @version no purl.

osv_query_batch

{
  "queries": [
    {
      "commit": "sha OR",
      "version": "version string OR",
      "package": {
        "name": "pkg name",
        "ecosystem": "ecosystem",
        "purl": "pkg:ecosys/name"
      },
      "pageToken": "optional"
    }
  ]
}

Regras: cada item segue as mesmas regras de osv_query.

Exemplos de chamadas

• Versão PyPI: {"package":{"purl":"pkg:pypi/jinja2"},"version":"3.1.4"}
• npm com name+ecosystem: {"package":{"name":"@nestjs/core","ecosystem":"npm"},"version":"10.2.10"}
• Consulta por commit: {"commit":"<sha>","package":{"ecosystem":"Go","name":"github.com/foo/bar"}}

Depuração

• Log do servidor: OSV MCP server listening on http://<host>:<port>/mcp
• Curl init: curl -H "content-type: application/json" -H "accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"curl","version":"0.0.0"},"capabilities":{}}}' http://localhost:3000/mcp
• Listar ferramentas: mesmo endpoint com {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

Licença

Licença MIT. Consulte LICENSE.