# CAPforge

**MCP server that makes your AI agent (Claude Code, Cursor, …) get SAP CAP/CDS right:**
scaffolding that follows real conventions, plus **real validation** against `cds compile`.
The agent doesn't stop until the code compiles clean.

[Website](https://capforge.dev/) · [npm](https://www.npmjs.com/package/capforge) · *Leelo en [español](README.es.md)*

It calls no LLM itself: your agent brings the model (**BYOK**). Zero inference cost, nothing leaves your machine.

## Why

General-purpose models hallucinate CDS — annotation terms that don't exist, OData v2 syntax mixed into v4, invented fields — because there's barely any public CAP code in training data. CAPforge gives your agent the two things it's missing:

1. **Curated, sourced knowledge** — modern CAP/UI5 best practices distilled from official SAP docs (capire, OData vocabularies, reference samples), every rule with its source URL.
2. **A real feedback loop** — tools that run the actual compiler and linter and feed errors back until everything is green.

## Tools

| Tool | What it does |
|---|---|
| `cap_project_context` | **Codebase-aware**: compiles your real project to CSN and returns the existing model (services, entities, fields, associations) so the agent reuses instead of inventing |
| `cap_scaffold_entity` | Generates all 5 layers of an entity following conventions: CDS model with aspects (`cuid`, `managed`), projection, `annotations.cds` (HeaderInfo, LineItem, Facets, FieldGroups), mock CSV, i18n |
| `cap_write_files` | Writes files into the project |
| `cap_validate` | Runs `cds compile` and returns errors (**the loop**) |
| `cap_lint` | Runs `cds lint` (best practices / anti-patterns) |
| `cap_deploy_check` | **Layer 3**: deploys to a throwaway sqlite DB and loads the mock CSVs — catches what `compile` can't (CSV columns that don't exist, bad data, duplicate keys) |
| `cap_analyze_legacy_ui5` | **Migration mode**: inventories a legacy freestyle UI5 app (read-only) — datasources, sections, columns, bound fields, value helps, actions, i18n |
| `ui5_scaffold_section` | Generates a freestyle ObjectPage section (SmartTable with p13nData, or SimpleForm) + handler stubs + i18n |
| `ui5_validate_view` | **The UI5 loop**: well-formed XML + every declared event handler exists in the controller |
| `ui5_lint` | **Layer 3**: runs SAP's official `ui5lint` — deprecated APIs, UI5 2.x readiness, CSP issues |
| resource `conventions://cap` | Canonical knowledge core + your team's convention profile + migration map |

Normal flow: `context` → `scaffold` → `write` → `validate` → correct → until green.
Migration flow: `analyze_legacy` → `context` (target) → propose map (REUSED / NEW / DISCARDED) → `scaffold` → `validate`.

## Requirements

- Node.js 18+
- `@sap/cds-dk` available (globally or in the project) for `cap_validate` to work.

## Install & try

```bash
npm install
node test-loop.js   # full-loop demo against the bundled sandbox
```

### VS Code / SAP Business Application Studio

Install the "CAPforge" extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=automatizatodo.capforge) (also on [Open VSX](https://open-vsx.org/extension/automatizatodo/capforge)): it registers the MCP server automatically for Copilot agent mode, no `mcp.json` editing.

Point the `capforge.conventionsPath` setting to your team's private conventions. BAS note: BAS installs extensions from Open VSX, but its AI assistant does not consume MCP servers natively yet — the extension is ready for the day it does.

### Claude Code / Cursor

Register in Claude Code (project `.mcp.json` or global config):

```json
{
  "mcpServers": {
    "capforge": {
      "command": "npx",
      "args": ["-y", "capforge"]
    }
  }
}
```

Load your team's private conventions (optional):

```json
"env": { "CAPFORGE_CONVENTIONS": "PATH/to/team-conventions.md" }
```

## Make your agent actually use it

Registering an MCP server does not force the agent to call it: agents only invoke tools when they decide the task needs them, and for CAP they often just write CDS from memory. Two ways to fix that:

1. **Workspace instructions (recommended).** Add this to your project's agent instructions file — `.github/copilot-instructions.md` (Copilot), `CLAUDE.md` (Claude Code) or `.cursorrules` (Cursor):

```
For every SAP CAP or UI5 task: call cap_project_context before generating and reuse existing names; scaffold with cap_scaffold_entity / ui5_scaffold_section; validate with cap_validate, cap_lint and cap_deploy_check (UI5: ui5_validate_view, ui5_lint) and correct until everything is green. Never hand-write CDS without a clean cap_validate run.
```

2. **The `cap_workflow` prompt.** CAPforge ships an MCP prompt with the same workflow: pick it from your client's prompt list (in VS Code: type `/` in chat) at the start of a CAP session.

You can also just ask explicitly ("scaffold this with the capforge tools and validate until clean") — but the instructions file is what makes it automatic for the whole team.

## Knowledge

- `knowledge/` — **canonical core**: modern CAP/UI5 best practices (aspects, compositions, drafts, authorization, Fiori annotations, i18n, tooling, migration map), anchored to official SAP docs with cited sources.
- `conventions/` — **house profile**: one team's style, overridable via `CAPFORGE_CONVENTIONS`. Wins over the core on style conflicts.

The `conventions://cap` resource serves both, combined, to the agent.

## Community

The roadmap is decided by the people who build CAP every day: [roadmap discussion](https://github.com/automatizatodo/capforge/discussions/1). Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT.