Toss Place MCP

Fragen Sie Codex nach Live-Umsätzen, Bestellungen, Menüverfügbarkeit, Tischen, Zahlungen und im POS erfassten Beständen von Toss Place POS.

Toss Place MCP ist eine Open-Source-Integration zum Selbsthosten. Ein kleiner Plugin läuft in Toss POS und synchronisiert lesbare POS-Daten sicher zu Ihrer Bridge. Codex verbindet sich über einen standardmäßigen lokalen MCP-Prozess oder den Streamable-HTTP-Endpunkt der Bridge.

[!IMPORTANT] Dieses Projekt integriert Toss Place POS, nicht Toss Payments. Toss Payments ist ein separater zukünftiger Anbieter mit anderen APIs und einer anderen Autorisierung.

Wonach Sie fragen können

• „Wie viel haben wir heute Abend verkauft, ohne offene Rechnungen?“

• „Was waren unsere meistverkauften Getränke zwischen 20 Uhr und Mitternacht?“

• „Vergleichen Sie diesen Freitag mit letztem Freitag.“

• „Zeigen Sie die stündlichen Verkäufe und sagen Sie mir, wann wir einen weiteren Barkeeper einplanen sollten.“

• „Welche Produkte sind ausverkauft oder haben weniger als 10 Einheiten?“

• „Schlüsseln Sie Karten-, Bar- und externe Zahlungen auf.“

• „Welche Tische haben derzeit offene Rechnungen?“

• „Geben Sie mir die rohe Toss-Bestellung hinter dieser Nummer.“

Der Server bietet sowohl reine POS-Werkzeuge als auch vorinterpretierte Analysen. Offene Rechnungen werden immer getrennt von den gebuchten Verkäufen ausgewiesen.

Related MCP server: lightspeed-x

So funktioniert es

Toss POS plugin ──signed HTTPS──▶ self-hosted bridge + database
                                      │
                         ┌────────────┴────────────┐
                         ▼                         ▼
                 local stdio MCP          Streamable HTTP MCP
                         │                         │
                         └──────────▶ Codex ◀─────┘

Diese Aufteilung ist wichtig, wenn Toss POS auf einem iPad oder einem Desktop-Computer im Geschäft läuft und Codex auf einem anderen Computer läuft. Docker ist nur eine bequeme Möglichkeit, die Bridge bereitzustellen; es ist nicht Teil des MCP-Protokolls und für die lokale Entwicklung nicht erforderlich.

Aktueller Plattformstatus

• Der Datenpfad basiert auf dem Toss-Place-POS-Plugin-SDK, das erfolgreich in einer echten Desktop-Sandbox-Integration eingesetzt wurde.

• Der vollständige Desktop-Pfad — Händleraktivierung, POS-Installation, einmalige Kopplung, erstmalige Synchronisierung und MCP-Abfragen zu Verkäufen/Beständen — wurde mit einem Toss-Testhändler auf macOS validiert.

• Das SDK unterstützt die Geräteplattformen Windows, macOS, Android und iOS. Dieses Projekt hat den vollständigen Installationsablauf auf einer iPad-Toss-POS-Instanz noch nicht validiert.

• Selbst gehostete Bridge-Domains müssen in der Regel zur HTTP-Allowlist/ACL des Toss-Developer-Plugins hinzugefügt werden. Dies ist der wichtigste manuelle Onboarding-Schritt; Toss Place stellt diese Integration derzeit nicht als gewöhnliches Händler-OAuth bereit.

• Ein Händler kann das GitHub-Repository derzeit nicht selbst in Toss POS installieren. Jemand mit dem erforderlichen Zugriff auf das Toss-Entwicklerportal muss das Worker-Plugin erstellen/verteilen, das Terminal und den Händler zuweisen und den Servicecode im POS eingeben. Nach dieser manuellen Installation kann Codex durch die Kopplung und MCP-Einrichtung führen.

• Lagerbestände sind nur verfügbar, wenn der Händler die Toss-Bestandsverfolgung für diesen Katalogpreis aktiviert. Andernfalls kann der MCP nur Verfügbarkeit und Ausverkaufsstatus melden.

