Skip to main content
Glama
SAP B1 Briefing MCP Server

SAP B1 Briefing MCP Server

README.md
# SAP B1 Briefing MCP Server

An MCP (Model Context Protocol) server that lets Claude answer sales-prep questions —
recent orders, overdue invoices, stock availability, follow-up suggestions — about SAP
Business One-style customer data, conversationally.

Inspired by Tom Cenens' LinkedIn article
["From the Driver's Seat to SAP: A Real-World AI Demo"](https://www.linkedin.com/pulse/from-drivers-seat-sap-business-one-real-world-ai-demo-tom-cenens-5xxbe),
which paired Claude's voice mode with a commercial SAP Business One MCP connector
("Amista AI Data Enabler") for hands-free customer briefings from a car. This project is an
original implementation — it does not use or copy that product — built directly against the
shape of SAP Business One's own Service Layer data, with mock data standing in for a real
system.

## What this is (and isn't), today

- **Data**: mock, in-memory data shaped like real SAP Business One Service Layer entities
  (`BusinessPartners`, `Orders`, `Invoices`, `Items`), not a live SAP connection. See
  [`src/data/sap-service-layer/README.md`](src/data/sap-service-layer/README.md) for what a
  real backend would need.
- **Transport**: local stdio only, for Claude Desktop. No remote hosting, no mobile/CarPlay
  replication of the original demo (that needs a hosted server with OAuth — a documented
  future phase, not built here).
- **Tools**: read-only. No tool can modify SAP data.

## Setup

```powershell
npm install
npm run build
```

Add this to Claude Desktop's config (Windows: `%APPDATA%\Claude\claude_desktop_config.json`),
adjusting the path if this project lives somewhere else — Claude Desktop requires absolute
paths here:

```json
{
  "mcpServers": {
    "sap-b1-demo": {
      "command": "node",
      "args": ["C:\\Users\\Mukesh Kumar\\Desktop\\Mukesh-Claude\\dist\\index.js"]
    }
  }
}
```

(Also at [`.claude-desktop/claude_desktop_config.sample.json`](.claude-desktop/claude_desktop_config.sample.json).)

Restart Claude Desktop, then see [`docs/demo-script.md`](docs/demo-script.md) for a scripted
walkthrough, including the "misspoken customer name" moment the original demo highlighted.

## Development

```powershell
npm run dev          # run directly with tsx, no build step
npm test             # vitest
npm run lint          # eslint
npm run typecheck     # tsc --noEmit
npm run format        # prettier --write
```

`.env.example` documents the environment variables this server reads; copy it to `.env` if
you need to override `LOG_LEVEL`. `DATA_PROVIDER=mock` is the only implemented backend today.

## Architecture

```
src/
├── index.ts, server.ts        # stdio transport bootstrap, McpServer wiring
├── config/, logging/, errors/ # env config, stderr-only structured logging, safe error mapping
├── domain/                    # types/enums shaped like real SAP B1 Service Layer entities
├── data/                      # DataProvider interface + mock implementation (the backend swap seam)
├── matching/                  # shared fuzzy-matching logic (customers + items)
├── tools/                     # the 5 MCP tools
```

Protocol wiring, business logic, domain modeling, and data access are kept in separate layers
so that wiring up a real SAP Business One Service Layer backend later only touches
`src/data/sap-service-layer/` plus a config flag — nothing in `src/tools/` or `src/domain/`
needs to change.

### Tools

| Tool | Purpose |
|---|---|
| `find_business_partner` | Fuzzy name search for a customer/vendor; returns ranked candidates, never a hard "not found" on a near-miss. |
| `get_recent_sales_orders` | A customer's recent sales orders by `CardCode`. |
| `get_open_overdue_invoices` | A customer's open/overdue AR invoices, with balance due and days overdue. |
| `check_item_availability` | Fuzzy item lookup with on-hand/committed/available stock. |
| `get_followup_suggestions` | Deterministic, rule-based visit talking points (overdue invoices → high, open orders → medium, reorder opportunities → low). |

## Security notes

- No credentials are hardcoded anywhere; env-var config (`src/config/env.ts`) reserves
  `SAP_SERVICE_LAYER_URL` / `SAP_COMPANY_DB` / `SAP_USERNAME` / `SAP_PASSWORD` for a future
  real backend, unused while `DATA_PROVIDER=mock`.
- When a real SAP Business One connection is wired up, use a dedicated, least-privilege,
  read-only integration user scoped to only the entities this server needs.
- Future OData filter construction must escape user-provided strings (see the
  `sap-service-layer/README.md` notes) to avoid filter injection.
- `npm audit` currently flags advisories against `vitest`/`vite`/`esbuild`'s dev-server chain
  (dev-only tooling, never exposed to a network here) and against the zod 4.x line generally;
  this project resolves to zod 3.25.x, which the advisory does not affect. Re-check
  `npm audit` before upgrading either.

## Out of scope (Phase 2 / future work)

- Real SAP Business One Service Layer integration.
- Remote/hosted MCP transport with OAuth, for a mobile + CarPlay replication of the original
  demo.
- Write/mutation tools (this phase is deliberately read-only).
- A "prompt library" feature (the original article mentions saving a reusable prompt for this
  scenario).
- Multi-tenant/multi-company support, caching, pagination beyond simple `limit` params,
  telemetry.

## CI

The CI workflow lives at [`docs/ci.yml.example`](docs/ci.yml.example) rather than
`.github/workflows/ci.yml` — it was moved out of `.github/workflows/` only because the GitHub
token used to push this repo didn't have the `workflow` scope needed to push a workflow file.
To enable it: `gh auth refresh -h github.com -s workflow`, then
`git mv docs/ci.yml.example .github/workflows/ci.yml` and push.

## License

MIT — see [LICENSE](LICENSE).

TDQS

A3.8/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a clearly distinct resource and action: business partner lookup, sales orders, AR invoices, item availability, and an aggregate follow-up generator. The only potential overlap is get_followup_suggestions, but its description explicitly frames it as a heuristic summary for 'what should I follow up on' questions, distinguishing it from the raw-data retrieval tools.

Naming Consistency5/5

All five tools use consistent snake_case verb_noun naming (find_business_partner, get_recent_sales_orders, get_open_overdue_invoices, check_item_availability, get_followup_suggestions). The verb variations (find/get/check) are semantically meaningful rather than inconsistent.

Tool Count5/5

Five tools is well-scoped for a customer-visit briefing server, with each tool earning its place by covering a distinct briefing input. There is no filler or redundancy.

Completeness4/5

The surface covers the core briefing workflow: identify the customer, pull recent orders, surface overdue invoices, check item stock, and synthesize follow-ups. Minor gaps exist around customer profile details (contacts, credit status) and order/invoice line-level detail, but these are workable around for the stated briefing purpose.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues