Setup External App Building Agent (OpenCode)

This guide explains how to set up OpenCode as your external app building agent for Simplifier projects. Each project or application should live in its own directory with its own MCP configuration, cloned from the Simplifier App Editor.

Prerequisites

Before you begin, make sure the following are installed and available on your machine:

Node.js (LTS version, includes npx)
Git
OpenCode — install via:
```
npm install -g opencode-ai
```
An Anthropic account with access to the Claude Opus and Claude Sonnet models
Access to your Simplifier App Editor (to clone the project Git repository)
A valid Simplifier Token from your Simplifier instance (User Profile → Security)
For Spec Kit (optional, Step 6): uv (or pipx) to install the specify CLI

Step 1 — Create a New Project Directory

For each project or application, create a dedicated directory on your machine. This keeps MCPs, configuration, and Git history isolated per app.

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

Important: Do not mix multiple Simplifier apps in the same directory. Each app needs its own folder so that MCPs and OpenCode context stay clean.

Step 2 — Clone the Project Git Repository from the Simplifier App Editor

Open your app in the Simplifier App Editor.
Create a new App with Version 2 and install it.

Open the Git panel and copy the repository URL of your application.
In your terminal, clone the repository into the project-directory you just created:
```
git clone <simplifier-app-git-url>
```

Best copy the command from the v2 application editor. This creates a new directory with the applications name. If you have already created a directory for your app, open the folder first and add a trailing . to the command, to clone the ressource to the created app directory.

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

Verify the clone:
```
git status
```

Step 3 — Enter the Project Directory and Add MCPs

All MCP servers must be added from inside the project Git folder so they are scoped to this app only. In OpenCode, MCPs are configured via the project-local opencode.json file (located in .opencode/opencode.json).

3.1 — Start OpenCode in the project folder (one-time, to initialize)

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

Exit again with /exit once it has initialized. This creates the .opencode/ folder with opencode.json.

3.2 — Add the required MCP servers

Open .opencode/opencode.json in your editor and add the following MCP entries. If the file does not yet have an MCP key, add it.

Simplifier MCP — Connectors, Business Objects, Datatypes, SAP Systems

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

You need two values:

SIMPLIFIER_BASE_URL — e.g. https://<yourinstance>-dev.simplifier.cloud (on-premise users use their own dev URL).
SIMPLIFIER_TOKEN — your current SimplifierToken from the logged-in Simplifier session.

via npx (recommended):

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

Alternative — via Docker:

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

Token rotation: Every time you log in to Simplifier, your SIMPLIFIER_TOKEN changes. After each new login you must:

Exit OpenCode

Update the SIMPLIFIER_TOKEN value in .opencode/opencode.json

Restart OpenCode

If the Simplifier MCP fails to connect on startup, an error page opens in your browser with details and fix suggestions.

Fiori MCP Server — SAP Fiori application scaffolding & modification

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

UI5 MCP Server — SAPUI5 / OpenUI5 development, linting, API reference

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

Playwright MCP — Browser automation & end-to-end testing

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

