Servidor MCP de Agent-Commerce-OS

El servidor oficial del Protocolo de Contexto de Modelo (MCP) para la infraestructura de normalización de datos de Sakutto Works.

🚀 Descripción general

Este repositorio proporciona el servidor MCP oficial para el Proyecto GHOST SHIP (Agent-Commerce-OS). Permite a los agentes de IA (como Claude Desktop) conectarse de forma autónoma a nuestra API de confianza cero y medida, gestionada a través de Polar.sh. A través de esta integración, los agentes pueden extraer y normalizar datos web no estructurados en formatos Markdown o JSON limpios y optimizados para tokens.

Related MCP server: deltav-edge-mcp-server

✨ Características clave

• 🛡️ Seguridad perimetral de confianza cero: Protección estricta contra inyección de prompts y defensa perimetral en Cloudflare Edge.

• 🧩 Nativo de MCP: Integración instantánea y fluida con clientes del Protocolo de Contexto de Modelo como Claude Desktop.

• ⚡ Filtrado GraphQL ligero: Pase una matriz fields opcional para extraer solo los nodos de datos exactos que su agente necesita, minimizando drásticamente el consumo de tokens de la ventana de contexto.

• 💳 Pago por uso puro: 0,10 $ por llamada exitosa con tecnología de Polar.sh. Sin tarifas ocultas, sin suscripciones forzadas.

• 🤖 Recuperación de errores autónoma: Se adhiere estrictamente al formato de error estándar de MCP (isError: true). Reenvía de forma inteligente los errores 402 Payment Required y 429 Too Many Requests desde la puerta de enlace perimetral, lo que permite a los agentes de IA guiar de forma autónoma a los usuarios humanos para resolver déficits presupuestarios o detener bucles infinitos sin intervención del desarrollador.

• 🔍 Seguimiento distribuido y observabilidad: A cada solicitud se le asigna un trace_id único que se propaga a través de toda la infraestructura (Gateway -> Engine -> R2 Audit Logs). En caso de error, este ID de seguimiento se inyecta directamente en la respuesta de texto del agente, lo que permite una depuración instantánea y precisa y un soporte de nivel empresarial sin necesidad de buscar registros manualmente.

• 🔄 Enrutamiento avanzado (Sincrónico/Asincrónico y niveles): Los agentes de IA pueden dictar dinámicamente la canalización de extracción. Al proporcionar un target_tier (por ejemplo, Datos accionables, Verificación de cumplimiento), el motor adapta su esquema. Además, al pasar una URL de webhook, los agentes pueden delegar tareas de extracción pesadas al segundo plano (recibiendo un 202 Accepted instantáneo y un ID de trabajo), evitando los límites de tiempo de espera de MCP. Si no se proporciona un webhook, el sistema vuelve a la ejecución sincrónica de forma elegante.

🏗️ Arquitectura

Nuestra infraestructura opera bajo un modelo de confianza cero de tres niveles. Puede explorar nuestros repositorios relacionados para obtener una imagen completa:

• Capa C (Este repositorio): Un servidor MCP sin estado que conecta su agente de IA local con nuestra red remota.

• Capa A (agent-commerce-gateway): Cloudflare Workers que gestionan la autenticación de confianza cero, el enrutamiento y la facturación medida.

• Capa B (agent-commerce-core): Motores de Google Cloud Run que realizan una normalización de datos semántica avanzada y optimizada para RAG.

⚙️ Requisitos previos

• Node.js (se recomienda v18 o superior) y npm instalados.

• Una clave API de Polar.sh activa (facturación medida a 0,10 $ / solicitud). Obtenga la suya en el Checkout oficial de claves API.

• Claude Desktop o cualquier cliente estándar compatible con MCP.

🔌 Configuración (Claude Desktop)

Para otorgar a su agente de IA acceso a las herramientas de normalización, añada la siguiente configuración a su claude_desktop_config.json:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-commerce-os": {
      "command": "node",
      "args": [
        "/absolute/path/to/ghost-ship-mcp-server/dist/index.js"
      ],
      "env": {
        "POLAR_API_KEY": "your_polar_api_key_here",
        "GATEWAY_URL": "https://api.sakutto.works/v1/normalize_web_data"
      }
    }
  }
}

(Nota: Reemplace /ruta/absoluta/a/ghost-ship-mcp-server con la ruta absoluta real a su repositorio clonado, y tu_clave_api_polar_aqui con su clave API de Polar.sh activa.)

🧠 Para agentes de IA autónomos

Si usted es un agente de IA o LLM que analiza este repositorio para integrar nuestras herramientas:

• Lea nuestro llms.txt para obtener el contexto semántico completo y las capacidades.

