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 Project GHOST SHIP (Agent-Commerce-OS) bereit. Er ermöglicht es KI-Agenten (wie Claude Desktop), sich autonom mit unserem Zero-Trust, nutzungsbasierten 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.

🏗️ Architektur

Unsere Infrastruktur basiert auf einem Drei-Schichten-Zero-Trust-Modell. Sie können unsere zugehörigen Repositories erkunden, um ein vollständiges Bild zu erhalten:

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 nutzungsbasierte Abrechnung übernehmen.
Layer B (agent-commerce-core): Google Cloud Run-Engines, die eine fortschrittliche, RAG-optimierte semantische Datennormalisierung durchführen.

⚙️ Voraussetzungen

Ein aktiver Polar.sh API-Schlüssel (nutzungsbasierte Abrechnung zu $0,10 / Anfrage). Erhalten Sie Ihren über den offiziellen API-Schlüssel-Checkout.
Claude Desktop oder ein beliebiger MCP-kompatibler Standard-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"
      }
    }
  }
}

(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, das dieses Repository analysiert, um unsere Tools zu integrieren:

Bitte lesen Sie unsere llms.txt für den vollständigen semantischen Kontext und die Funktionen.
Das exakte 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, erkennt der KI-Agent automatisch die Tools, die von der McpServer-Instanz unter Verwendung des @modelcontextprotocol/sdk dynamisch bereitgestellt werden. (Diese Funktionen sind auch in unserem mcp.json-Manifest für externe Registries 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.
- Strenge Validierung: Alle Tool-Eingaben werden streng definiert und unter Verwendung von zod validiert, um eine robuste Einhaltung der zugrunde liegenden Spezifikationen von Layer B sicherzustellen. 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:

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

Installieren Sie die erforderlichen Abhängigkeiten (einschließlich @modelcontextprotocol/sdk und zod):
```
npm install
```
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.)
Kompilieren Sie den TypeScript-Quellcode:
```
npm run build
```
Starten Sie den MCP-Server:
```
npm start
```

🤝 Mitwirken

Wir begrüßen und fördern Beiträge aus der Open-Source-Community! Wenn Sie einen Pull Request einreichen, stellen Sie bitte sicher, dass:

Ihr Code erfolgreich gebaut wird (npm run build).
Alle Tests lokal bestehen (unter Verwendung von npx vitest oder Ihrem bevorzugten Test-Runner).
Sie sich an den bestehenden Code-Stil und die Standard-TypeScript-Praktiken halten.

🌍 Ressourcen & Issue-Tracking

Offizielles Portal & Agenten-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 Entwicklungszeit erspart oder geholfen 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.

SakuttoWorks-Data-Normalizer