Voraussetzungen

• Node.js 22 oder neuer

• Eine stabile HTTPS-URL, die vom Toss-POS-Gerät aus erreichbar ist, für die Nutzung mit getrennten Geräten

• Zugriff zum Erstellen oder Installieren eines Toss-Place-Developer-Plugins

• Docker und Docker Compose nur, wenn Sie die Container-Bereitstellung wählen

Schnellstart

1. Klonen und initialisieren

git clone https://github.com/danyay/toss-place-mcp.git
cd toss-place-mcp
npm install
npm run build:all
node dist/cli.js init

Die generierte .env-Datei hat den Modus 0600 und wird von Git ignoriert. Setzen Sie TOSS_MCP_PUBLIC_URL auf die stabile HTTPS-URL, die das POS-Gerät erreichen kann.

2. Die Bridge starten

Lokal:

npm run bridge

Oder mit Docker:

docker compose up -d --build

Bevor Sie das POS-Plugin installieren, geben Sie der Bridge einen stabilen HTTPS-Hostnamen. Der empfohlene Weg ist Docker plus Caddy; ein dauerhafter Cloudflare Tunnel ist hinter NAT nützlich. Befolgen Sie docs/deployment.md für Anweisungen zu DNS, Firewall, Caddyfile, Tunnel, Überprüfung und Neustart. Senden Sie Kopplungs- oder POS-Datenverkehr nicht über öffentliches unverschlüsseltes HTTP.

3. Das Toss-POS-Plugin erstellen und installieren

npm run build:plugin
npm run zip --workspace plugin

Das Upload-Artefakt ist plugin/place-mcp-bridge.zip, mit dem Toss-Einstiegspunkt unter dist/main.js innerhalb der ZIP-Datei.

Dieser Abschnitt erfordert eine Person mit Zugriff auf das Toss-Entwicklerportal. Im Toss-Entwicklerportal:

1. Erstellen Sie eine POS-Worker-Plugin-Anwendung mit dem Einstiegspunkt POS_BACKGROUND_WORKER. Halten Sie die Paket-ID konsistent mit dem hochgeladenen Bundle (place-mcp-bridge für dieses Repository).

2. Fügen Sie Ihre Bridge-Origin, z. B. https://toss-mcp.example.com, zur HTTP-ACL/Allowlist der Anwendung hinzu.

3. Laden Sie plugin/place-mcp-bridge.zip auf den Entwicklungs-/Test-Track hoch und verteilen oder stellen Sie diese Version dann auf dem Test-Track bereit. Das bloße Hochladen reicht nicht aus.

4. Registrieren Sie das POS-Terminal unter den Test-Terminal-Einstellungen der Anwendung. Verwenden Sie die Seriennummer, die in Toss POS unter Einstellungen → POS-Informationen/-Software angezeigt wird.

5. Öffnen Sie Test-Händlerverwaltung, wählen Sie den Händler aus, suchen Sie Place MCP Bridge in der Tabelle Anwendung und schalten Sie sie auf EIN. Bestätigen Sie, dass Toss die Aktualisierung als erfolgreich meldet.

6. Beenden Sie Toss POS vollständig und starten Sie es neu.

7. Öffnen Sie in Toss POS Einstellungen → Service-Integration → Mit Servicecode verbinden, geben Sie den für die Entwickleranwendung angezeigten Servicecode ein und bestätigen Sie, dass Place MCP Bridge als In Verwendung erscheint.

Sowohl die Test-Terminal-Registrierung als auch der Pro-Händler-Schalter Anwendung → EIN sind erforderlich. Das Erkennen des Servicecodes bedeutet nicht, dass der Worker für diesen Händler autorisiert ist. Aktivieren Sie ihn nur für einen Händler, dessen Eigentümer die dauerhafte schreibgeschützte Datenverbindung genehmigt hat.

Weitere Informationen zur vollständigen Klick-für-Klick-Checkliste, dem erwarteten Ergebnis nach jeder Stufe, der Fehlerdiagnose und den Grenzen des öffentlichen Händler-Onboardings finden Sie unter docs/toss-developer-setup.md.