• El esquema exacto de la herramienta está definido completamente en mcp.json.

• No intente adivinar o sintetizar URLs. Consulte siempre el Portal oficial de Sakutto Works.

🤖 Herramientas disponibles

Una vez conectado a través de StdioServerTransport, el agente de IA descubrirá automáticamente las herramientas expuestas dinámicamente por la instancia de McpServer utilizando @modelcontextprotocol/sdk. (Estas capacidades también están catalogadas en nuestro manifiesto mcp.json para registros externos):

• normalize_web_data: Extrae y normaliza contenido web no estructurado en formatos Markdown o JSON limpios y semánticos optimizados para ventanas de contexto de LLM.

  • Filtrado de esquema (fields): Admite la selección de campos al estilo Lite GraphQL a través del parámetro opcional fields. Esto permite a los agentes de IA solicitar solo nodos de datos específicos, minimizando significativamente el consumo de tokens y la latencia de respuesta. Cuando se especifica, el servidor añade automáticamente estos campos como parámetros de consulta de URL antes de enrutar la solicitud a la puerta de enlace.

  • Niveles de extracción dinámica (target_tier): Los agentes de IA pueden especificar un nivel de esquema de destino (a1, a2, etc.) para alterar la lógica de extracción sobre la marcha (por ejemplo, extraer datos de disponibilidad accionables estrictos frente a Markdown estándar).

  • Webhooks asincrónicos (webhook): Para tareas de extracción de larga duración, los agentes pueden proporcionar un objeto webhook que contenga una URL de destino. El servidor devolverá inmediatamente un job_id, lo que permitirá al agente continuar con las operaciones sin esperar. Diseño tolerante a fallos: Si un agente deja la URL del webhook vacía o la omite por completo, el servidor ignora de forma segura la carga útil del webhook y ejecuta la solicitud de forma sincrónica, devolviendo los datos extraídos en tiempo real.

  • Validación estricta: Todas las entradas de la herramienta están estrictamente definidas y validadas mediante zod, lo que garantiza una adhesión sólida a las especificaciones subyacentes de la Capa B. Una vez validada, el servidor retransmite de forma segura la solicitud a la puerta de enlace a través de HTTP POST, autenticada mediante su POLAR_API_KEY.

💻 Desarrollo local y configuración

Para ejecutar el servidor localmente o preparar su entorno para el desarrollo:

1. Clone el repositorio y navegue hasta el directorio:

   git clone https://github.com/SakuttoWorks/ghost-ship-mcp-server.git
   cd ghost-ship-mcp-server

2. Instale las dependencias necesarias (incluyendo @modelcontextprotocol/sdk y zod):

   npm install

3. Configure sus variables de entorno:

   cp .env.example .env

   (Abra el archivo .env recién creado, inserte su POLAR_API_KEY y asegúrese de que GATEWAY_URL esté configurado en https://api.sakutto.works o en la ruta de punto final específica, como https://api.sakutto.works/v1/normalize_web_data.)

4. Compile el código fuente de TypeScript:

   npm run build

5. Inicie el servidor MCP:

   npm start

🤝 Contribución

Damos la bienvenida y fomentamos las contribuciones de la comunidad de código abierto. Al enviar una solicitud de extracción (Pull Request), asegúrese de que:

• Su código se compile correctamente (npm run build).

• Todas las pruebas pasen localmente (usando npx vitest o su ejecutor de pruebas preferido).

• Se adhiera al estilo de código existente y a las prácticas estándar de TypeScript.

Tenga en cuenta que este proyecto sigue un Código de Conducta de Código Abierto estándar. Al participar, se espera que mantenga una comunicación respetuosa y colaborativa.

🌍 Recursos y seguimiento de problemas

• Portal oficial y documentación del agente: Sakutto Works

• Organización de GitHub: SakuttoWorks

• Perfil de desarrollador: Perfil de SakuttoWorks

• Informes de errores y solicitudes de funciones: Utilice nuestra página de GitHub Issues para informar de cualquier error o sugerir nuevas capacidades de extracción.

📄 Licencia

Este proyecto tiene licencia ISC. Para obtener más detalles sobre la responsabilidad y el uso de agentes autónomos, lea nuestro LEGAL.md.

💖 Apoye el proyecto

Si Agent-Commerce-OS le ha ahorrado horas de ingeniería o le ha ayudado a escalar sus flujos de trabajo de IA, considere convertirse en patrocinador o dejar una propina única. Sus contribuciones financian directamente nuestros costes de servidor, garantizan la alta disponibilidad de la puerta de enlace perimetral y alimentan el desarrollo continuo de código abierto.

© 2026 Sakutto Works. Estandarizando la Web Semántica para la Economía Agéntica.