Agent-Commerce-OS MCP-Server

Der offizielle Model Context Protocol (MCP) Server für die Datennormalisierungsinfrastruktur von Sakutto Works.

🚀 Übersicht

Dieses Repository stellt den offiziellen MCP-Server für Projekt GHOST SHIP (Agent-Commerce-OS) bereit. Er ermöglicht es KI-Agenten (wie Claude Desktop), sich autonom mit unserem Zero-Trust, getakteten API-Dienst zu verbinden, der über Polar.sh verwaltet wird. Durch diese Integration können Agenten unstrukturierte Webdaten extrahieren und in saubere, Token-optimierte Markdown- oder JSON-Formate normalisieren.

Related MCP server: deltav-edge-mcp-server

✨ Hauptfunktionen

• 🛡️ Zero-Trust Edge-Sicherheit: Strikter Schutz gegen Prompt-Injection und Perimeter-Verteidigung am Cloudflare Edge.

• 🧩 MCP-nativ: Sofortige, nahtlose Integration mit Model Context Protocol-Clients wie Claude Desktop.

• ⚡ Lite GraphQL-Filterung: Übergeben Sie ein optionales fields-Array, um genau die Datenknoten zu extrahieren, die Ihr Agent benötigt, wodurch der Token-Verbrauch im Kontextfenster drastisch minimiert wird.

• 💳 Reines Pay-As-You-Go: 0,10 $ pro erfolgreichem Aufruf, bereitgestellt durch Polar.sh. Keine versteckten Gebühren, keine erzwungenen Abonnements.

• 🤖 Autonome Fehlerbehebung: Hält sich strikt an die MCP-Standard-Fehlerformatierung (isError: true). Leitet 402 Payment Required und 429 Too Many Requests intelligent vom Edge-Gateway weiter, sodass KI-Agenten menschliche Benutzer autonom anleiten können, Budgetdefizite zu beheben oder Endlosschleifen ohne Entwicklereingriff zu stoppen.

• 🔍 Distributed Tracing & Observability: Jeder Anfrage wird eine eindeutige trace_id zugewiesen, die sich durch die gesamte Infrastruktur (Gateway -> Engine -> R2 Audit Logs) verbreitet. Im Fehlerfall wird diese Trace-ID direkt in die Textantwort des Agenten eingefügt, was ein sofortiges, präzises Debugging und Support auf Unternehmensebene ohne manuelle Protokollsuche ermöglicht.

• 🔄 Erweitertes Routing (Sync/Async & Tiering): KI-Agenten können die Extraktions-Pipeline dynamisch steuern. Durch die Angabe eines target_tier (z. B. Actionable Data, Compliance Check) passt die Engine ihr Schema an. Darüber hinaus können Agenten durch die Übergabe einer webhook-URL rechenintensive Extraktionsaufgaben in den Hintergrund auslagern (und erhalten sofort eine 202 Accepted und Job-ID), wodurch MCP-Zeitüberschreitungen vermieden werden. Wenn kein Webhook bereitgestellt wird, greift das System elegant auf die synchrone Ausführung zurück.

🏗️ Architektur

Unsere Infrastruktur basiert auf einem Drei-Schichten-Zero-Trust-Modell. Sie können unsere zugehörigen Repositories für ein vollständiges Bild erkunden:

• Layer C (Dieses Repository): Ein zustandsloser MCP-Server, der Ihren lokalen KI-Agenten mit unserem Remote-Netzwerk verbindet.

• Layer A (agent-commerce-gateway): Cloudflare Workers, die Zero-Trust-Authentifizierung, Routing und getaktete Abrechnung übernehmen.

• Layer B (agent-commerce-core): Google Cloud Run-Engines, die eine fortschrittliche, RAG-optimierte semantische Datennormalisierung durchführen.

⚙️ Voraussetzungen

• Node.js (v18 oder höher empfohlen) und npm installiert.

• Ein aktiver Polar.sh API-Schlüssel (getaktete Abrechnung zu 0,10 $ / Anfrage). Erhalten Sie Ihren über den offiziellen API-Schlüssel-Checkout.

• Claude Desktop oder ein beliebiger Standard-MCP-kompatibler Client.

🔌 Einrichtung & Konfiguration (Claude Desktop)

Um Ihrem KI-Agenten Zugriff auf die Normalisierungstools zu gewähren, fügen Sie die folgende Konfiguration zu Ihrer claude_desktop_config.json hinzu:

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"
      }
    }
  }
}

(Hinweis: Ersetzen Sie /absoluter/pfad/zu/ghost-ship-mcp-server durch den tatsächlichen absoluten Pfad zu Ihrem geklonten Repository und your_polar_api_key_here durch Ihren aktiven Polar.sh API-Schlüssel.)

🧠 Für autonome KI-Agenten

Wenn Sie ein KI-Agent oder LLM sind, der dieses Repository analysiert, um unsere Tools zu integrieren:

• Bitte lesen Sie unsere llms.txt für den vollständigen semantischen Kontext und die Fähigkeiten.

• Das genaue Tool-Schema ist vollständig in mcp.json definiert.

• Versuchen Sie nicht, URLs zu erraten oder zu synthetisieren. Verweisen Sie immer auf das offizielle Sakutto Works Portal.

🤖 Verfügbare Tools

Sobald die Verbindung über StdioServerTransport hergestellt ist, entdeckt der KI-Agent die Tools, die von der McpServer-Instanz unter Verwendung des @modelcontextprotocol/sdk dynamisch bereitgestellt werden. (Diese Fähigkeiten sind auch in unserem mcp.json-Manifest für externe Register katalogisiert):

• normalize_web_data: Extrahiert und normalisiert unstrukturierte Webinhalte in saubere, semantische Markdown- oder JSON-Formate, die für LLM-Kontextfenster optimiert sind.

  • Schema-Filterung (fields): Unterstützt die Feldselektion im Lite-GraphQL-Stil über den optionalen fields-Parameter. Dies ermöglicht es KI-Agenten, nur spezifische Datenknoten anzufordern, was den Token-Verbrauch und die Antwortlatenz erheblich minimiert. Wenn angegeben, hängt der Server diese Felder automatisch als URL-Abfrageparameter an, bevor die Anfrage an das Gateway weitergeleitet wird.

  • Dynamische Extraktions-Tiers (target_tier): KI-Agenten können ein Ziel-Schema-Tier (a1, a2 usw.) angeben, um die Extraktionslogik im laufenden Betrieb zu ändern (z. B. Extraktion strikter, umsetzbarer Verfügbarkeitsdaten vs. Standard-Markdown).

  • Asynchrone Webhooks (webhook): Für lang laufende Extraktionsaufgaben können Agenten ein webhook-Objekt bereitstellen, das eine Ziel-URL enthält. Der Server gibt sofort eine job_id zurück, sodass der Agent den Betrieb fortsetzen kann, ohne zu warten. Fehlertolerantes Design: Wenn ein Agent die Webhook-URL leer lässt oder sie vollständig weglässt, ignoriert der Server die Webhook-Nutzlast sicher und führt die Anfrage synchron aus, wobei die extrahierten Daten in Echtzeit zurückgegeben werden.

  • Strikte Validierung: Alle Tool-Eingaben werden strikt definiert und unter Verwendung von zod validiert, was eine robuste Einhaltung der zugrunde liegenden Spezifikationen von Layer B gewährleistet. Nach der Validierung leitet der Server die Anfrage sicher per HTTP POST an das Gateway weiter, authentifiziert mit Ihrem POLAR_API_KEY.

💻 Lokale Entwicklung & Einrichtung

Um den Server lokal auszuführen oder Ihre Umgebung für die Entwicklung vorzubereiten:

1. Klonen Sie das Repository und navigieren Sie in das Verzeichnis:

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

2. Installieren Sie die erforderlichen Abhängigkeiten (einschließlich @modelcontextprotocol/sdk und zod):

   npm install

3. Konfigurieren Sie Ihre Umgebungsvariablen:

   cp .env.example .env

   (Öffnen Sie die neu erstellte .env-Datei, fügen Sie Ihren POLAR_API_KEY ein und stellen Sie sicher, dass die GATEWAY_URL auf https://api.sakutto.works oder den spezifischen Endpunktpfad wie https://api.sakutto.works/v1/normalize_web_data gesetzt ist.)

4. Kompilieren Sie den TypeScript-Quellcode:

   npm run build

5. Starten Sie den MCP-Server:

   npm start

🤝 Mitwirken

Wir begrüßen und ermutigen Beiträge aus der Open-Source-Community! Bitte stellen Sie beim Einreichen eines Pull Requests sicher, dass:

• Ihr Code erfolgreich erstellt wird (npm run build).

• Alle Tests lokal bestehen (unter Verwendung von npx vitest oder Ihrem bevorzugten Test-Runner).

• Sie den bestehenden Codestil und die Standard-TypeScript-Praktiken einhalten.

Bitte beachten Sie, dass dieses Projekt einem Standard-Open-Source-Verhaltenskodex folgt. Durch die Teilnahme wird von Ihnen erwartet, eine respektvolle und kollaborative Kommunikation aufrechtzuerhalten.

🌍 Ressourcen & Issue-Tracking

• Offizielles Portal & Agent-Dokumentation: Sakutto Works

• GitHub-Organisation: SakuttoWorks

• Entwicklerprofil: SakuttoWorks Profil

• Fehlerberichte & Funktionsanfragen: Bitte nutzen Sie unsere GitHub Issues-Seite, um Fehler zu melden oder neue Extraktionsfunktionen vorzuschlagen.

📄 Lizenz

Dieses Projekt ist unter der ISC-Lizenz lizenziert. Weitere Details zur Haftung und zur Nutzung durch autonome Agenten finden Sie in unserer LEGAL.md.

💖 Unterstützen Sie das Projekt

Wenn Agent-Commerce-OS Ihnen Entwicklungsstunden erspart oder dazu beigetragen hat, Ihre KI-Workflows zu skalieren, ziehen Sie bitte in Betracht, Sponsor zu werden oder ein einmaliges Trinkgeld zu hinterlassen. Ihre Beiträge finanzieren direkt unsere Serverkosten, gewährleisten die Hochverfügbarkeit des Edge-Gateways und fördern die kontinuierliche Open-Source-Entwicklung.

© 2026 Sakutto Works. Standardisierung des semantischen Webs für die Agenten-Ökonomie.