4. Das POS koppeln

Bei laufender Bridge:

npm run pair

Geben Sie die angezeigte Bridge-URL und den Einmalcode in den Plugin-Einstellungen von Toss POS ein. Der Code läuft nach 15 Minuten ab und kann nur einmal verwendet werden. Das daraus resultierende Verbindungsgeheimnis wird im sicheren Speicher von Toss aufbewahrt; Plugin-Anfragen sind mit Zeitstempel versehen, durch Nonces geschützt und HMAC-signiert.

Die Felder befinden sich unter Einstellungen → Service-Integration → Place MCP Bridge. Speichern Sie sie und starten Sie Toss POS dann einmal vollständig neu, damit der Hintergrund-Worker geladen wird und seine erste Synchronisierung durchführt.

Überprüfen Sie die Verbindung:

npm run doctor

Die erste Verbindung lädt Bestellungen der letzten bis zu 90 Tage nach. Große Händler können später über das MCP-Tool refresh_pos_data andere Zeiträume anfordern.

5. Codex verbinden

Für einen lokalen MCP-Server über stdio:

codex mcp add toss-place \
  --env TOSS_MCP_BRIDGE_URL=http://127.0.0.1:8787 \
  --env TOSS_MCP_ACCESS_TOKEN=YOUR_LOCAL_ENV_TOKEN \
  -- npx -y toss-place-mcp mcp

Bis das Paket auf npm veröffentlicht ist, ersetzen Sie den Befehl nach -- durch den Pfad zum erstellten Repository:

node /absolute/path/to/toss-place-mcp/dist/cli.js mcp

Für entferntes Streamable HTTP fügen Sie dies zu ~/.codex/config.toml hinzu:

[mcp_servers.toss_place]
url = "https://toss-mcp.example.com/mcp"
bearer_token_env_var = "TOSS_MCP_ACCESS_TOKEN"
default_tools_approval_mode = "writes"

Exportieren Sie dann TOSS_MCP_ACCESS_TOKEN in der Umgebung, in der Codex gestartet wird. Codex-Desktop-, CLI- und IDE-Clients auf demselben Host verwenden diese Konfiguration gemeinsam. Siehe die offizielle Codex-MCP-Dokumentation.

Dieses Repository an Codex übergeben

Dies ist die vorgesehene Onboarding-Erfahrung für Nicht-Entwickler:

Installieren Sie den Toss-Place-MCP-Server aus diesem Repository. Bewahren Sie alle Anmeldedaten außerhalb von Git auf. Stellen Sie die Bridge lokal oder mit Docker bereit, helfen Sie mir, eine stabile HTTPS-URL zuzuweisen, erstellen Sie das Toss-POS-Plugin-ZIP und stoppen Sie, wenn ich das Toss-Entwicklerportal freigeben oder bedienen muss. Erstellen Sie einen Einmal-Kopplungscode, prüfen Sie, ob das POS synchronisiert, fügen Sie den MCP zu meiner Codex-Konfiguration hinzu und zeigen Sie mir dann die heutigen gebuchten Verkäufe getrennt von offenen Rechnungen.

Codex kann die lokale Installation und Überprüfung durchführen. Eine Person muss die Toss-Portal-/Geräteschritte dennoch ausführen, wenn das Konto sie erfordert.

MCP-Tools

Der MCP veröffentlicht außerdem die Ressourcen toss-place://capabilities und toss-place://data-dictionary sowie einen Prompt daily-sales-review.

Dies ist nicht jeder aufrufbare Namespace im Toss-Place-SDK. Es umfasst die schreibgeschützten Händlerdaten, die für übliche Umsatz-, Bestell-, Zahlungs-, Menü-, Tisch- und Bestandsanalysen benötigt werden. KDS-Status, Live-Entwurfsbestellungen, Geräte-/UI-Steuerungen und sämtliche Mutationen sind von v1 ausgeschlossen. Die SDK-Abdeckungsmatrix unterscheidet vollständige, teilweise, interne und nicht unterstützte Schnittstellen.

Sicherheitsmodell

