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 con medición, 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.

🏗️ 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

Una clave de API de Polar.sh activa (facturación medida a $0.10 / solicitud). Obtenga la suya en el Checkout oficial de claves de 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"
      }
    }
  }
}

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

🧠 Para agentes de IA autónomos

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

Por favor, lea nuestro llms.txt para obtener el contexto semántico completo y las capacidades.
El esquema exacto de la herramienta está completamente definido 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 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.
- Validación estricta: Todas las entradas de la herramienta están estrictamente definidas y validadas utilizando zod, lo que garantiza una adhesión robusta 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 utilizando su POLAR_API_KEY.

💻 Desarrollo local y configuración

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

Clone el repositorio y navegue al directorio:

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

Instale las dependencias necesarias (incluyendo @modelcontextprotocol/sdk y zod):
```
npm install
```
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.)
Compile el código fuente de TypeScript:
```
npm run build
```
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.

🌍 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 está bajo la 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 costos de servidor, garantizan la alta disponibilidad de la puerta de enlace perimetral y alimentan el desarrollo continuo de código abierto.

SakuttoWorks-Data-Normalizer