# SAP Business AI Agent Suite

A small, self-contained demo of a **Joule-style multi-agent architecture** built
on a **real, standalone Model Context Protocol (MCP) server**, grounded by a
lightweight **RAG knowledge base**, and designed around SAP's **Clean Core**
principles throughout.

This is a portfolio project (mock/generic data only — see [Clean Core & data](#clean-core--data) below).

## Why this exists

This repo focuses specifically on **agentic AI architecture and ABAP AI / Clean
Core concepts** — the areas most relevant to SAP Joule / Business AI extension
roles — as a complement to two earlier repos in the same portfolio:

- **SAP CPI & BTP Integration Examples** — core Integration Suite / iFlow skills.
- **IntelliFleet** — SAP BTP + CAP + Fiori + Business AI end-to-end application.

Repo #3 goes one level deeper: instead of embedding "MCP-style" tool calls
inside one app, it ships a **real standalone MCP server** any MCP-compliant
client could connect to, plus a small **multi-agent orchestrator** that
composes specialized skills the way SAP Joule composes skills internally.

## Architecture

```
                     ┌─────────────────────┐
   user query  ───▶  │   Orchestrator       │  routes by intent
                     │   (planner agent)     │  (rule-based, or Claude Haiku
                     └──────────┬────────────┘   if ANTHROPIC_API_KEY is set)
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                        ▼
┌───────────────┐     ┌───────────────────┐     ┌────────────────┐
│ Diagnostics    │     │ Documentation      │     │ Action          │
│ agent          │     │ agent              │     │ agent           │
│ (reads live    │     │ (RAG over mock SAP │     │ (drafts via MCP │
│  device/order/ │     │  help content —    │     │  tool; never    │
│  incident data)│     │  BTP/CPI/ABAP AI)  │     │  writes back)   │
└───────┬────────┘     └────────────────────┘     └────────┬────────┘
        │                                                    │
        └───────────────────┬────────────────────────────────┘
                             ▼
                  ┌─────────────────────┐
                  │  MCP server (stdio)  │  get_device_status, get_customer,
                  │  src/mcp-server/     │  get_order, list_open_incidents,
                  └──────────────────────┘  draft_incident_note
```

### 1. Standalone MCP server (`src/mcp-server/`)

A real [Model Context Protocol](https://modelcontextprotocol.io) server built
with `@modelcontextprotocol/sdk`, run as its own process over stdio — not tool
functions embedded inside one app. It exposes five tools over mock data
(`src/mcp-server/data/mock-data.ts`):

| Tool | Purpose |
|---|---|
| `get_device_status` | Read a device's status + latest telemetry |
| `get_customer` | Read customer master data |
| `get_order` | Read an order |
| `list_open_incidents` | List open incidents, optionally filtered by device |
| `draft_incident_note` | Draft a customer-facing note — **drafting only, never persists** |

Any MCP-compliant client can connect to this server independently of the
agents in this repo (e.g. point Claude Desktop's MCP config at
`src/mcp-server/server.ts` via `tsx`).

### 2. RAG knowledge base (`src/rag/`)

A small curated set of mock SAP-help-style markdown docs covering BTP, CPI/
Integration Suite, ABAP AI & Clean Core, and Joule-style agent architecture
(`src/rag/knowledge-base/`). Retrieval (`src/rag/retriever.ts`) uses a
dependency-free TF-IDF + cosine-similarity search — fully offline, no
embedding API calls. The documentation agent grounds its answers in the
retrieved excerpts, and (optionally) asks Claude to synthesize a short answer
from them; with no `ANTHROPIC_API_KEY`, it returns the excerpts directly.

### 3. Multi-agent orchestration (`src/agents/`)

- `orchestrator.ts` — the planner. Routes a query to one of three
  specialized agents. Uses deterministic keyword rules by default; if
  `ANTHROPIC_API_KEY` is set, uses Claude Haiku for more flexible natural-
  language routing instead (same dual-mode pattern used in IntelliFleet).
- `diagnosticsAgent.ts` — calls MCP read tools to answer operational
  questions ("what's the status of DEV-001?").
- `documentationAgent.ts` — answers conceptual questions via RAG.
- `actionAgent.ts` — drafts a note via the MCP `draft_incident_note` tool.

## Clean Core & data

Every tool the agents can call is the mock equivalent of a **released** SAP
API (a released OData service / wrapped BAPI / event API) — nothing in this
repo reads or writes a simulated core table directly, and `draft_incident_note`
only produces draft text; it never persists anything. See
`src/rag/knowledge-base/abap-clean-core.md` for the underlying principle this
mirrors.

All data (`src/mcp-server/data/mock-data.ts`, the knowledge-base docs) is
generic/mock. No real Cognizant/Electrolux client code, data, or IP appears
anywhere in this repo.

## Running it

```bash
npm install
npm run cli
```

Runs three example queries end-to-end (spawns the MCP server as a subprocess,
routes each through the orchestrator). Pass your own query:

```bash
npm run cli -- "What is the status of DEV-002?"
```

By default this runs fully **offline/deterministic** — no external API calls,
no cost. To enable Claude-assisted routing and documentation synthesis:

```bash
cp .env.example .env   # then fill in ANTHROPIC_API_KEY
```

To run the MCP server standalone (e.g. to point another MCP client at it):

```bash
npm run mcp-server
```

## Tests

```bash
npm test
```

Runs offline against the real MCP server subprocess (`test/mcp-server.test.ts`),
the retriever (`test/retriever.test.ts`), and the orchestrator's routing
(`test/orchestrator.test.ts`) — no API key required.

## Tech stack

Node.js + TypeScript, `@modelcontextprotocol/sdk`, `@anthropic-ai/sdk`
(optional, dual-model Haiku/Sonnet cost-conscious pattern), a dependency-free
in-process TF-IDF retriever, `zod` for tool schemas, `tsx` for running
TypeScript directly, Node's built-in test runner.