Einrichtung des externen App Building Agents (OpenCode)

Dieser Leitfaden erklärt, wie du OpenCode als deinen externen App Building Agent für Simplifier-Projekte einrichtest. Jedes Projekt oder jede Anwendung sollte in einem eigenen Verzeichnis mit einer eigenen MCP-Konfiguration liegen, die aus dem Simplifier App Editor geklont wurde.

Voraussetzungen

Bevor du beginnst, stelle sicher, dass Folgendes auf deinem Rechner installiert und verfügbar ist:

Node.js (LTS-Version, enthält npx)
Einguss
OpenCode — installiere es über:
```
npm install -g opencode-ai
```
Ein Anthropic-Konto mit Zugriff auf die Modelle Claude Opus und Claude Sonnet
Zugriff auf deinen Simplifier App Editor (um das Git-Repository des Projekts zu klonen)
Ein gültiger Simplifier Token von deiner Simplifier-Instanz (Benutzerprofil → Sicherheit)
Für das Spec Kit (optional, Schritt 6): uv (oder pipx), um das specify-CLI zu installieren

Schritt 1 — Erstelle ein neues Projektverzeichnis

Erstelle für jedes Projekt oder jede Anwendung ein eigenes Verzeichnis auf deinem Rechner. Dies hält MCPs, Konfiguration und Git-Historie pro App isoliert.

mkdir ~/simplifier-projects/
cd ~/simplifier-projects/

Wichtig: Mische nicht mehrere Simplifier-Apps im selben Verzeichnis. Jede App benötigt einen eigenen Ordner, damit MCPs und der OpenCode-Kontext sauber bleiben.

Schritt 2 — Klone das Projekt-Git-Repository aus dem Simplifier App Editor

Öffne deine App im Simplifier App Editor.
Erstelle eine neue App mit Version 2 und installiere sie.

Öffne das Git-Panel und kopiere die Repository-URL deiner Anwendung.
Klone das Repository in deinem Terminal in das soeben erstellte Projektverzeichnis:
```
git clone <simplifier-app-git-url>
```

Kopiere den Befehl am besten aus dem v2 App Editor. Dies erstellt ein neues Verzeichnis mit dem Namen der Anwendung. Wenn du bereits ein Verzeichnis für deine App erstellt hast, öffne zuerst den Ordner und füge dem Befehl ein abschließendes . hinzu, um die Ressource in das erstellte App-Verzeichnis zu klonen.

git clone <simplifier-app-git-url> .

Überprüfe den Klonvorgang:
```
git status
```

Schritt 3 — Wechsle in das Projektverzeichnis und füge MCPs hinzu

Alle MCP-Server müssen aus dem Projekt-Git-Ordner heraus hinzugefügt werden, damit sie nur auf diese App beschränkt sind. In OpenCode werden MCPs über die projektlokale Datei opencode.json (im Ordner .opencode/opencode.json) konfiguriert.

3.1 — Starte OpenCode im Projektordner (einmalig zur Initialisierung)

cd ~/simplifier-projects/<your-app-name>
opencode

Beenden Sie erneut mit /exit, sobald es initialisiert wurde. Dadurch wird der Ordner .opencode/ mit der Datei opencode.json erstellt.

3.2 — Füge die erforderlichen MCP-Server hinzu

Öffnen Sie .opencode/opencode.json in Ihrem Editor und fügen Sie die folgenden MCP-Einträge hinzu. Falls die Datei noch keinen MCP-Schlüssel hat, fügen Sie ihn hinzu.

Simplifier MCP — Konnektoren, Business Objekte, Datentypen, SAP-Systeme

Referenz: https://github.com/simplifier-ag/simplifier-mcp

Du benötigst zwei Werte:

SIMPLIFIER_BASE_URL – z. B. https://<yourinstance>-dev.simplifier.cloud (On-Premise-Benutzer verwenden ihre eigene Entwicklungs-URL).
SIMPLIFIER_TOKEN – Ihr aktueller SimplifierToken aus der angemeldeten Simplifier-Sitzung.