Diese Version ist analyseorientiert und schreibgeschützt. Das zugrunde liegende Toss-SDK enthält Mutationen für Bestellungen, Zahlungen, Kassenbelege und Entwurfsbestellungen, diese werden jedoch absichtlich nicht als MCP-Tools bereitgestellt. Das versehentliche Stornieren einer offenen Rechnung ist keine akzeptable Standardfunktion für einen Umsatzanalyse-Server.

• Die Bridge-API und der entfernte MCP erfordern ein langes Bearer-Token.

• POS-Synchronisierungsanfragen verwenden HMAC-SHA256, Zeitstempel und Einmal-Nonces.

• Kopplungscodes sind gehasht, kurzlebig und nur einmal verwendbar.

• Geheimnisse werden über .gitignore ausgeschlossen; Beispiele enthalten nur Platzhalter.

• Die Bridge bindet standardmäßig an 127.0.0.1.

• Logs enthalten absichtlich keine Zugriffstoken oder Plugin-Geheimnisse.

Lesen Sie SECURITY.md, bevor Sie die Bridge dem Internet aussetzen.

Daten und Kennzahlen

Standardmäßig werden Tagesgrenzen mit Asia/Seoul verwendet. „Gebuchte Verkäufe“ bezeichnet die Summe von Toss chargePrice.chargePriceValue für abgeschlossene, nicht stornierte Bestellungen. Aktuelle Tischrechnungen werden separat angezeigt, selbst wenn eine Rechnung vor dem angeforderten Verkaufszeitraum geöffnet wurde; sie werden niemals als gebuchte Verkäufe gezählt. Rohe signierte Rabattfelder bleiben erhalten, da Erstattungen und Stornierungsbuchungen deren Vorzeichen beeinflussen können.

Siehe docs/api-coverage.md und docs/architecture.md.

Datenbank

SQLite ist die Standardeinstellung:

TOSS_MCP_DATABASE_URL=sqlite:./data/toss-place.sqlite

PostgreSQL verwendet dasselbe Repository:

TOSS_MCP_DATABASE_URL=postgresql://user:password@localhost:5432/toss_mcp

Die Datenbank enthält Händlerverkaufsdaten und Verbindungsgeheimnisse für verschlüsselte Übertragungen. Schützen Sie sie wie andere Produktions-POS-Daten und sichern Sie sie gemäß Ihrer eigenen Aufbewahrungsrichtlinie.

Entwicklung

npm install
npm run check
npm run build:all

Tests verwenden synthetische Fixtures. Anmeldedaten für die Live-Integration dürfen nur über ignorierte Umgebungsvariablen bereitgestellt werden und sind für die normale Testsuite nie erforderlich.

Die macOS-Sandbox-Test-App und alle lokalen POS-Daten sind von Git ausgeschlossen. Kopieren Sie niemals eine Händler-Bridge-URL, ein Zugriffstoken, einen Kopplungscode, eine Datenbank oder ein Toss-POS-Anwendungsbundle in einen Commit.

Roadmap

• iPad-Bereitstellung bei einem echten Händler validieren und dokumentieren

• Von Toss geprüftes/veröffentlichtes Plugin-Onboarding, sofern die Plattform es erlaubt

• Konfigurierbare Aufbewahrung und inkrementelle Checkpoints für langfristige Backfills

• PostgreSQL-Integrationstests in CI

• Optionaler OAuth für den entfernten MCP-Endpunkt

• Separater Toss-Payments-Anbieter

• Sorgfältig abgesicherte operative Werkzeuge erst, nachdem ein explizites Genehmigungs- und Prüfmodell existiert

Lizenz und Marken

MIT. Toss und Toss Place sind Marken ihrer jeweiligen Inhaber. Dieses Community-Projekt ist, sofern nicht anders angegeben, weder mit Toss verbunden noch von Toss unterstützt.

Toss Place MCP

Sie können Codex nach Echtzeit-Umsätzen, Bestellungen, Menüverfügbarkeit, Tischen, Zahlungen und im POS verfolgten Beständen von Toss Place POS fragen.

