# ilias20055/sap-b1-mcp-ai architecture

> Architecture diagram of the GitHub repository ilias20055/sap-b1-mcp-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ilias20055/sap-b1-mcp-ai
- Repository: https://github.com/ilias20055/sap-b1-mcp-ai

## Overview

This is an SAP Business One natural-language assistant with web and terminal entry points. A user request is handled by an AI client that can call MCP tools; those tools inspect metadata, execute read-only SQL, or use SAP’s Service Layer, then return results for presentation and optional Excel export. The web server owns the chat loop, while the CLI runs its own loop. The excerpts show the main orchestration and service calls; several documented capabilities are represented at subsystem level because their implementation details were not sampled.

Main entry points: [`mcp-client.js`](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/mcp-client.js) (AI Agent Client), [`src/services/sql-service.js`](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/services/sql-service.js) (SQL Service), [`src/server/mcp-server.js`](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/server/mcp-server.js) (MCP Server), [`src/services/sap-service.js`](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/services/sap-service.js) (SAP Service Layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_webui["Web UI<br/>[index.html]"]
  node_webserver["Web Server<br/>[server.js]"]
  node_cli["Terminal Client<br/>[mcp-client.js]"]
end

subgraph group_ai["AI Orchestration"]
  node_aiclient["AI Agent Client<br/>[mcp-client.js]"]
  node_gemini{{"Gemini"}}
  node_groq{{"Groq Fallback"}}
  node_excel["Excel Export<br/>[mcp-client.js]"]
end

subgraph group_mcp["MCP Tools"]
  node_mcpserver["MCP Server<br/>[mcp-server.js]"]
  node_schema["Schema Metadata<br/>[mcp-server.js]"]
  node_querytool["SQL Query Tool<br/>[mcp-server.js]"]
  node_saptools["SAP Operations<br/>[mcp-server.js]"]
end

subgraph group_data["SAP Data Access"]
  node_config["Configuration<br/>[config.js]"]
  node_sqlservice["SQL Service<br/>[sql-service.js]"]
  node_database[("SAP B1 SQL")]
  node_sapservice["SAP Service Layer<br/>[sap-service.js]"]
end

node_user(("User"))
node_sapexternal[("SAP B1")]

node_user -->|"enters request"| node_webui
node_webui -->|"sends chat"| node_webserver
node_user -->|"enters query"| node_cli
node_webserver -->|"runs agent loop"| node_aiclient
node_cli -->|"runs terminal flow"| node_aiclient
node_aiclient -->|"requests completion"| node_gemini
node_aiclient -.->|"falls back"| node_groq
node_aiclient -->|"calls tools"| node_mcpserver
node_mcpserver -->|"registers tools"| node_schema
node_mcpserver -->|"registers tools"| node_querytool
node_mcpserver -->|"registers tools"| node_saptools
node_schema -->|"reads columns"| node_sqlservice
node_querytool -->|"executes query"| node_sqlservice
node_saptools -->|"reads data"| node_sqlservice
node_saptools -->|"uses Service Layer"| node_sapservice
node_sqlservice -->|"queries"| node_database
node_sapservice -->|"requests entities"| node_sapexternal
node_config -->|"supplies settings"| node_sapservice
node_config -->|"supplies settings"| node_sqlservice
node_aiclient -.->|"recovers schema"| node_schema
node_aiclient -->|"exports results"| node_excel

click node_webui "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/index.html"
click node_webserver "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/server.js"
click node_cli "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/mcp-client.js"
click node_aiclient "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/mcp-client.js"
click node_excel "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/mcp-client.js"
click node_mcpserver "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/server/mcp-server.js"
click node_schema "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/server/mcp-server.js"
click node_querytool "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/server/mcp-server.js"
click node_saptools "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/server/mcp-server.js"
click node_config "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/utils/config.js"
click node_sqlservice "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/services/sql-service.js"
click node_sapservice "https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/services/sap-service.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webui,node_webserver,node_cli,node_user toneBlue
class node_aiclient,node_gemini,node_groq,node_excel,node_sapexternal toneAmber
class node_mcpserver,node_schema,node_querytool,node_saptools toneMint
class node_config,node_sqlservice,node_database,node_sapservice toneRose
```

## Components

### User Interfaces

- [Web UI](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/index.html): `index.html`
- [Web Server](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/server.js): `server.js`
- [Terminal Client](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/mcp-client.js): `mcp-client.js`

### AI Orchestration

- [AI Agent Client](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/mcp-client.js): `mcp-client.js`
- **Gemini**
- **Groq Fallback**
- [Excel Export](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/mcp-client.js): `mcp-client.js`

### MCP Tools

- [MCP Server](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/server/mcp-server.js): `src/server/mcp-server.js`
- [Schema Metadata](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/server/mcp-server.js): `src/server/mcp-server.js`
- [SQL Query Tool](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/server/mcp-server.js): `src/server/mcp-server.js`
- [SAP Operations](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/server/mcp-server.js): `src/server/mcp-server.js`

### SAP Data Access

- [Configuration](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/utils/config.js): `src/utils/config.js`
- [SQL Service](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/services/sql-service.js): `src/services/sql-service.js`
- **SAP B1 SQL**
- [SAP Service Layer](https://github.com/ilias20055/sap-b1-mcp-ai/blob/main/src/services/sap-service.js): `src/services/sap-service.js`

### Other components

- **User**
- **SAP B1**

## Connections

- User → Web UI: enters request (evidence: `README.md`)
- Web UI → Web Server: sends chat (evidence: `README.md`)
- User → Terminal Client: enters query (evidence: `README.md`)
- Web Server → AI Agent Client: runs agent loop (evidence: `server.js`)
- Terminal Client → AI Agent Client: runs terminal flow (evidence: `mcp-client.js`)
- AI Agent Client → Gemini: requests completion (evidence: `mcp-client.js`)
- AI Agent Client → Groq Fallback: falls back (evidence: `mcp-client.js`)
- AI Agent Client → MCP Server: calls tools (evidence: `mcp-client.js`)
- MCP Server → Schema Metadata: registers tools (evidence: `src/server/mcp-server.js`)
- MCP Server → SQL Query Tool: registers tools (evidence: `src/server/mcp-server.js`)
- MCP Server → SAP Operations: registers tools (evidence: `src/server/mcp-server.js`)
- Schema Metadata → SQL Service: reads columns (evidence: `src/server/mcp-server.js`)
- SQL Query Tool → SQL Service: executes query (evidence: `src/server/mcp-server.js`)
- SAP Operations → SQL Service: reads data (evidence: `src/server/mcp-server.js`)
- SAP Operations → SAP Service Layer: uses Service Layer (evidence: `src/server/mcp-server.js`)
- SQL Service → SAP B1 SQL: queries (evidence: `src/services/sql-service.js`)
- SAP Service Layer → SAP B1: requests entities (evidence: `src/services/sap-service.js`)
- Configuration → SAP Service Layer: supplies settings (evidence: `src/services/sap-service.js`)
- Configuration → SQL Service: supplies settings (evidence: `src/services/sql-service.js`)
- AI Agent Client → Schema Metadata: recovers schema (evidence: `README.md`)
- AI Agent Client → Excel Export: exports results (evidence: `mcp-client.js`)
