{"_id":"@aredes.me/mcp-senado","_rev":"5-3bebff560bb59017547610aa60c68197","name":"@aredes.me/mcp-senado","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"@aredes.me/mcp-senado","version":"0.1.0","keywords":["mcp","model-context-protocol","senado","senado-federal","brazilian-senate","legislative-data","open-data","dados-abertos","ai-assistant","claude","cursor","windsurf","continue","brazil","brasil","congress","congresso"],"author":{"url":"https://github.com/cristianoaredes","name":"Cristiano Aredes","email":"cristiano@aredes.me"},"license":"MIT","_id":"@aredes.me/mcp-senado@0.1.0","maintainers":[{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"}],"homepage":"https://github.com/cristianoaredes/mcp-senado#readme","bugs":{"url":"https://github.com/cristianoaredes/mcp-senado/issues"},"bin":{"mcp-senado":"build/bin/mcp-senado.js","mcp-senado-http":"build/bin/mcp-senado-http.js"},"dist":{"shasum":"e5eb7bdfb79584db1f6dd228348353393b99d9e7","tarball":"https://registry.npmjs.org/@aredes.me/mcp-senado/-/mcp-senado-0.1.0.tgz","fileCount":116,"integrity":"sha512-PoYAtoIm7DPVNeLWf8asOW5iTj8moa16kzvrspRpQ+Crqx0Rd+imRguGhqIgaXApcEjAoethyKeJxpeOxCOIZQ==","signatures":[{"sig":"MEYCIQCME0VJ4VZYCaN35WKpV7ojEpS6mpdpdULxz+S2KsdnZgIhAKXvmoSA2rcZ/YKKebFfF520CuVBQ3zu/ty6AoFAGXGC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":584832},"main":"build/index.js","type":"module","types":"build/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"1117c157ae4f7f9efbc139642657056b04bbbd90","scripts":{"dev":"tsx watch lib/bin/mcp-senado.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","clean":"rm -rf build","smoke":"tsx scripts/smoke-test.ts","dev:http":"tsx watch lib/bin/mcp-senado-http.ts","start:http":"node build/bin/mcp-senado-http.js","test:watch":"vitest","dev:workers":"wrangler dev","test:coverage":"vitest run --coverage","deploy:workers":"npm run build && wrangler deploy","prepublishOnly":"npm run clean && npm run build","deploy:workers:staging":"npm run build && wrangler deploy --env staging","deploy:workers:production":"npm run build && wrangler deploy --env production"},"_npmUser":{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"},"repository":{"url":"git+https://github.com/cristianoaredes/mcp-senado.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Brazilian Federal Senate (Senado Federal) Open Data API - Access legislative data through AI assistants","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","express":"^5.1.0","@genkit-ai/mcp":"^1.23.0","fast-xml-parser":"^4.3.4","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.0.0","wrangler":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0","@types/express":"^5.0.5","@vitest/coverage-v8":"^4.0.0","@cloudflare/workers-types":"^4.20251113.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-senado_0.1.0_1763159307638_0.5829659558824287","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aredes.me/mcp-senado","version":"0.1.1","keywords":["mcp","model-context-protocol","senado","senado-federal","brazilian-senate","legislative-data","open-data","dados-abertos","ai-assistant","claude","cursor","windsurf","continue","brazil","brasil","congress","congresso"],"author":{"url":"https://github.com/cristianoaredes","name":"Cristiano Aredes","email":"cristiano@aredes.me"},"license":"MIT","_id":"@aredes.me/mcp-senado@0.1.1","maintainers":[{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"}],"homepage":"https://github.com/cristianoaredes/mcp-camara#readme","bugs":{"url":"https://github.com/cristianoaredes/mcp-camara/issues"},"bin":{"mcp-senado":"build/bin/mcp-senado.js","mcp-senado-http":"build/bin/mcp-senado-http.js"},"dist":{"shasum":"1a703afe1f6c2b23129d6b361c6bdae7d1fb7b10","tarball":"https://registry.npmjs.org/@aredes.me/mcp-senado/-/mcp-senado-0.1.1.tgz","fileCount":120,"integrity":"sha512-3KlpRul24p9DGkpQkMsJphclP1HVIzO32H88nYKzgDuY9WJmrzYDVNyjjZ3Y8AbVg37qlTZkcfl6dO3bfeBYnw==","signatures":[{"sig":"MEUCIEQFUVPu5ZG6IDViuXo0z0Io2ki+uMwsFvC2rCfB9jWNAiEA2uUl2/0ekk0e2XTQuUOEYIkbBvjmkRsAr/5MpkP2Po4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":625859},"main":"build/index.js","type":"module","types":"build/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"b0f2eff29deaa8bd505abb60a12203b60478485d","scripts":{"dev":"tsx watch lib/bin/mcp-senado.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","clean":"rm -rf build","smoke":"tsx scripts/smoke-test.ts","dev:http":"tsx watch lib/bin/mcp-senado-http.ts","start:http":"node build/bin/mcp-senado-http.js","test:watch":"vitest","dev:workers":"wrangler dev","test:coverage":"vitest run --coverage","deploy:workers":"npm run build && wrangler deploy","prepublishOnly":"npm run clean && npm run build","deploy:workers:staging":"npm run build && wrangler deploy --env staging","deploy:workers:production":"npm run build && wrangler deploy --env production"},"_npmUser":{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"},"repository":{"url":"git+https://github.com/cristianoaredes/mcp-camara.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Brazilian Federal Senate (Senado Federal) Open Data API - Access legislative data through AI assistants","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","express":"^5.1.0","@genkit-ai/mcp":"^1.23.0","fast-xml-parser":"^4.3.4","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.0.0","wrangler":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0","@types/express":"^5.0.5","@vitest/coverage-v8":"^4.0.0","@cloudflare/workers-types":"^4.20251113.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-senado_0.1.1_1763305587146_0.8195170040064663","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@aredes.me/mcp-senado","version":"0.1.2","keywords":["mcp","model-context-protocol","senado","senado-federal","brazilian-senate","legislative-data","open-data","dados-abertos","ai-assistant","claude","cursor","windsurf","continue","brazil","brasil","congress","congresso"],"author":{"url":"https://github.com/cristianoaredes","name":"Cristiano Aredes","email":"cristiano@aredes.me"},"license":"MIT","_id":"@aredes.me/mcp-senado@0.1.2","maintainers":[{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"}],"homepage":"https://github.com/cristianoaredes/mcp-senado#readme","bugs":{"url":"https://github.com/cristianoaredes/mcp-senado/issues"},"bin":{"mcp-senado":"build/bin/mcp-senado.js","mcp-senado-http":"build/bin/mcp-senado-http.js"},"dist":{"shasum":"c825958634d9b8f0809af1caae38bf1a9412116c","tarball":"https://registry.npmjs.org/@aredes.me/mcp-senado/-/mcp-senado-0.1.2.tgz","fileCount":120,"integrity":"sha512-AjHJFfPFRtEDF9CpKHaAkYunoSKyjb9wXxfrFJbrLd01K2mVC2KRDpXTIZQaJHN0ckMURjXSu9v9J8t8mkLU0A==","signatures":[{"sig":"MEUCIFVkV1XgzJfebFO5peP1NsU9IDhZ3a0j4WGuYD0E2WJaAiEAoTg1C3WoV1SUUtj6hHc/cOCFWKLewBY9pbOXnHJvRW8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":625863},"main":"build/index.js","type":"module","types":"build/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"e148a62d3449eff099e03d114d5b728cee281a8a","scripts":{"dev":"tsx watch lib/bin/mcp-senado.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","clean":"rm -rf build","smoke":"tsx scripts/smoke-test.ts","dev:http":"tsx watch lib/bin/mcp-senado-http.ts","start:http":"node build/bin/mcp-senado-http.js","test:watch":"vitest","dev:workers":"wrangler dev","test:coverage":"vitest run --coverage","deploy:workers":"npm run build && wrangler deploy","prepublishOnly":"npm run clean && npm run build","deploy:workers:staging":"npm run build && wrangler deploy --env staging","deploy:workers:production":"npm run build && wrangler deploy --env production"},"_npmUser":{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"},"repository":{"url":"git+https://github.com/cristianoaredes/mcp-senado.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Brazilian Federal Senate (Senado Federal) Open Data API - Access legislative data through AI assistants","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","express":"^5.1.0","@genkit-ai/mcp":"^1.23.0","fast-xml-parser":"^4.3.4","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.0.0","wrangler":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0","@types/express":"^5.0.5","@vitest/coverage-v8":"^4.0.0","@cloudflare/workers-types":"^4.20251113.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-senado_0.1.2_1763306763753_0.7455108282209435","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aredes.me/mcp-senado","version":"0.2.0","keywords":["mcp","model-context-protocol","senado","senado-federal","brazilian-senate","legislative-data","open-data","dados-abertos","ai-assistant","claude","cursor","windsurf","continue","brazil","brasil","congress","congresso"],"author":{"url":"https://github.com/cristianoaredes","name":"Cristiano Aredes","email":"cristiano@aredes.me"},"license":"MIT","_id":"@aredes.me/mcp-senado@0.2.0","maintainers":[{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"}],"homepage":"https://github.com/cristianoaredes/mcp-senado#readme","bugs":{"url":"https://github.com/cristianoaredes/mcp-senado/issues"},"bin":{"mcp-senado":"build/bin/mcp-senado.js","mcp-senado-http":"build/bin/mcp-senado-http.js"},"dist":{"shasum":"af8755f71cf481d02748983c8696dd69c1d69ae2","tarball":"https://registry.npmjs.org/@aredes.me/mcp-senado/-/mcp-senado-0.2.0.tgz","fileCount":120,"integrity":"sha512-7OlO+dgw+i5FiQP+vZvmbOyfjusXuDUbY6iFlpyZWakFAL9z8KyeQLGmaEeDG74XCnsaPMspk2d7fHUcO4MILA==","signatures":[{"sig":"MEUCIQDhulKVD8SNti0y/aivS50tBqw69XdCq6nVombohLXvNAIgHajW/KjOMQtx4jB0vKkypVpaCAelYfnG24aIC0NxsJw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":637301},"main":"build/index.js","type":"module","types":"build/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"15101ae71526c26c50b1b000b688e9f8e6b7ef50","scripts":{"dev":"tsx watch lib/bin/mcp-senado.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","clean":"rm -rf build","smoke":"tsx scripts/smoke-test.ts","dev:http":"tsx watch lib/bin/mcp-senado-http.ts","start:http":"node build/bin/mcp-senado-http.js","test:watch":"vitest","dev:workers":"wrangler dev","test:coverage":"vitest run --coverage","deploy:workers":"npm run build && wrangler deploy","prepublishOnly":"npm run clean && npm run build","deploy:workers:staging":"npm run build && wrangler deploy --env staging","deploy:workers:production":"npm run build && wrangler deploy --env production"},"_npmUser":{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"},"repository":{"url":"git+https://github.com/cristianoaredes/mcp-senado.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Brazilian Federal Senate (Senado Federal) Open Data API - Access legislative data through AI assistants","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","express":"^5.1.0","@genkit-ai/mcp":"^1.23.0","fast-xml-parser":"^4.3.4","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.0.0","wrangler":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0","@types/express":"^5.0.5","@vitest/coverage-v8":"^4.0.0","@cloudflare/workers-types":"^4.20251113.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-senado_0.2.0_1763317362865_0.9254533669741314","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@aredes.me/mcp-senado","version":"0.2.1","description":"Official MCP server for Brazilian Federal Senate (Senado Federal) Open Data API - Query senator voting records, legislative proposals, committee activities via Claude, Cursor, Continue. 56 tools for legislative transparency and political research in Brazi","type":"module","main":"build/index.js","types":"build/index.d.ts","bin":{"mcp-senado":"build/bin/mcp-senado.js","mcp-senado-http":"build/bin/mcp-senado-http.js"},"scripts":{"build":"tsc","dev":"tsx watch lib/bin/mcp-senado.ts","dev:http":"tsx watch lib/bin/mcp-senado-http.ts","dev:workers":"wrangler dev","start:http":"node build/bin/mcp-senado-http.js","deploy:workers":"npm run build && wrangler deploy","deploy:workers:staging":"npm run build && wrangler deploy --env staging","deploy:workers:production":"npm run build && wrangler deploy --env production","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"tsc --noEmit","clean":"rm -rf build","prepublishOnly":"npm run clean && npm run build","smoke":"tsx scripts/smoke-test.ts"},"keywords":["mcp","model-context-protocol","mcp-server","brazilian-senate","senado-federal","legislative-data","congress-api","voting-records","senate-bills","political-transparency","parliamentary-data","government-api","open-data","dados-abertos","data-journalism","political-research","civic-tech","ai-assistant","claude","claude-integration","cursor","windsurf","continue","brazil","brasil","senado","congress","congresso"],"author":{"name":"Cristiano Aredes","email":"cristiano@aredes.me","url":"https://github.com/cristianoaredes"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cristianoaredes/mcp-senado.git"},"bugs":{"url":"https://github.com/cristianoaredes/mcp-senado/issues"},"homepage":"https://github.com/cristianoaredes/mcp-senado#readme","engines":{"node":">=18.0.0"},"dependencies":{"@genkit-ai/mcp":"^1.23.0","@modelcontextprotocol/sdk":"^1.0.4","dotenv":"^16.4.5","express":"^5.1.0","fast-xml-parser":"^4.3.4","zod":"^3.23.8"},"devDependencies":{"@cloudflare/workers-types":"^4.20251113.0","@types/express":"^5.0.5","@types/node":"^22.0.0","@vitest/coverage-v8":"^4.0.0","tsx":"^4.0.0","typescript":"^5.7.0","vitest":"^4.0.0","wrangler":"^4.0.0"},"_id":"@aredes.me/mcp-senado@0.2.1","gitHead":"3ee684ad454666496dd0382bccbe1790aecc6a20","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-uO+6qrNhdFaNFiOA7cSm7OTTcJol8FbsIui9QQ9ErMpJvJNHHUpLzWTJPkDEHaTjDiHD9WVoKzxh9g/hoPCfMA==","shasum":"33d2d25b1ad5957ca96cc4c345b26d5799c90879","tarball":"https://registry.npmjs.org/@aredes.me/mcp-senado/-/mcp-senado-0.2.1.tgz","fileCount":120,"unpackedSize":637691,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCVLzKHpWdej2pFDfmh3k+l8kljtW6qoHv4e3HOjutm9QIgRPlcfVbaBNlT02dh5H+K4TIq0ipyKGtkU1xZxc6JPZ0="}]},"_npmUser":{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"},"directories":{},"maintainers":[{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-senado_0.2.1_1763319908883_0.9679234123716487"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-14T22:28:27.560Z","modified":"2025-11-16T19:05:09.314Z","0.1.0":"2025-11-14T22:28:27.850Z","0.1.1":"2025-11-16T15:06:27.351Z","0.1.2":"2025-11-16T15:26:03.968Z","0.2.0":"2025-11-16T18:22:43.070Z","0.2.1":"2025-11-16T19:05:09.097Z"},"bugs":{"url":"https://github.com/cristianoaredes/mcp-senado/issues"},"author":{"name":"Cristiano Aredes","email":"cristiano@aredes.me","url":"https://github.com/cristianoaredes"},"license":"MIT","homepage":"https://github.com/cristianoaredes/mcp-senado#readme","keywords":["mcp","model-context-protocol","mcp-server","brazilian-senate","senado-federal","legislative-data","congress-api","voting-records","senate-bills","political-transparency","parliamentary-data","government-api","open-data","dados-abertos","data-journalism","political-research","civic-tech","ai-assistant","claude","claude-integration","cursor","windsurf","continue","brazil","brasil","senado","congress","congresso"],"repository":{"type":"git","url":"git+https://github.com/cristianoaredes/mcp-senado.git"},"description":"Official MCP server for Brazilian Federal Senate (Senado Federal) Open Data API - Query senator voting records, legislative proposals, committee activities via Claude, Cursor, Continue. 56 tools for legislative transparency and political research in Brazi","maintainers":[{"name":"cristianoaredes","email":"cristianoaredes@icloud.com"}],"readme":"# MCP Senado Federal 🇧🇷\n\n> **Servidor MCP para API de Dados Abertos do Senado Federal Brasileiro**\n> Conecte assistentes de IA como Claude, Cursor, Windsurf e Continue.dev aos dados legislativos oficiais do Congresso Nacional\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/cristianoaredes/mcp-senado/actions/workflows/ci.yml)\n[](https://www.typescriptlang.org/)\n[](https://nodejs.org/)\n[](https://github.com/cristianoaredes/mcp-senado)\n[](https://github.com/cristianoaredes/mcp-senado)\n[](https://www.npmjs.com/package/@aredes.me/mcp-senado)\n\n[English](./README.en.md) | **Português** | [Documentação Completa](#-documentação) | [Contribuir](./CONTRIBUTING.md)\n\n---\n\n## 📋 Índice\n\n- [Visão Geral](#-visão-geral)\n- [Recursos Principais](#-recursos-principais)\n- [Instalação](#-instalação)\n- [Início Rápido](#-início-rápido)\n- [Ferramentas Disponíveis](#-ferramentas-disponíveis)\n- [Modos de Implantação](#-modos-de-implantação)\n- [Configuração](#-configuração)\n- [Exemplos de Uso](#-exemplos-de-uso)\n- [Documentação](#-documentação)\n- [Contribuindo](#-contribuindo)\n- [Licença](#-licença)\n\n---\n\n## 🎯 Visão Geral\n\n**MCP Senado Federal** é um servidor MCP (Model Context Protocol) de código aberto que conecta assistentes de inteligência artificial à **API de Dados Abertos do Senado Federal do Brasil**. Desenvolvido com TypeScript, oferece acesso programático a dados legislativos completos, incluindo informações sobre senadores, propostas legislativas, votações, comissões, partidos e sessões plenárias.\n\n### Por que usar?\n\n- 🤖 **Integração com IA**: Use ChatGPT, Claude, Cursor, Windsurf para consultar dados do Senado\n- 📊 **Dados Oficiais**: Acesso direto à fonte oficial de dados abertos do Senado Federal\n- 🚀 **Pronto para Produção**: Circuit breaker, rate limiting, cache e monitoramento incluídos\n- 🔒 **Seguro e Confiável**: Validação de entrada, conformidade com LGPD, tratamento robusto de erros\n- 🌍 **Deploy Global**: Suporte para Docker, Cloudflare Workers (edge computing) e HTTP/REST\n- 📚 **Bem Documentado**: Documentação completa em português e inglês\n\n### Casos de Uso\n\n- **Jornalismo de Dados**: Análise automatizada de votações e propostas legislativas\n- **Pesquisa Acadêmica**: Estudos sobre comportamento parlamentar e produção legislativa\n- **Transparência Pública**: Ferramentas de acompanhamento da atividade legislativa\n- **Aplicações Cívicas**: Chatbots e assistentes virtuais para educação política\n- **Análise Política**: Dashboards e relatórios sobre o Congresso Nacional\n\n---\n\n## ✨ Recursos Principais\n\n### 🛠️ 56 Ferramentas em 7 Categorias\n\n| Categoria | Ferramentas | Descrição |\n| -------------------------- | -------------- | --------------------------------------------------- |\n| **Dados de Referência** | 10 ferramentas | Legislaturas, tipos de proposta, estados, comissões |\n| **Senadores** | 13 ferramentas | Busca, biografia, votações, propostas, discursos |\n| **Propostas Legislativas** | 12 ferramentas | Pesquisa, detalhes, votações, tramitação, textos |\n| **Votações** | 5 ferramentas | Sessões de votação, resultados, votos individuais |\n| **Comissões** | 5 ferramentas | Listagem, membros, reuniões, pautas |\n| **Partidos** | 5 ferramentas | Partidos, blocos, lideranças |\n| **Sessões Plenárias** | 6 ferramentas | Calendário, atas, discursos, resultados |\n\n### 🚀 Características Técnicas\n\n- ⚡ **Alto Desempenho**: Cache em memória com LRU, otimização de requisições\n- 🛡️ **Resiliência**: Circuit breaker para proteção contra falhas da API\n- 📊 **Monitoramento**: Logs estruturados, métricas, health checks\n- 🔄 **Rate Limiting**: Token bucket para controle de taxa de requisições\n- 🎯 **TypeScript Strict**: Type-safe com inferência de tipos completa\n- ✅ **Testado**: 211 testes (73% de cobertura), incluindo E2E\n- 🐳 **Containerizado**: Imagem Docker otimizada multi-stage (~150MB)\n- ⚡ **Edge Computing**: Deploy em Cloudflare Workers (300+ data centers)\n\n### 🔐 Segurança e Conformidade\n\n- ✅ Validação rigorosa de entrada com Zod schemas\n- ✅ Sanitização automática de dados\n- ✅ Mascaramento de PII (Personally Identifiable Information)\n- ✅ Conformidade com LGPD (Lei Geral de Proteção de Dados)\n- ✅ Autenticação opcional por token\n- ✅ CORS configurável\n- ✅ Rate limiting para prevenir abuso\n\n---\n\n## 📦 Instalação\n\n### Via NPM (Recomendado)\n\n```bash\n# Instalação global\nnpm install -g @aredes.me/mcp-senado\n\n# Ou executar diretamente\nnpx @aredes.me/mcp-senado\n```\n\n### Via Git (Desenvolvimento)\n\n```bash\ngit clone https://github.com/cristianoaredes/mcp-senado.git\ncd mcp-senado\nnpm install\nnpm run build\n```\n\n### Requisitos\n\n- **Node.js** 18.x ou superior\n- **npm** 9.x ou superior\n- **Memória**: Mínimo 512MB RAM\n- **Sistema Operacional**: Linux, macOS, Windows (WSL2)\n\n---\n\n## 🚀 Início Rápido\n\n### Claude Desktop\n\nAdicione ao arquivo `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"senado-federal\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@aredes.me/mcp-senado\"],\n \"env\": {\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\n**Localização do arquivo de configuração:**\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n### Cursor / Windsurf\n\nAdicione às configurações MCP do editor:\n\n```json\n{\n \"mcpServers\": {\n \"senado-federal\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@aredes.me/mcp-senado\"]\n }\n }\n}\n```\n\n### Continue.dev\n\nAdicione ao `config.json`:\n\n```json\n{\n \"mcpServers\": [\n {\n \"name\": \"senado-federal\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@aredes.me/mcp-senado\"]\n }\n ]\n}\n```\n\n### Testando a Integração\n\nApós configurar, pergunte ao seu assistente de IA:\n\n```\n\"Liste os senadores do estado de São Paulo\"\n\"Quais foram as últimas votações no Senado?\"\n\"Mostre propostas sobre educação tramitando no Senado\"\n```\n\n---\n\n## 🛠️ Ferramentas Disponíveis\n\n### 📚 Dados de Referência (10 ferramentas)\n\nAcesso a dados fundamentais do sistema legislativo:\n\n- `ufs_listar` - Lista todos os estados brasileiros (UFs)\n- `legislaturas_listar` - Lista legislaturas do Senado Federal\n- `tipos_materia_listar` - Lista tipos de proposições legislativas\n- `situacoes_materia_listar` - Lista situações de tramitação\n- `tipos_comissao_listar` - Lista tipos de comissões\n- `tipos_autor_listar` - Lista tipos de autores\n- `tipos_sessao_listar` - Lista tipos de sessões\n- `tipos_votacao_listar` - Lista tipos de votações\n- `tipos_documento_listar` - Lista tipos de documentos\n- `assuntos_listar` - Lista classificações temáticas\n\n### 👥 Senadores (13 ferramentas)\n\nInformações completas sobre parlamentares:\n\n- `senadores_listar` - Busca senadores com filtros (nome, partido, UF, legislatura)\n- `senador_detalhes` - Detalhes completos de um senador específico\n- `senador_historico` - Histórico parlamentar e mandatos anteriores\n- `senador_votacoes` - Votações de um senador com filtros\n- `senador_materias` - Propostas de autoria do senador\n- `senador_discursos` - Discursos proferidos pelo senador\n- `senador_licencas` - Licenças e afastamentos\n- `senador_comissoes` - Participação em comissões\n- `senador_liderancas` - Cargos de liderança ocupados\n- `senador_filiacao` - Histórico de filiação partidária\n- `senador_profissoes` - Profissões declaradas\n- `senador_apartes` - Apartes realizados\n- `senador_relatorias` - Relatorias de proposições\n\n### 📜 Propostas Legislativas (12 ferramentas)\n\nAcesso completo ao processo legislativo:\n\n- `materias_pesquisar` - Busca avançada de proposições\n- `materia_detalhes` - Informações detalhadas da proposição\n- `materia_texto` - Texto integral da proposição\n- `materia_votacoes` - Votações relacionadas\n- `materia_tramitacao` - Histórico de tramitação\n- `materia_autores` - Autores e coautores\n- `materia_relacionadas` - Proposições relacionadas\n- `materia_emendas` - Emendas apresentadas\n- `materia_pareceres` - Pareceres emitidos\n- `materia_notas_tecnicas` - Notas técnicas\n- `materia_audiencias` - Audiências públicas relacionadas\n- `materia_documentos` - Documentos anexos\n\n### 🗳️ Votações (5 ferramentas)\n\nResultados de votações nominais e simbólicas:\n\n- `votacoes_listar` - Lista votações com filtros\n- `votacao_detalhes` - Detalhes de votação específica\n- `votacao_votos` - Votos individuais dos senadores\n- `votacao_orientacoes` - Orientações de bancadas\n- `votacao_resumo` - Resumo estatístico da votação\n\n### 🏛️ Comissões (5 ferramentas)\n\nInformações sobre comissões parlamentares:\n\n- `comissoes_listar` - Lista todas as comissões (permanentes e temporárias)\n- `comissao_detalhes` - Detalhes de comissão específica\n- `comissao_membros` - Composição da comissão\n- `comissao_reunioes` - Calendário de reuniões\n- `comissao_materias` - Propostas em análise\n\n### 🎭 Partidos (5 ferramentas)\n\nDados sobre partidos e blocos parlamentares:\n\n- `partidos_listar` - Lista partidos e blocos\n- `partido_detalhes` - Informações do partido\n- `partido_membros` - Senadores filiados\n- `partido_liderancas` - Lideranças partidárias\n- `blocos_listar` - Blocos parlamentares e coligações\n\n### 📅 Sessões Plenárias (6 ferramentas)\n\nAcompanhamento de sessões do plenário:\n\n- `sessoes_listar` - Calendário de sessões\n- `sessao_detalhes` - Detalhes de sessão específica\n- `sessao_votacoes` - Votações da sessão\n- `sessao_discursos` - Discursos proferidos\n- `sessao_ordem_dia` - Ordem do dia\n- `sessao_expediente` - Expediente da sessão\n\n---\n\n## 🌐 Modos de Implantação\n\n### 1️⃣ Modo stdio (Padrão MCP)\n\nProtocolo nativo para assistentes de IA:\n\n```bash\n# Via npx\nnpx @aredes.me/mcp-senado\n\n# Via instalação global\nmcp-senado\n\n# Via código fonte\nnpm run dev\n```\n\n**Uso**: Integração direta com Claude Desktop, Cursor, Windsurf, Continue.dev\n\n### 2️⃣ Modo HTTP/REST API\n\nServidor HTTP standalone para aplicações web:\n\n```bash\n# Desenvolvimento\nnpm run dev:http\n\n# Produção\nnpm run start:http\n\n# Porta personalizada\nHTTP_PORT=8080 npm run start:http\n```\n\n**Endpoints disponíveis:**\n\n```bash\nGET /health # Health check\nPOST /mcp # Protocolo MCP via JSON-RPC\nGET /sse # Streaming (Server-Sent Events)\nGET /info # Informações do servidor\nGET /api/tools # Lista todas as ferramentas\nGET /api/tools/:name # Detalhes de ferramenta\nPOST /api/tools/:name # Executa ferramenta\nGET /api/categories # Lista categorias\nGET /api/tools/category/:cat # Ferramentas por categoria\n```\n\n**Exemplo de uso:**\n\n```bash\n# Listar senadores de SP\ncurl -X POST http://localhost:3000/api/tools/senadores_listar \\\n -H \"Content-Type: application/json\" \\\n -d '{\"uf\": \"SP\"}'\n\n# Health check\ncurl http://localhost:3000/health\n\n# JSON-RPC (tools/list)\ncurl -X POST http://localhost:3000/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"demo\",\"method\":\"tools/list\"}'\n\n# SSE streaming (somente leitura)\ncurl -N -H \"Accept: text/event-stream\" http://localhost:3000/sse\n```\n\n**Autenticação (opcional):**\n\n```bash\nHTTP_AUTH_ENABLED=true \\\nHTTP_AUTH_TOKEN=seu-token-secreto \\\nnpm run start:http\n\n# Requisição autenticada\ncurl -H \"Authorization: Bearer seu-token-secreto\" \\\n http://localhost:3000/api/tools\n```\n\n### 3️⃣ Modo Docker\n\nDeploy containerizado com isolamento completo:\n\n**Docker Compose (Recomendado):**\n\n```bash\n# Iniciar\ndocker-compose up -d\n\n# Ver logs\ndocker-compose logs -f\n\n# Parar\ndocker-compose down\n```\n\n**Docker manual:**\n\n```bash\n# Build\ndocker build -t mcp-senado .\n\n# Run\ndocker run -d \\\n --name mcp-senado \\\n -p 3000:3000 \\\n -e HTTP_PORT=3000 \\\n -e MCP_LOG_LEVEL=info \\\n mcp-senado:latest\n\n# Logs\ndocker logs -f mcp-senado\n```\n\n**Características:**\n- 🐳 Imagem Alpine Linux (~150MB)\n- 🔒 Execução como usuário não-root\n- 🏥 Health check integrado\n- 📊 Multi-stage build otimizado\n\n### 4️⃣ Cloudflare Workers (Edge Computing)\n\nDeploy global em 300+ data centers com **Durable Objects** para estado persistente:\n\n#### 🎯 Arquitetura com Durable Objects\n\nO MCP Senado utiliza **4 Durable Objects** para gerenciar estado distribuído:\n\n| Durable Object | Função | Benefício |\n| ------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- |\n| **CacheDurableObject** | Cache LRU persistente com TTL | Cache compartilhado entre todas as requisições globalmente |\n| **RateLimiterDurableObject** | Rate limiting com token bucket | Limites de taxa distribuídos e precisos |\n| **CircuitBreakerDurableObject** | Circuit breaker pattern (CLOSED/OPEN/HALF_OPEN) | Proteção contra falhas em cascata da API |\n| **MetricsDurableObject** | Métricas agregadas e analytics | Observabilidade em tempo real de todas as requisições |\n\n**Por que Durable Objects?**\n- 🔄 **Estado persistente** entre todas as requisições Workers\n- 🌍 **Consistência global** através de todos os 300+ data centers\n- ⚡ **Performance** com cache compartilhado e circuit breaker distribuído\n- 📊 **Métricas precisas** agregadas de todas as instâncias Workers\n\n#### 📋 Pré-requisitos\n\n1. **Conta Cloudflare** com acesso a Durable Objects (plano Workers Paid - $5/mês)\n2. **Wrangler CLI** instalado\n\n```bash\nnpm install -g wrangler\nwrangler login\n```\n\n#### 🚀 Deploy Passo a Passo\n\n**1. Build do projeto:**\n\n```bash\nnpm run build\n```\n\nIsso compila TypeScript para JavaScript e gera:\n- `build/workers/index.js` - Entry point do Worker\n- `build/durable-objects/*.js` - Código dos Durable Objects\n\n**2. Deploy inicial (development):**\n\n```bash\nnpm run deploy:workers\n# ou manualmente:\nwrangler deploy --env development\n```\n\n**3. Deploy para produção:**\n\n```bash\nnpm run deploy:workers:production\n# ou manualmente:\nwrangler deploy --env production\n```\n\n**4. Verificar deployment:**\n\n```bash\n# Ver status dos Durable Objects\nwrangler deployments list\n\n# Logs em tempo real\nwrangler tail\n```\n\n#### 🔧 Configuração (`wrangler.toml`)\n\n```toml\nname = \"mcp-senado\"\nmain = \"build/workers/index.js\"\ncompatibility_date = \"2024-01-01\"\ncompatibility_flags = [\"nodejs_compat\"]\n\n# Durable Objects Bindings\n[[durable_objects.bindings]]\nname = \"CACHE\"\nclass_name = \"CacheDurableObject\"\nscript_name = \"mcp-senado\"\n\n[[durable_objects.bindings]]\nname = \"RATE_LIMITER\"\nclass_name = \"RateLimiterDurableObject\"\nscript_name = \"mcp-senado\"\n\n[[durable_objects.bindings]]\nname = \"CIRCUIT_BREAKER\"\nclass_name = \"CircuitBreakerDurableObject\"\nscript_name = \"mcp-senado\"\n\n[[durable_objects.bindings]]\nname = \"METRICS\"\nclass_name = \"MetricsDurableObject\"\nscript_name = \"mcp-senado\"\n\n# Migrations (necessário para criar DOs)\n[[migrations]]\ntag = \"v1\"\nnew_classes = [\"CacheDurableObject\", \"RateLimiterDurableObject\", \"CircuitBreakerDurableObject\", \"MetricsDurableObject\"]\n\n# Variáveis de ambiente\n[vars]\nMCP_SERVER_NAME = \"mcp-senado\"\nMCP_SERVER_VERSION = \"1.0.0\"\nSENADO_API_BASE_URL = \"https://legis.senado.leg.br/dadosabertos\"\nSENADO_API_TIMEOUT = \"30000\"\n\n# Cache\nMCP_CACHE_ENABLED = \"true\"\nMCP_CACHE_TTL = \"300000\" # 5 minutos\n\n# Rate Limiting\nMCP_RATE_LIMIT_ENABLED = \"true\"\nMCP_RATE_LIMIT_MAX_TOKENS = \"30\"\nMCP_RATE_LIMIT_REFILL_RATE = \"0.5\" # 0.5 tokens/segundo\n\n# Circuit Breaker\nMCP_CIRCUIT_BREAKER_ENABLED = \"true\"\nMCP_CIRCUIT_BREAKER_THRESHOLD = \"5\" # Falhas para abrir\nMCP_CIRCUIT_BREAKER_TIMEOUT = \"60000\" # 1 minuto\n\n# Logging\nMCP_LOG_LEVEL = \"INFO\"\n\n# Ambientes\n[env.development]\nname = \"mcp-senado-dev\"\nvars = { ENVIRONMENT = \"development\" }\n\n[env.production]\nname = \"mcp-senado-prod\"\nvars = { ENVIRONMENT = \"production\" }\n# Descomentar e configurar sua rota:\n# route = \"mcp-senado.seudominio.com/*\"\n```\n\n#### 🧪 Desenvolvimento Local\n\n```bash\n# Iniciar servidor de desenvolvimento com Durable Objects\nnpm run dev:workers\n\n# Servidor estará disponível em:\n# http://localhost:8787\n```\n\n**Testando endpoints:**\n\n```bash\n# Health check\ncurl http://localhost:8787/health\n\n# Listar ferramentas MCP\ncurl http://localhost:8787/v1/tools/list\n\n# Invocar ferramenta\ncurl -X POST http://localhost:8787/v1/tools/invoke \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"get_senator\",\n \"arguments\": {\"codigo\": \"5012\"}\n }'\n\n# Métricas (do MetricsDurableObject)\ncurl http://localhost:8787/v1/metrics/global\n```\n\n#### 📊 Monitoramento de Durable Objects\n\n**1. Métricas globais:**\n```bash\ncurl https://mcp-senado-prod.seu-worker.workers.dev/v1/metrics/global\n```\n\n**2. Estatísticas de cache:**\n```bash\ncurl https://mcp-senado-prod.seu-worker.workers.dev/v1/cache/stats\n```\n\n**3. Status do circuit breaker:**\n```bash\ncurl https://mcp-senado-prod.seu-worker.workers.dev/v1/circuit-breaker/stats\n```\n\n**4. Rate limiter status:**\n```bash\ncurl https://mcp-senado-prod.seu-worker.workers.dev/v1/rate-limiter/stats\n```\n\n#### 🎯 Boas Práticas\n\n1. **Sempre faça build antes de deploy:**\n ```bash\n npm run build && npm run deploy:workers\n ```\n\n2. **Teste localmente antes de produção:**\n ```bash\n npm run dev:workers\n # Testar thoroughly\n npm run deploy:workers # Deploy em dev primeiro\n ```\n\n3. **Monitor logs em produção:**\n ```bash\n wrangler tail --env production\n ```\n\n4. **Use variáveis de ambiente corretas para cada ambiente:**\n - Development: mais logs, cache TTL menor\n - Production: logs INFO/WARN, cache TTL otimizado\n\n#### 💰 Custos\n\n**Cloudflare Workers + Durable Objects:**\n\n| Recurso | Free Tier | Paid Plan ($5/mês) |\n| ------------------- | ---------------- | ------------------ |\n| Workers Requests | 100.000/dia | 10M incluídos |\n| CPU Time | 10ms/req | 50ms/req |\n| **Durable Objects** | ❌ Não disponível | ✅ Incluído |\n| DO Requests | - | 1M incluídos |\n| DO Storage | - | 1GB incluído |\n\n**Estimativa de custos para 1M requisições/mês:**\n- Workers: ~$0-5 (dependendo do uso)\n- Durable Objects: ~$0-5 (storage + requests)\n- **Total: ~$5-10/mês** para tráfego moderado\n\n#### 🔐 Segurança\n\n**Secrets (valores sensíveis):**\n\n```bash\n# Definir API key (opcional)\nwrangler secret put MCP_API_KEY --env production\n\n# Definir tokens de autenticação\nwrangler secret put WORKERS_AUTH_TOKEN --env production\n```\n\n**Habilitar autenticação no Worker:**\n\n```toml\n[env.production.vars]\nWORKERS_AUTH_ENABLED = \"true\"\n```\n\nEntão use o header `Authorization` nas requisições:\n```bash\ncurl -H \"Authorization: Bearer seu-token-aqui\" \\\n https://mcp-senado-prod.seu-worker.workers.dev/v1/tools/list\n```\n\n#### ✨ Benefícios do Deploy com Durable Objects\n\n- ⚡ **Zero cold starts** - Workers sempre quentes\n- 🌍 **Latência ultra-baixa** - 300+ data centers globalmente\n- 🔄 **Cache persistente** - Compartilhado entre todas as requisições\n- 🛡️ **Circuit breaker distribuído** - Proteção contra falhas da API do Senado\n- 📊 **Métricas precisas** - Analytics em tempo real agregadas\n- 📈 **Escalabilidade automática** - De 0 a milhões de requisições\n- 💰 **Custo otimizado** - Pague apenas pelo que usar\n- 🔐 **DDoS protection** - Incluído automaticamente\n- 🚀 **Deploy em segundos** - CI/CD integrado\n- 🧪 **Desenvolvimento local fácil** - Emulador completo de DOs\n\n---\n\n### 5️⃣ Dokploy em VPS Hostinger\n\nImplantação orquestrada pelo [Dokploy](https://dokploy.com/) em um VPS Hostinger aproveitando o mesmo `Dockerfile` e variáveis de ambiente do projeto.\n\n- ✅ Ideal para fluxos de CI/CD self-hosted com pipelines Git\n- 🔒 Mantém suporte a autenticação HTTP (`HTTP_AUTH_TOKEN`) e CORS customizado\n- ⚙️ Compatível com tempo de execução Docker ou Node dentro do Dokploy\n- 📘 Guia completo em [`docs/deployment/dokploy-hostinger.md`](./docs/deployment/dokploy-hostinger.md)\n\n---\n\n## ⚙️ Configuração\n\n### Variáveis de Ambiente\n\nCrie um arquivo `.env` na raiz do projeto:\n\n```bash\n# API do Senado Federal\nSENADO_API_BASE_URL=https://legis.senado.leg.br/dadosabertos\nSENADO_API_TIMEOUT=30000\nSENADO_API_MAX_RETRIES=3\nSENADO_API_RETRY_DELAY=1000\n\n# Servidor HTTP (opcional)\nHTTP_PORT=3000\nHTTP_HOST=0.0.0.0\nHTTP_CORS_ORIGIN=*\nHTTP_AUTH_ENABLED=false\nHTTP_AUTH_TOKEN=\nHTTP_REQUEST_TIMEOUT=30000\n\n# Transporte (stdio | http)\nMCP_TRANSPORT=http\n\n# Cache\nMCP_CACHE_ENABLED=true\nMCP_CACHE_TTL=300000\nMCP_CACHE_MAX_SIZE=1000\nMCP_CACHE_CLEANUP_INTERVAL=60000\n\n# Rate Limiting\nMCP_RATE_LIMIT_ENABLED=true\nMCP_RATE_LIMIT_TOKENS=30\nMCP_RATE_LIMIT_INTERVAL=60000\nMCP_RATE_LIMIT_REFILL_RATE=2000\n\n# Circuit Breaker\nMCP_CIRCUIT_BREAKER_ENABLED=true\nMCP_CIRCUIT_BREAKER_FAILURE_THRESHOLD=5\nMCP_CIRCUIT_BREAKER_SUCCESS_THRESHOLD=2\nMCP_CIRCUIT_BREAKER_TIMEOUT=60000\n\n# Logging\nMCP_LOG_LEVEL=info # debug | info | warn | error\nMCP_LOG_FORMAT=json # json | text\nMCP_LOG_MASK_PII=true\n\n# Ambiente\nNODE_ENV=production # development | production | test\n```\n\n### Configuração Avançada\n\n**Performance:**\n\n```bash\n# Cache agressivo (ideal para dados que mudam pouco)\nMCP_CACHE_TTL=3600000 # 1 hora em ms\nMCP_CACHE_MAX_SIZE=5000 # Mais entradas\n\n# Rate limiting relaxado (para uso interno)\nMCP_RATE_LIMIT_TOKENS=100\nMCP_RATE_LIMIT_INTERVAL=60000\n```\n\n**Segurança:**\n\n```bash\n# Produção segura\nHTTP_AUTH_ENABLED=true\nHTTP_AUTH_TOKEN=token-forte-aqui\nHTTP_CORS_ORIGIN=https://meu-dominio.com\nMCP_LOG_MASK_PII=true\n```\n\n**Debug:**\n\n```bash\n# Modo de desenvolvimento\nNODE_ENV=development\nMCP_LOG_LEVEL=debug\nMCP_LOG_FORMAT=text\nMCP_CACHE_ENABLED=false # Facilita debug\n```\n\n---\n\n## 💡 Exemplos de Uso\n\n### Exemplo 1: Consultar Senadores\n\n**Prompt para IA:**\n```\n\"Liste todos os senadores do estado de São Paulo na legislatura atual\"\n```\n\n**Resposta esperada:**\n- Nome completo de cada senador\n- Partido político\n- Telefones e emails de contato\n- Período do mandato\n\n### Exemplo 2: Pesquisar Propostas\n\n**Prompt para IA:**\n```\n\"Busque propostas legislativas sobre educação que estão tramitando\"\n```\n\n**Resultado:**\n- Lista de PLs (Projetos de Lei)\n- Ementa e descrição\n- Status de tramitação\n- Autores\n\n### Exemplo 3: Acompanhar Votações\n\n**Prompt para IA:**\n```\n\"Mostre as votações do Senado nos últimos 7 dias e como cada senador votou\"\n```\n\n**Informações retornadas:**\n- Data e hora da votação\n- Matéria votada\n- Resultado (aprovado/rejeitado)\n- Votos individuais por senador\n- Orientação das bancadas\n\n### Exemplo 4: Análise de Comissões\n\n**Prompt para IA:**\n```\n\"Quais comissões permanentes estão ativas e quem são os presidentes?\"\n```\n\n**Dados fornecidos:**\n- Nome da comissão\n- Sigla\n- Presidente atual\n- Vice-presidente\n- Número de membros\n\n### Exemplo 5: Uso via API HTTP\n\n```bash\n# Consultar votações recentes\ncurl -X POST http://localhost:3000/api/tools/votacoes_listar \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"dataInicio\": \"2024-01-01\",\n \"dataFim\": \"2024-12-31\",\n \"pagina\": 1,\n \"itensPorPagina\": 10\n }'\n\n# Detalhes de um senador\ncurl -X POST http://localhost:3000/api/tools/senador_detalhes \\\n -H \"Content-Type: application/json\" \\\n -d '{\"codigo\": 5012}'\n\n# Propostas por tipo\ncurl -X POST http://localhost:3000/api/tools/materias_pesquisar \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"tipo\": \"PL\",\n \"ano\": \"2024\",\n \"tramitando\": true\n }'\n```\n\n---\n\n## 📚 Documentação\n\n### Documentação Oficial\n\n- **[README em Inglês](./README.en.md)** - Documentação em inglês\n- **[Guia de Contribuição](./CONTRIBUTING.md)** - Como contribuir com o projeto\n- **[Código de Conduta](./CODE_OF_CONDUCT.md)** - Normas da comunidade\n- **[Segurança](./SECURITY.md)** - Política de segurança\n- **[Changelog](./CHANGELOG.md)** - Histórico de versões\n- **[Roadmap](./ROADMAP.md)** - Planejamento futuro\n\n### Recursos Externos\n\n- **[API Dados Abertos do Senado](https://legis.senado.leg.br/dadosabertos/)** - Documentação oficial da API\n- **[Model Context Protocol](https://modelcontextprotocol.io/)** - Especificação MCP\n- **[TypeScript](https://www.typescriptlang.org/)** - Documentação TypeScript\n- **[Vitest](https://vitest.dev/)** - Framework de testes\n\n### Suporte e Comunidade\n\n- 🐛 **Issues**: [GitHub Issues](https://github.com/cristianoaredes/mcp-senado/issues)\n- 💬 **Discussões**: [GitHub Discussions](https://github.com/cristianoaredes/mcp-senado/discussions)\n- 📧 **Email**: Contato com mantenedores\n- 🌟 **Star no GitHub**: Mostre seu apoio!\n\n---\n\n## 🤝 Contribuindo\n\nContribuições são muito bem-vindas! Este é um projeto open-source mantido pela comunidade.\n\n### Como Contribuir\n\n1. **Fork** o repositório\n2. Crie uma **branch** para sua feature (`git checkout -b feature/minha-feature`)\n3. **Commit** suas mudanças (`git commit -m 'feat: adiciona nova feature'`)\n4. **Push** para a branch (`git push origin feature/minha-feature`)\n5. Abra um **Pull Request**\n\n### Diretrizes\n\n- ✅ Escreva testes para novas funcionalidades\n- ✅ Mantenha cobertura de testes > 70%\n- ✅ Siga o style guide TypeScript\n- ✅ Documente alterações no código\n- ✅ Use commits semânticos (conventional commits)\n- ✅ Atualize documentação quando necessário\n\n### Áreas que Precisam de Ajuda\n\n- 📝 Documentação de ferramentas específicas\n- 🧪 Testes adicionais (E2E, integração)\n- 🌍 Traduções (inglês, espanhol)\n- 🎨 Exemplos de uso\n- 🐛 Correção de bugs\n- ⚡ Otimizações de performance\n\nVeja [CONTRIBUTING.md](./CONTRIBUTING.md) para guia completo e o manual resumido em [AGENTS.md](./AGENTS.md) para agentes MCP ou contribuintes que precisam de uma visão rápida das diretrizes.\n\n---\n\n## 🏗️ Arquitetura\n\n### Estrutura do Projeto\n\n```\nmcp-senado/\n├── lib/ # Código fonte\n│ ├── adapters/ # Adaptadores de transporte\n│ │ ├── http.ts # Adaptador HTTP/REST\n│ │ └── workers.ts # Adaptador Cloudflare Workers\n│ ├── bin/ # Entry points CLI\n│ │ ├── mcp-senado.ts # stdio (MCP)\n│ │ └── mcp-senado-http.ts # HTTP server\n│ ├── config/ # Configuração\n│ ├── core/ # Lógica core MCP\n│ │ ├── mcp-server.ts # Servidor MCP principal\n│ │ ├── tools.ts # Registry de ferramentas\n│ │ ├── validation.ts # Validação com Zod\n│ │ └── errors.ts # Tratamento de erros\n│ ├── infrastructure/ # Infraestrutura\n│ │ ├── cache.ts # Cache LRU\n│ │ ├── circuit-breaker.ts\n│ │ ├── http-client.ts # Cliente HTTP\n│ │ ├── logger.ts # Logging estruturado\n│ │ └── rate-limiter.ts # Rate limiting\n│ ├── tools/ # Implementação das ferramentas\n│ │ ├── reference-tools.ts\n│ │ ├── senator-tools.ts\n│ │ ├── proposal-tools.ts\n│ │ ├── voting-tools.ts\n│ │ ├── committee-tools.ts\n│ │ ├── party-tools.ts\n│ │ └── session-tools.ts\n│ ├── types/ # Definições TypeScript\n│ └── workers/ # Cloudflare Workers\n├── test/ # Testes\n│ ├── core/ # Testes unitários core\n│ ├── e2e/ # Testes E2E\n│ ├── infrastructure/ # Testes infra\n│ └── integration/ # Testes integração\n├── .github/workflows/ # CI/CD\n└── docker/ # Docker configs\n```\n\n### Stack Tecnológica\n\n- **Runtime**: Node.js 18+\n- **Linguagem**: TypeScript 5.7+ (strict mode)\n- **Framework MCP**: @modelcontextprotocol/sdk\n- **HTTP Server**: Express 5.x\n- **Validação**: Zod\n- **Testes**: Vitest (211 testes, 73% coverage)\n- **Build**: TypeScript Compiler\n- **Deploy**: Docker, Cloudflare Workers\n- **CI/CD**: GitHub Actions\n\n---\n\n## 📈 Status do Projeto\n\n### Métricas\n\n- ✅ **211 testes** passando (2 skipped)\n- ✅ **73% cobertura** de código\n- ✅ **56 ferramentas** implementadas\n- ✅ **7 categorias** de dados\n- ✅ **4 modos** de deployment\n- ✅ **0 vulnerabilidades** de segurança\n\n### Versão Atual\n\n**v0.1.0** - Primeira versão pública\n- Core MCP server completo\n- 56 ferramentas funcionais\n- 4 adaptadores de transporte\n- Documentação completa\n- CI/CD configurado\n\n### Próximos Passos\n\n- [ ] Publicação no NPM oficial\n- [ ] Suporte a webhooks do Senado\n- [ ] Interface web de demonstração\n- [ ] Expansão para Câmara dos Deputados\n- [ ] SDK JavaScript/TypeScript\n- [ ] Integração com mais assistentes de IA\n\nVeja [ROADMAP.md](./ROADMAP.md) para planejamento completo.\n\n---\n\n## 📄 Licença\n\nEste projeto está licenciado sob a **MIT License** - veja o arquivo [LICENSE](./LICENSE) para detalhes.\n\n### Termos\n\n- ✅ Uso comercial permitido\n- ✅ Modificação permitida\n- ✅ Distribuição permitida\n- ✅ Uso privado permitido\n- ⚠️ Sem garantias\n- ⚠️ Limitação de responsabilidade\n\n---\n\n## 🙏 Agradecimentos\n\n- **Senado Federal** - Pela API de Dados Abertos\n- **Anthropic** - Pelo Model Context Protocol\n- **Comunidade Open Source** - Por tornar isso possível\n- **Contribuidores** - Obrigado por cada PR e issue!\n\n---\n\n## 📞 Contato\n\n- **GitHub**: [@cristianoaredes](https://github.com/cristianoaredes)\n- **Issues**: [Reportar bug ou sugerir feature](https://github.com/cristianoaredes/mcp-senado/issues)\n- **Discussions**: [Fórum da comunidade](https://github.com/cristianoaredes/mcp-senado/discussions)\n\n---\n\n
\n Feito com ❤️ para a transparência e democracia brasileira \n Dados abertos • Código aberto • Democracia aberta\n