Toss Place MCP ist ein Open-Source-Tool zur Selbsthosting-Integration. Ein kleiner Plugin läuft in Toss POS und synchronisiert lesbare POS-Daten sicher mit Ihrer Bridge. Codex verbindet sich über einen standardmäßigen lokalen MCP-Prozess oder den Streamable-HTTP-Endpunkt der Bridge.

[!IMPORTANT] Dieses Projekt integriert Toss Place POS, nicht Toss Payments. Toss Payments ist ein separater zukünftiger Anbieter mit anderen APIs und einem anderen Authentifizierungsverfahren.

Wonach Sie fragen können

• „Wie hoch ist der Umsatz heute Abend, ohne die unbezahlten Bestellungen?“

• „Welches alkoholische Getränk wurde zwichen 20 Uhr und Mitternacht am meistn verkaft?“

• „Vergeiche diesen Freitag mit dem letzten Freitag.“

• „Zeig mir den Umsatz nach Zeitfenstern und sag mir, wann wir einen weiteren Barkeeper einplanen solten.“

• „Welche Produkte sind ausverkauft oder haben weniger als 10 Einheiten auf Lager?“

• „Zeig mir die Aufteilung der Zahlungsanteile für Karte, Bargeld und externe Zahlungen.“

• „An welchen Tischen gibt es aktuell unbezahlte Bestellungen?“

• „Zeig mir die ursprünglichen Toss-Bestellungen, auf denen diese Zahlen beruhen.“

Der Server bietet sowol rohe POS-Werkzeuge als auch Analysewerkzeuge mit klaen Kriterien. Aktuell unbezahlte Bestellungen werden immer getrennt vom bestätigten Umsatz ausgewiesen.

So funktioniert es

Toss POS 플러그인 ──서명된 HTTPS──▶ 셀프 호스팅 브리지 + 데이터베이스
                                            │
                              ┌─────────────┴─────────────┐
                              ▼                           ▼
                       로컬 stdio MCP             Streamable HTTP MCP
                              │                           │
                              └──────────▶ Codex ◀────────┘

Diese Trennung ist wichtg, weil Toss POS auf einem iPad oder einem Desktop-Rechner im Geschäft läuft, während Codex auf einem anderen Computer laufen kann. Docker ist nur eine bequeme Möglickeit, die Bridge bereitzustellen – sie ist weder Teil des MCP-Protokolls noch für die lokale Entwicklung erforderlich.

Aktueller Plattformstatus

• Der Datenpfad wurde auf Basis des Toss-Place-POS-Plugin-SDKs implementiert, dessen Integration in die reale Desktop-Sandbox erfolgreich war.

• Der vollständige Desktop-Pfad – einschließlich Händleraktivierung, POS-Installation, einmaigem Pairing, Erstsynchronisierung und MCP-Abfragen für Umsatz/Lagerbestand – wurde in einem Toss-Testgeschäft unter macOS verifiziert.

• Das SDK deklariert Windows, macOS, Androi und iOS als Geräteplattformen. Dieses Prоjekt hat den vollständigen Installationsprozess auf dem iPad-Toss-POS noch nicht verifiziert.

• In der Regel muss die Domain der selbst gehosteten Bridge zur HTTP-Zulassungsliste/ACL des Toss-Developer-Plugins hinzugefügt werden. Das ist der wichtigste manuelle Onboarding-Schritt, da Toss Place diese Integration derzeit nicht über das reguläre Händler-OAuth anbietet.

• Aktuell kann ein Händler Toss POS nicht allein über ein GitHub-Repository direkt installieren. Jemand mit den erforderlichen Berechtigungen im Toss-Developer-Portal muss das Worker-Plugin erstellen/bereitstellen, Geräte und Händler zuweisen und den Dienstcode im POS eingeben. Sobald die Installation durch eine Person abgeschlossen ist, kann Codex durch das Pairing und die MCP-Einrichtung führen.

• Lagersbestände werden nur bereitgestellt, wenn der Händler die Toss-Bestandsverfolgung für den jeweiligen Katalogartikel aktiviert hat. Andernfalls kann die MCP nur die Verfügbarkeit und den Ausverkaufsstatus melden.