Full example `.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": "<your-current-simplifier-token>",
        "SIMPLIFIER_BASE_URL": "https://<yourinstance>-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 — Verify the MCP registration

Restart OpenCode and check that all MCPs show as connected in the status bar. You should see:

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

Step 4 — Init the Simplifier Project

Execute the init command within OpenCode:

/init-simplifier

This command walks you through:

Setting the Simplifier instance base URL in .env
Running ‘pnpm install’ to fetch UI5 tooling pnpm install
Starting the dev server with ‘pnpm run start’ (app available at http://localhost:12345/index.html) pnpm run start
Documenting MCP usage in CLAUDE.md / AGENTS.md

The /init-simplifier command lives in .claude/commands/init-simplifier.md in the project repo. OpenCode reads and executes these slash commands just like Claude Code does.

Step 5 — The Two-Mode Workflow: Plan First, Then Build

OpenCode supports the same Plan-first / Build-second methodology. Always start in Plan Mode. Only switch to Build Mode after the specification is reviewed and approved.

5.1 — Plan Mode (use Claude Opus 4.5)

Plan Mode is read-only: the agent analyzes, designs, and proposes — but does not modify files.

Recommended model: claude-opus-4-5 (highest reasoning quality)
When to use: ALWAYS at the start of a task, with or without Spec Kit
Goal: Produce a clear, reviewed specification or implementation plan

Set the model in OpenCode by updating opencode.json before starting a planning session:

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

Or switch inline during the session:

/model anthropic/claude-opus-4-5

Now describe what you want to build. Review the result carefully:

Does it match your intent?
Are all entities, connectors, business objects correctly identified?
Are edge cases covered?
Do external requirements (Excel/PDF/Jira) trace 1:1 into the spec?

5.2 — Build Mode (use Claude Sonnet 4.5)

Once the specification or plan is good, switch to Build Mode for the actual implementation. Sonnet is faster and cheaper, and is fully sufficient for executing a well-defined plan.

Recommended model: claude-sonnet-4-5 (cost-efficient, fast)
When to use: ONLY after the plan/spec is reviewed and approved

Switch model for execution:

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

Or inline:

/model anthropic/claude-sonnet-4-5

Now instruct the agent to execute the approved plan. It will create files, run commands, and commit changes.

Step 6 — (Optional, Recommended for Larger Projects) Integrate GitHub Spec Kit

For larger applications, we strongly recommend using the GitHub Spec Kit framework. Spec Kit drives Spec-Driven Development: you first write a precise specification, then let the agent implement it.

Run /init-simplifier (Step 4) and enter Plan Mode (Step 5) BEFORE Spec Kit commands.

6.1 — Install the Specify CLI (one-time, system-wide)

Spec Kit ships as the specify CLI. Install once via uv (recommended) or pipx:

# 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

Verify:

specify version
specify check

If command not found: uv → install uv first, or use the pipx line above.

6.2 — Initialize Spec Kit in your project

From inside your project directory:

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

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

This creates the .specify/ folder with templates, plus slash commands under .claude/commands/ which OpenCode also picks up.

6.3 — Establish project principles (constitution)

In OpenCode, run:

/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 — Create the specification

For a small/internal project, write the spec directly:

/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 — Integrate external requirements (Excel, Word, PDF, Jira export)

If you already have requirements in an Excel sheet with user stories, a Word/PDF specification, a Jira export, or any other external document, do not retype them. Drop the file(s) into the project folder (e.g. into a docs/ subfolder) and let OpenCode read them.

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

Then in OpenCode (Plan Mode + Opus 4.5), use a prompt like:

Prompt example — Excel with 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 example — PDF / Word specification:

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 example — 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 can read .xlsx, .csv, .docx, .pdf, .md, .txt directly. For very large files, ask the agent to summarize chapter by chapter first, then produce the consolidated spec.

After /speckit.specify has run, review spec.md and refine with /speckit.clarify if anything is underspecified.

6.5 — Plan, break down, implement

/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`	Project-wide guiding principles
`/speckit.specify`	Define what to build (functional spec)
`/speckit.clarify`	Resolve underspecified areas (run before /speckit.plan)
`/speckit.plan`	Define how to build it (tech stack, architecture)
`/speckit.tasks`	Generate the actionable task list
`/speckit.analyze`	Cross-artifact consistency & coverage check
`/speckit.implement`	Execute all tasks

Recommended Workflow Summary

Step	Action	Model	Mode
1	Create project directory	—	—
2	git clone from Simplifier App Editor	—	—
3	Add MCPs via .opencode/opencode.json (Simplifier, Fiori, UI5, Playwright)	—	—
4	Run /init-simplifier inside OpenCode	—	—
5	Enter Plan Mode + select Opus 4.5	Opus 4.5	Plan
6	(Large projects) specify init + /speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan	Opus 4.5	Plan
7	Review and approve plan + spec	Opus 4.5	Plan
8	Switch to Build Mode + Sonnet 4.5; /speckit.tasks → /speckit.analyze → /speckit.implement	Sonnet 4.5	Build
9	Commit and push to Simplifier Git	Sonnet 4.5	Build

Tips & Best Practices

One project = one folder = one .opencode/opencode.json. Never share MCP configs across unrelated apps.
Always start in Plan Mode. The cost of a bad plan is far higher than the cost of Opus tokens.
Switch to Sonnet for execution. Building from a clear plan does not require Opus-level reasoning.
Refresh your Simplifier Token after every login. Update SIMPLIFIER_TOKEN in .opencode/opencode.json and restart OpenCode — otherwise calls will fail with auth errors.
Drop external requirements into docs/. Excel, PDF, Word, CSV — let the agent read them; never copy-paste content by hand.
Preserve external IDs. Story IDs (Jira keys, Excel row IDs, FR-/NFR- numbers) belong in the spec for traceability.
Commit often. Use the cloned Simplifier Git repository as your source of truth — push back to the App Editor when work is done.
Use Spec Kit for anything non-trivial. Even a single spec.md dramatically improves agent output.
Keep MCPs up to date. Check MCP connectivity in OpenCode’s status panel periodically.

Troubleshooting

Symptom	Fix
MCP shows as disconnected in OpenCode	Check .opencode/opencode.json for typos in the command or env vars; restart OpenCode
Simplifier MCP shows auth / 401 error	Your SIMPLIFIER_TOKEN expired after re-login → update the token in .opencode/opencode.json and restart OpenCode
Simplifier MCP opens an error page in browser on startup	Read the page — it details the connection issue (wrong URL, invalid token, network) and how to fix it
Agent does not know about Simplifier APIs	Confirm simplifier entry is present and enabled: true in .opencode/opencode.json
Opus 4.5 too slow / too expensive for small edits	Switch to Sonnet 4.5 with /model anthropic/claude-sonnet-4-5 after the plan is locked
Playwright MCP fails to launch browser	Run ‘npx playwright install’ once to install browser binaries `npx playwright install`
`specify: command not found`	Install via uv tool install specify-cli –from git+https://github.com/github/spec-kit.git (or pipx)
`/speckit.*` commands not visible in OpenCode	Re-run specify init . –integration claude inside the project folder, then restart OpenCode
Excel/PDF requirements ignored by agent	Place files in docs/ and explicitly reference the path in your prompt (e.g. docs/UserStories.xlsx)

Current Release