via npx (empfohlen):

{
  "mcp": {
    "simplifier": {
      "type": "local",
      "command": ["npx", "@simplifierag/simplifier-mcp@latest"],
      "env": {
        "SIMPLIFIER_TOKEN": "",
        "SIMPLIFIER_BASE_URL": "https://-dev.simplifier.cloud"
      },
      "enabled": true
    }
  }
}

Alternative — via Docker:

{
  "mcp": {
    "simplifier": {
      "type": "local",
      "command": ["docker", "run", "--rm", "-i",
        "--env", "SIMPLIFIER_TOKEN=",
        "--env", "SIMPLIFIER_BASE_URL=https://-dev.simplifier.cloud",
        "simplifierag/simplifier-mcp:latest"
      ],
      "enabled": true
    }
  }
}

Token-Rotation: Jedes Mal, wenn Sie sich bei Simplifier anmelden, ändert sich Ihr SIMPLIFIER_TOKEN. Nach jeder neuen Anmeldung müssen Sie:

OpenCode beenden

Aktualisieren Sie den Wert von SIMPLIFIER_TOKEN in .opencode/opencode.json

aktualisieren und OpenCode neu starten

Falls der Simplifier MCP beim Start keine Verbindung herstellen kann, öffnet sich in deinem Browser eine Fehlerseite mit Details und Lösungsvorschlägen.

Fiori MCP Server — SAP Fiori Anwendungs-Scaffolding & -Modifikation

"fiori-mcp-server": {
  "type": "local",
  "command": ["npx", "-y", "@sap/fiori-mcp-server@latest"],
  "enabled": true
}

UI5 MCP Server — SAPUI5 / OpenUI5 Entwicklung, Linting, API-Referenz

"ui5-mcp-server": {
  "type": "local",
  "command": ["npx", "-y", "@ui5/mcp-server@latest"],
  "enabled": true
}

Playwright MCP — Browser-Automatisierung & End-to-End-Tests

"playwright": {
  "type": "local",
  "command": ["npx", "-y", "@playwright/mcp@latest"],
  "enabled": true
}

Vollständiges Beispiel `.opencode/opencode.json`

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "mcp": {
    "simplifier": {
      "type": "local",
      "command": ["npx", "@simplifierag/simplifier-mcp@latest"],
      "env": {
        "SIMPLIFIER_TOKEN": "",
        "SIMPLIFIER_BASE_URL": "https://-dev.simplifier.cloud"
      },
      "enabled": true
    },
    "fiori-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "@sap/fiori-mcp-server@latest"],
      "enabled": true
    },
    "ui5-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "@ui5/mcp-server@latest"],
      "enabled": true
    },
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp@latest"],
      "enabled": true
    }
  }
}

3.3 — Überprüfe die MCP-Registrierung

Starte OpenCode neu und prüfe, ob alle MCPs in der Statusleiste als verbunden angezeigt werden. Du solltest Folgendes sehen:

simplifier
fiori-mcp-server
ui5-mcp-server
playwright

Schritt 4 — Initialisiere das Simplifier-Projekt

Führe den Init-Befehl innerhalb von OpenCode aus:

/init-simplifier

Dieser Befehl führt dich durch:

Festlegen der Basis-URL der Simplifier-Instanz in .env
Ausführen von ‘pnpm install’ zum Abrufen der UI5-Tools pnpm install
Starten des Dev-Servers mit ‘pnpm run start’ (App verfügbar unter http://localhost:12345/index.html) pnpm run start
Dokumentation der MCP-Nutzung in CLAUDE.md / AGENTS.md

Der Befehl /init-simplifier befindet sich in .claude/commands/init-simplifier.md im Projekt-Repo. OpenCode liest und führt diese Slash-Befehle genau wie Claude Code aus.

Schritt 5 — Der Zwei-Modi-Workflow: Erst planen, dann bauen

OpenCode unterstützt die gleiche „Plan-first / Build-second“-Methodik. Beginne immer im Plan-Modus. Wechsle erst in den Build-Modus, nachdem die Spezifikation geprüft und genehmigt wurde.

5.1 — Plan-Modus (verwende Claude Opus 4.5)

Der Plan-Modus ist schreibgeschützt: Der Agent analysiert, entwirft und schlägt vor — aber er verändert keine Dateien.

Empfohlenes Modell: claude-opus-4-5 (höchste Argumentationsqualität)
Wann zu verwenden: IMMER zu Beginn einer Aufgabe, mit oder ohne Spec Kit
Ziel: Erstellung einer klaren, geprüften Spezifikation oder eines Implementierungsplans

Legen Sie das Modell in OpenCode fest, indem Sie opencode.json aktualisieren, bevor Sie eine Planungssitzung starten:

{
  "model": "anthropic/claude-opus-4-5"
}

Oder wechsle direkt während der Sitzung:

/model anthropic/claude-opus-4-5

Beschreibe nun, was du bauen möchtest. Prüfe das Ergebnis sorgfältig:

Entspricht es deiner Absicht?
Sind alle Entitäten, Konnektoren und Business Objekte korrekt identifiziert?
Sind Sonderfälle abgedeckt?
Lassen sich externe Anforderungen (Excel/PDF/Jira) 1:1 in der Spezifikation nachverfolgen?

5.2 — Build-Modus (verwende Claude Sonnet 4.5)

Sobald die Spezifikation oder der Plan steht, wechsle für die eigentliche Implementierung in den Build-Modus. Sonnet ist schneller und kostengünstiger und für die Ausführung eines gut definierten Plans völlig ausreichend.

Empfohlenes Modell: claude-sonnet-4-5 (kosteneffizient, schnell)
Wann zu verwenden: NUR nachdem der Plan/die Spezifikation geprüft und genehmigt wurde

Modell für die Ausführung wechseln:

{
  "model": "anthropic/claude-sonnet-4-5"
}

Oder direkt:

/model anthropic/claude-sonnet-4-5

Weise den Agenten nun an, den genehmigten Plan auszuführen. Er wird Dateien erstellen, Befehle ausführen und Änderungen committen.

Schritt 6 — (Optional, empfohlen für größere Projekte) GitHub Spec Kit integrieren

Für größere Anwendungen empfehlen wir dringend die Verwendung des GitHub Spec Kit Frameworks. Das Spec Kit treibt die spezifikationsgetriebene Entwicklung voran: Du schreibst zuerst eine präzise Spezifikation und lässt sie dann vom Agenten implementieren.

Führen Sie /init-simplifier (Schritt 4) aus und wechseln Sie in den Planungsmodus (Schritt 5) VOR den Spec Kit-Befehlen.

6.1 — Installiere das Specify-CLI (einmalig, systemweit)

Spec Kit wird als specify CLI ausgeliefert. Einmalig über uv (empfohlen) oder pipx installieren:

# Recommended — using uv
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Alternative — using pipx
pipx install git+https://github.com/github/spec-kit.git

Überprüfen:

specify version
specify check

Wenn Befehl nicht gefunden: uv → installieren Sie zuerst uv, oder verwenden Sie die pipx-Zeile oben.

6.2 — Initialisiere das Spec Kit in deinem Projekt

Aus deinem Projektverzeichnis heraus:

cd ~/simplifier-projects/<your-app-name>

# Initialize in the current folder for OpenCode
specify init . --integration claude
# or, equivalent
specify init --here --integration claude

Dadurch wird der Ordner .specify/ mit Vorlagen sowie Slash-Befehle unter .claude/commands/ erstellt, die OpenCode ebenfalls aufnimmt.

6.3 — Projektprinzipien festlegen (Constitution)

Führe in OpenCode Folgendes aus:

/speckit.constitution Create principles focused on code quality, Simplifier best practices, BusinessObject testing, naming conventions for connectors, and UI consistency for SAPUI5/Fiori screens.

6.4 — Erstelle die Spezifikation

Schreibe die Spezifikation für ein kleines/internes Projekt direkt:

/speckit.specify Build a Simplifier app that lets warehouse managers scan barcodes, look up stock levels via the SAP RFC connector, and post goods movements. The UI is a Fiori list-detail layout.

6.4.a — Externe Anforderungen integrieren (Excel, Word, PDF, Jira-Export)

Wenn du bereits Anforderungen in einer Excel-Tabelle mit User Stories, einer Word/PDF-Spezifikation, einem Jira-Export oder einem anderen externen Dokument hast, tippe diese nicht erneut ab. Lege die Datei(en) in den Projektordner (z. B. in einen Unterordner docs/) und lass OpenCode sie lesen.

mkdir docs
cp ~/Downloads/UserStories.xlsx docs/
cp ~/Downloads/RequirementsSpec.pdf docs/

Verwende dann in OpenCode (Plan-Modus + Opus 4.5) einen Prompt wie:

Prompt-Beispiel — Excel mit User Stories:

Read the file docs/UserStories.xlsx. Each row is a user story with columns:
ID, Role, Goal, Reason (As a / I want / So that), Acceptance Criteria, Priority, Epic.

Consolidate the stories into a coherent specification grouped by Epic.
Identify all entities, Simplifier Connectors, BusinessObjects and screens implied
by the stories. Then call /speckit.specify with the consolidated text so that
spec.md is created. Preserve the original Story IDs as references in the spec
so we can trace every requirement back to the Excel.

Prompt-Beispiel — PDF / Word-Spezifikation:

Read docs/RequirementsSpec.pdf. Extract:
- functional requirements (numbered FR-x)
- non-functional requirements (NFR-x)
- data entities and their fields
- external systems / integrations

Then run /speckit.specify with a structured summary that keeps the FR/NFR IDs
as traceability anchors. Flag anything ambiguous and ask me before finalizing.

Prompt-Beispiel — Jira / Azure DevOps CSV-Export:

Read docs/jira-export.csv. Each row is an issue (Story or Task) with key,
summary, description, acceptance criteria, labels, epic link.

Group by Epic Link, deduplicate, and produce a single spec input. Then call
/speckit.specify. Keep Jira keys (e.g. PROJ-123) as references next to each
requirement so we can sync back to Jira later.

OpenCode kann .xlsx, .csv, .docx, .pdf, .md, .txt direkt lesen. Bei sehr großen Dateien bitten Sie den Agenten, zuerst kapitelweise zusammenzufassen und dann die konsolidierte Spezifikation zu erstellen.

Nachdem /speckit.specify ausgeführt wurde, überprüfen Sie spec.md und verfeinern Sie es mit /speckit.clarify, falls etwas unzureichend spezifiziert ist.

6.5 — Planen, aufteilen, implementieren

/speckit.plan Use the Simplifier platform: REST/SAP-RFC connectors, server-side BusinessObjects for business logic, and a Fiori-style SAPUI5 frontend. Persist app artifacts via the Simplifier Git integration.

/speckit.tasks

/speckit.analyze     # optional — cross-artifact consistency check before implement

/speckit.implement

`/speckit.constitution`	Projektweite Leitprinzipien
`/speckit.specify`	Definiere, was gebaut werden soll (funktionale Spezifikation)
`/speckit.clarify`	Unzureichend spezifizierte Bereiche auflösen (vor /speckit.plan ausführen)
`/speckit.plan`	Definiere, wie es gebaut werden soll (Tech-Stack, Architektur)
`/speckit.tasks`	Erstelle die ausführbare Aufgabenliste
`/speckit.analyze`	Prüfung der Konsistenz und Abdeckung über alle Artefakte hinweg
`/speckit.implement`	Führe alle Aufgaben aus

Zusammenfassung des empfohlenen Workflows

Schritt	Aktion	Modell	Modus
1	Projektverzeichnis erstellen	—	—
2	git clone aus dem Simplifier App Editor	—	—
3	MCPs über .opencode/opencode.json hinzufügen (Simplifier, Fiori, UI5, Playwright)	—	—
4	/init-simplifier innerhalb von OpenCode ausführen	—	—
5	Plan-Modus aufrufen + Opus 4.5 wählen	Opus 4.5	Plan
6	(Große Projekte) specify init + /speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan	Opus 4.5	Plan
7	Plan + Spezifikation prüfen und genehmigen	Opus 4.5	Plan
8	Wechseln Sie in den Build-Modus + Sonnet 4.5; /speckit.tasks → /speckit.analyze → /speckit.implement	Sonnet 4.5	Build
9	Commit und Push zum Simplifier Git	Sonnet 4.5	Build

Tipps & Best Practices

Ein Projekt = ein Ordner = eine .opencode/opencode.json. Teilen Sie niemals MCP-Konfigurationen über nicht verwandte Apps hinweg.
Beginne immer im Plan-Modus. Die Kosten für einen schlechten Plan sind weitaus höher als die Kosten für Opus-Token.
Wechsle für die Ausführung zu Sonnet. Das Bauen auf Basis eines klaren Plans erfordert keine Argumentation auf Opus-Niveau.
Aktualisieren Sie Ihren Simplifier Token nach jeder Anmeldung. Aktualisieren Sie SIMPLIFIER_TOKEN in .opencode/opencode.json und starten Sie OpenCode neu – andernfalls schlagen Aufrufe mit Authentifizierungsfehlern fehl.
Legen Sie externe Anforderungen in docs/ ab. Excel, PDF, Word, CSV – lassen Sie den Agenten sie lesen; kopieren Sie Inhalte niemals manuell per Copy-and-Paste.
Bewahre externe IDs. Story-IDs (Jira-Keys, Excel-Zeilen-IDs, FR-/NFR-Nummern) gehören zur Rückverfolgbarkeit in die Spezifikation.
Committe oft. Nutze das geklonte Simplifier-Git-Repository als „Source of Truth“ — pushe die Änderungen zurück in den App Editor, wenn die Arbeit erledigt ist.
Verwenden Sie Spec Kit für alles, was nicht trivial ist. Selbst eine einzige spec.md verbessert die Agenten-Ausgabe dramatisch.
Halte MCPs auf dem neuesten Stand. Überprüfe regelmäßig die MCP-Konnektivität im Status-Panel von OpenCode.

Fehlerbehebung

Symptom	Lösung
MCP wird in OpenCode als getrennt angezeigt	Überprüfen Sie .opencode/opencode.json auf Tippfehler im Befehl oder in den Umgebungsvariablen; starten Sie OpenCode neu
Simplifier MCP zeigt Authentifizierungs- / 401-Fehler an	Ihr SIMPLIFIER_TOKEN ist nach der erneuten Anmeldung abgelaufen → aktualisieren Sie den Token in .opencode/opencode.json und starten Sie OpenCode neu
Simplifier MCP öffnet beim Start eine Fehlerseite im Browser	Lies die Seite — sie beschreibt das Verbindungsproblem (falsche URL, ungültiger Token, Netzwerk) und wie es behoben werden kann
Agent kennt Simplifier APIs nicht	Bestätigen Sie, dass der Simplifier-Eintrag vorhanden und enabled: true in .opencode/opencode.json ist
Opus 4.5 zu langsam / zu teuer für kleine Bearbeitungen	Wechseln Sie zu Sonnet 4.5 mit /model anthropic/claude-sonnet-4-5, nachdem der Plan gesperrt ist
Playwright MCP startet den Browser nicht	Führen Sie ‘npx playwright install’ einmal aus, um Browser-Binärdateien zu installieren `npx playwright install`
`specify: command not found`	Installation über uv tool install specify-cli –from git+https://github.com/github/spec-kit.git (oder pipx)
`/speckit.*` Befehle in OpenCode nicht sichtbar	Führen Sie specify init . –integration claude erneut im Projektordner aus und starten Sie dann OpenCode neu
Excel-/PDF-Anforderungen werden vom Agenten ignoriert	Legen Sie Dateien in docs/ ab und verweisen Sie explizit auf den Pfad in Ihrer Eingabeaufforderung (z. B. docs/UserStories.xlsx)

Aktueller Release