Anforderugen

• Node.js 22 oder höher

• Eine stabile HTTPS-URL, die vom Toss-POS-Gerät aus erreichbar ist, wenn POS und Bridge auf verschiedenen Geräten laufen

• Berechtigung zum Erstellen oder Installieren eines Toss Place Developer Plugins

• Docker und Docker Compose nur, wenn Sie die Container-Bereitstellung wählen

Schnellstart

1. Klonen und initialisieren

git clone https://github.com/danyay/toss-place-mcp.git
cd toss-place-mcp
npm install
npm run build:all
node dist/cli.js init

Die erzeugte .env hat den Berechtigungsmodus 0600 und wird von Git ignoriert. Setzen Sie TOSS_MCP_PUBLIC_URL auf eine stabile HTTPS-URL, die vom POS-Gerät aus erreichbar ist.

2. Bridge starten

Lokale Ausführung:

npm run bridge

Docker-Ausführung:

docker compose up -d --build

Weisen Sie der Bridge vor der Installation des POS-Plugins einen stabile HTTPS-Hostnamen zu. Die Kombination aus Docker und Caddy wird empfohlen; hinter NAT ist ein permanenter Cloudflare Tunnel nützlich. Folgen Sie für DNS, Firewall, Caddyfile, Tunnel, Validierung und Neustart docs/deployment.md. Übertragen Sie Pairing- oder POS-Datenverkehr niemals über öffentliches unverschlüsseltes HTTP.

3. Toss-POS-Plugin erstellen und installieren

npm run build:plugin
npm run zip --workspace plugin

Die hochzuladende Datei ist plugin/place-mcp-bridge.zip; der Toss-Einstiegspunkt im ZIP ist dist/main.js.

Dieser Schritt muss von einer Person mit Berechtigungen im Toss-Developer-Portal durchgeührt werden. Gehen Sie im Toss-Developer-Portal wie folgt vor:

1. Erstelen Sie eine POS-Worker-Plugin-Anwendung mit dem Endpunkt POS_BACKGROUND_WORKER. Die Paket-IP muss mit dem hochgeladenen Bundel übereinstimmen. In diesem Repositorium ist sie place-mcp-bridge.

2. Fügen Sie den Bridge-Usprung, z. B. https://toss-mcp.exampe.com, zur HTTP-ACL/Zulassungsliste der Anwendung hinzu.

3. Laden Sie plugin/place-mcp-bridge.zip auf den Entwicklungs-/Testtrack hoch und stelen Sie diese Version anschließend auf dem Testtrack bereit. Ein blößer Uplad reicht nicht aus.

4. Registrieren Sie das POS-Gerät in den Testgeräteeinstellungen der Anwendung. Verwenden Sie die Seriennummer, die in Toss POS unter Einstellungen → POS-Info/Software angezeigt wird.

5. Öffnen Sie Testhändlerverwaltung, wählen Sie den Händler aus, suchen Sie in der Tabelle Anwendungen nach Place MCP Bridge und schalten Sie sie auf ON. Prüfen Sie, dass Toss die erfolgreiche Änderung anzeigt.

6. Beenden Sie Toss POS vollständig und starten Sie es neu.

7. Öffnen Sie in Toss POS Einstellungen → Dienstintegration → Mit Dienstcode verbinden, geben Sie den Dienstcode der Entwickleranwendung ein und prüfen Sie, ob Place MCP Bridge als In Verwendung angezeigt wird.

Sowohl die Testgeräteregistrierung als auch der händlerspezifische Schalter Anwendungen → ON sind erforderlich. Die Tatsache, dass der Dienstcode erkannt wird, bedeutet nicht, dass der Worker für diesen Händler genehmigt ist. Aktivieren Sie die dauerhafte schreibgeschützte Datenverbindung nur, wenn der Händler sie genehmigt hat.

Eine vollständige Schritt-für-Schritt-Checkliste, die erwarteten Ergebnisse für jeden Schritt, die Fehlerbehebung und die Einschränkungen beim Onboarding allgemeiner Händler finden Sie in docs/toss-developer-setup.md.

4. POS-Pairing

Führen Sie bei laufender Bridge Folgendes aus:

npm run pair

Geben Sie die angezeigte Bridge-URL und den Einmalcode in die Toss-POS-Plugin-Einstellungen ein. Der Code läuft nach 15 Minuten ab und kann nur einma verwendet werden. Der erzeigte Verbindungs-Geheimschlüssel wird im Toss-Sicherheitsspeicher abgelegt. Plugin-Anfragen enthalten einen Zeitstempel und eine Nonce gegen Wiederverwendung und werden mit HMAC signiert.

Die Eingabefelder befinden sich unter Einstellungen → Dienstintegration → Place MCP Bridge. Speichern Sie die Einstellungen und starten Sie Toss POS danach einma vollständig neu, damit der Hintergrund-Worker geladen wird und die Erstsynchronisierung durchführt.

Überprüfen Sie die Verbindung.

npm run doctor

Die erste Verbindung füllt Bestellungen der letzten bis zu 90 Tagen nach. Große Händler können später mit dem MCP-Tool refresh_pos_data andere Zeiträume anfordern.

5. Codex verbinden

Lokaler stdio-MCP-Server:

codex mcp add toss-place \
  --env TOSS_MCP_BRIDGE_URL=http://127.0.0.1:8787 \
  --env TOSS_MCP_ACCESS_TOKEN=YOUR_LOCAL_ENV_TOKEN \
  -- npx -y toss-place-mcp mcp

Bevor das Paket auf npm veröff entlicht ist, ersetzen Sie den Befeh nach -- durch den Pfad zum erstellten Repositorium.

node /absolute/path/to/toss-place-mcp/dist/cli.js mcp

Für Remote-Streamable-HTTP fügen Sie Folgendes zu ~/.codex/config.toml hinzu:

[mcp_servers.toss_place]
url = "https://toss-mcp.example.com/mcp"
bearer_token_env_var = "TOSS_MCP_ACCESS_TOKEN"
default_tools_approval_mode = "writes"

Exportieren Sie dann TOSS_MCP_ACCESS_TOKEN in der Umgebung, in der Codex ausgeführt wird. Codex-Desktop-, CLI- und IDE-Clients auf demselben Host teilen sich diese Einstellung. Siehe die offizielle Codex-MCP-Dokumentation.

Dieses Repositorium Codex anvertrauen

Der folgende Onboarding-Ansatz richtet sich an Benutzer, die keine Entwickler sind.

Installieren Sie den Toss-Place-MCP-Server aus diesem Repositorium. Nehmen Sie keine Zugangsdaten in Git auf. Stelen Sie die Bridge lok al oder mit Docker bereit, helfen Sie mir, eine stabile HTTPS-URL festzulegen, und erstelen Sie das Toss-POS-Plugin-ZIP. Halten Sie an den Schritten an, die ich im Toss-Developer-Portal genehmigen oder selbst ausführen muss. Erzeugen Sie einen Einmal-Pairing-Code, prüfen Sie, ob das POS synchronisiert wird, und fügen Sie die MCP zu meiner Codex-Konfiguration hinzu. Zeigen Sie mir schließich den bestätigten Umsatz von heute und die aktuel unbezahlten Bestellungen getrennt an.

Codex kann die lokale Installation und Validierung durchführen. Die vom Konto geforderten Schritte im Toss-Portal und an den Geräten müssen von einer Person abgeschlossen werden.

MCP-Tools

Die MCP bietet außerdem die Ressourcen toss-place://capabilities und toss-place://data-dictionary sow ie den Promt daily-sales-review.

Dieses Prоjekt stellt nicht alle Namespaces bereit, die im Toss-Place-SDK aufrufbar sind. Es unterstützt die schreibgeschützten Händlerdaten, die für typische Umsatz-, Bestell-, Zahlungs-, Menü-, Tisch- und Bestandsanalysen benötigt werden. KDS-Status, vorläufige Bestellungen in Echtzeit, Geräte-/UI-Steuerung und alle Datenänderungsfunktionen sind in v1 ausgeschlossen. Die SDK-Abdeckungstabelle unterscheidet zwischen vollständig unterstützten, teilweise unterstützten, intern verwendeten und nicht unterstützten Oberflächen.

