Skip to content
Back to search

meli-agent-service

Servicio y MCP Server de Mercado Libre con gobernanza Spec-First y arquitectura segura para agentes de IA

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jmrodev--meli-agent-service/badge.svg)](/listings/jmrodev--meli-agent-service)

HTML

<a href="/listings/jmrodev--meli-agent-service"><img src="/api/listings/jmrodev--meli-agent-service/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 145 lines
  1. # 🛍️ Mercado Libre Agent Service & MCP Bridge
  2. Servicio backend y servidor MCP (**Model Context Protocol**) de alto rendimiento para interactuar con la **API de Mercado Libre**. Construido bajo los lineamientos académicos de **EDI 3 (TECDA 3º año)**, la metodología **Spec-First** de **Chelo-Harness** y las directivas de seguridad **OWASP Top 10 for LLM Applications 2025**.
  3. ---
  4. ## 🎯 Objetivo del Proyecto
  5. Permitir que agentes de Inteligencia Artificial (Antigravity, Claude Code, OpenCode o microservicios autónomos) consulten e interactúen con la plataforma de Mercado Libre de forma:
  6. 1. **Tipada y determinista:** Validaciones estrictas con esquemas **Zod**.
  7. 2. **Defensiva contra Prompt Injections:** Encapsulamiento de respuestas externas no confiables en tags XML pasivos (`<mercadolibre_item>`).
  8. 3. **Resiliente y controlada:** Timeouts defensivos (15s), reintentos automáticos con backoff exponencial y jitter ante errores `429` (Rate Limit) o `5xx`.
  9. 4. **Desacoplada:** Opera como microservicio HTTP independiente (Fastify) y como servidor MCP sobre `stdio`.
  10. ---
  11. ## 🏛️ Arquitectura de Referencia (5 Capas EDI 3 / OWASP LLM)
  12. ```
  13. ┌────────────────────────────────────────────────────────┐
  14. │ Agente IA / Usuario / Microservicio │
  15. │ (Antigravity, Claude, WhatsApp) │
  16. └───────────────────────────┬────────────────────────────┘
  17. │
  18. ▼
  19. ┌────────────────────────────────────────────────────────────────────────┐
  20. │ meli-agent-service │
  21. │ │
  22. │ [Capa 1: Entrada] Sanitización de queries y límites con Zod │
  23. │ [Capa 2: Control] Fastify Rate Limit (100 req/min) + CORS │
  24. │ [Capa 3: Auth] OAuth 2.0 (Token exchange, refresh automático) │
  25. │ [Capa 4: Resiliencia] Timeouts duros (15s) + Backoff exponencial │
  26. │ [Capa 5: Salida] Aislamiento en XML pasivo para evitar inyecciones │
  27. └──────────────┬──────────────────────────────────────────┬──────────────┘
  28. │ │
  29. ▼ ▼
  30. ┌──────────────────────────────┐ ┌──────────────────────────────┐
  31. │ Servidor MCP (stdio) │ │ API de Mercado Libre │
  32. │ - meli_search_items │ │ (https://api.mercadolibre) │
  33. │ - meli_get_item │ │ - MLA (Argentina) │
  34. │ - meli_auth_status │ │ - Scopes: read / offline │
  35. └──────────────────────────────┘ └──────────────────────────────┘
  36. ```
  37. ---
  38. ## 🛠️ Herramientas MCP Disponibles
  39. | Herramienta | Parámetros | Modo | Descripción |
  40. | :--- | :--- | :---: | :--- |
  41. | **`meli_search_items`** | `query` (str, req), `limit` (int, 1-50), `siteId` (str, default MLA) | Lectura | Busca publicaciones en Mercado Libre y devuelve lista estructurada en XML. |
  42. | **`meli_get_item`** | `itemId` (str, ej: `MLA1412345678`) | Lectura | Consulta especificaciones, precio, stock, condición y garantía de un ítem. |
  43. | **`meli_auth_status`** | Ninguno | Diagnóstico | Informa si el servicio posee un `access_token` activo y el `user_id` vinculado. |
  44. ---
  45. ## 🚀 Inicio Rápido
  46. ### 1. Requisitos
  47. - Node.js >= 20
  48. - pnpm >= 10
  49. ### 2. Instalación y Build
  50. ```bash
  51. git clone https://github.com/jmrodev/meli-agent-service.git
  52. cd meli-agent-service
  53. pnpm install
  54. pnpm build
  55. ```
  56. ### 3. Configuración de Entorno (`.env`)
  57. Crea un archivo `.env` en la raíz (opcional para modo búsqueda básica, requerido para operaciones con cuenta):
  58. ```env
  59. PORT=3000
  60. HOST=0.0.0.0
  61. MELI_CLIENT_ID="tu_app_id"
  62. MELI_CLIENT_SECRET="tu_client_secret"
  63. MELI_REDIRECT_URI="http://localhost:3000/api/v1/auth/callback"
  64. ```
  65. ### 4. Ejecución del Servidor HTTP
  66. ```bash
  67. pnpm start
  68. # o en desarrollo:
  69. pnpm dev
  70. ```
  71. Verifica la disponibilidad:
  72. ```bash
  73. curl http://localhost:3000/health
  74. # {"status":"ok","uptime":1.23}
  75. ```
  76. ---
  77. ## 🤖 Conexión con Asistentes de IA (MCP)
  78. Agrega el servidor en el archivo de configuración MCP (`mcp_config.json` de Antigravity / Claude Desktop / OpenCode):
  79. ```json
  80. {
  81. "mcpServers": {
  82. "mercadolibre": {
  83. "command": "node",
  84. "args": [
  85. "/home/jmro/Documents/Development/meli-agent-service/dist/cli.js"
  86. ],
  87. "env": {
  88. "MELI_CLIENT_ID": "tu_client_id",
  89. "MELI_CLIENT_SECRET": "tu_client_secret"
  90. }
  91. }
  92. }
  93. }
  94. ```
  95. ---
  96. ## 🧪 Pruebas y Gobernanza (Chelo-Harness & Breaker)
  97. Este repositorio aplica la metodología **Spec-First** donde [`openapi.yaml`](./openapi.yaml) es el contrato único de verdad.
  98. ### Pruebas de Contrato (Hurl)
  99. ```bash
  100. # Validar contratos de API con Hurl
  101. hurl --test tests/000_health.hurl tests/001_adversarial_contract.hurl
  102. ```
  103. ### Suite Adversarial (Breaker)
  104. ```bash
  105. # Ejecutar suite de testing adversarial (EDI 3)
  106. pnpm test
  107. ```
  108. Verifica las siguientes invariantes críticas:
  109. - Rechazo determinista con Zod ante tokens falsificados o malformados.
  110. - Delimitación XML pasiva ante inyecciones de prompt o scripts en títulos externos.
  111. - Cero divulgación de secretos criptográficos en las herramientas MCP.
  112. ---
  113. ## 📚 Historias de Usuario
  114. La documentación formal de requisitos y criterios de aceptación Gherkin se encuentra en:
  115. - [`docs/stories/US001_consulta_productos_mcp.md`](./docs/stories/US001_consulta_productos_mcp.md)
  116. - [`docs/stories/US002_oauth_vendedor_seguro.md`](./docs/stories/US002_oauth_vendedor_seguro.md)
  117. - [`docs/stories/US003_blindaje_adversarial_y_resiliencia.md`](./docs/stories/US003_blindaje_adversarial_y_resiliencia.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.