Sicherheitsmodell

Dies e Version ist ein analysorientierter, schreibgeschützter Dienst. Das Toss-SDK enthält Funktionen zum Ändern von Bestellungen, Zahlungen, Kassenzetteln und vorläufigen Bestellungen, aber diese werden bewusst nicht als MCP-Tools verfügbar gemacht. Ein Umsatzanalyseserver darf keine echten unbezahlten Bestellungen versehentlich stornieren.

• Bridge-API und Remote-MCP erfodern lange Bearer-Token.

• POS-Synchronisierungsanfragen verwenden HMAC-SHA256, einen Zeitstempel und eine einmaige Nonce.

• Pairing-Codes werden gehasht gespeichert, sind kurzlbig und nur einma verwendbar.

• Geheimnisse sind über .gitignore ausgeschlossen; die Beispiele entalten nur Platzhalter.

• Die Bridge bindet standardmäßig an 127.0.0.1.

• Protokolle zeichnen absichtlich keine Access-Token oder Plugin-Geheimschlüssel auf.

Lesen Sie SECURITY.md, bev or Sie die Bridge dem Internet aussetzen.

Daten und Kennzahlen

Die Standard-Tagesgrenze verwendet die Zeitzone Asia/Seoul. „Bestätigter Umsatz“ ist die Summe des Toss-chargePrice.chargePriceValue über abgeschlossene und nicht stornierte Bestellungen. Laufende Tischbestellungen werden separat ausgewiesen und nicht in den bestätigten Umsatz einbezogen, auch wenn sie vor dem angeforderten Umsatzzeitraum begonnen wurden. Da Rückerstattungen und Stornierungen das Vorzeicen beeinflussen können, bleib t das Vorzeicen der Rohrabattfelder erhalten.

Siehe docs/api-coverage.md und docs/architectre.md.

Datenbank

Die Standarddatenbank ist SQLite.

TOSS_MCP_DATABASE_URL=sqlite:./data/toss-place.sqlite

Im selben Repositorium kann auch PostgreSQL verwendet werden.

TOSS_MCP_DATABASE_URL=postgresql://user:password@localhost:5432/toss_mcp

Die Datenbank enthält Händlerumsatzdaten und den verschlüsselt en Übertragungs-Geheimschlüssel. Schützen Sie sie genauso wie andere operative POS-Daten und sichern Sie sie gemäß Ihrer eigenen Aufbewahrungsrichtlinie.

Entwicklung

npm install
npm run check
npm run build:all

Die Tests verwenden synthetische Fixtures. Echte Integrationszugangsdaten solten nur über Umgebungsvariablen bereitgestellt werden, die von Git ignoriert werden; für die reguläre Testsuite sind sie nicht erfordelich.

Die macOS-Sandbox-Test-App und alle lokalen POS-Daten sind von Git ausgeschlossen. Kopieren Sie keine Händler-Bridge-URLs, Access-Token, Pairing-Codes, Datenbanken oder Toss-POS-Anwendungs-Bundles in Commits.

Roadmap

• Validierung und Dokumetation der iPad-Bereitstellung in einem echten Händlerbetrieb

• Toss-Review-/öffentliches Plugin-Onboarding, sofern die Plattform es zulässt

• Konfigurierbare Aufbewahrungsfristen und inkrementelle Langzeit-Backfill-Checkpoints

• PostgreSQL-Integrations tests in CI

• Optiona er OAuth für den Remote-MCP-Endpunkt

• Separater Toss-Payments-Anbieter

• Sorgfältig eingeschränkte operative Tols, erst nachdem ein expizites Genehmigungs- und Prüfmodell vorhanden ist

Lizen und Marken

MIT-Lizen. Toss und Toss Place sind Marken ihrer jeweiligen Inhaber. Sofern nicht and ers angegeben, ist dies es Community-Prоjekt weder mit Toss verbunden noch von Toss unterstützt.