SAP BusinessObjects MCP Server (bo-mcp)

A Model Context Protocol (MCP) server that exposes SAP BusinessObjects BI Platform 4.3 SP5 administration, semantic analysis, and Web Intelligence inspection capabilities to AI coding assistants and autonomous agents. Built using FastMCP 2.0 and the SAP BI Platform REST Web Services (biprws and raylight), this server enables AI agents (such as Google Antigravity IDE, Antigravity CLI agy, Claude Desktop, and Cursor) to execute 48 specialized enterprise tools directly from natural language prompts.

Table of Contents

• Key Features

• Tech Stack

• Prerequisites

• Getting Started

  • 1. Clone or Open the Repository

  • 2. Environment Configuration

  • 3. Install Dependencies

  • 4. Verify MCP Server Installation

• Architecture & Deep Dive

  • Modular Domain Services Architecture

  • Directory Structure

  • System Flow Diagram

  • Domain Services Breakdown

  • Authentication & Session Lifecycle

• Available MCP Tools Reference (48 Tools)

  • 1. Authentication (2 Tools)

  • 2. Universes & Semantic Layer (5 Tools)

  • 3. Web Intelligence Documents & Lifecycle (5 Tools)

  • 4. Webi Prompts, Parameters & Refresh (3 Tools)

  • 5. Webi Tabs, Blocks & Tabular Data (5 Tools)

  • 6. Data Providers, SQL & Change Data Source (8 Tools)

  • 7. Central Management Server (CMS) Admin & Security (8 Tools)

  • 8. Schedules & Instance Diagnostics (4 Tools)

  • 9. InfoStore, Folders & Categories (6 Tools)

  • 10. Intelligent Diagnostics & Batch Health Monitoring (1 Tool)

• Environment Variables

• Client Integration Guide

  • 1. Google Antigravity IDE

  • 2. Antigravity CLI (agy)

  • 3. FastMCP Development Inspector (Web UI)

  • 4. Claude Desktop & Other MCP Hosts

• Agent Skill: sap-business-objects

• Available Scripts & Commands

• Testing & Verification

• Contributing Guidelines

• Troubleshooting

• Security & Operational Best Practices

• Author & License

Related MCP server: bw-modeling-mcp

Key Features

• Enterprise Authentication & Zero-Plaintext Security: Interactive CLI credential intake with masked input (getpass), OS Keyring integration (macOS Keychain, Windows Credential Manager, Linux SecretService), and automatic account discovery. Eliminates plaintext passwords in .env files or LLM chat transcripts.

• Session Isolation & Native SAP BO Security Rights: Manages independent client sessions with dedicated BOEClient instances and X-SAP-LogonToken tokens, strictly preserving individual SAP BO user permissions, folder access, and universe row-level security.

• Web Intelligence Execution & Data Extraction: Retrieve prompts, query Allowed Values (LOV), answer prompts, trigger live document refresh, and extract tabular cell data from table and chart blocks without generating bloated binary files.

• Data Provider SQL Inspection: Extract the raw SQL query generated by the Semantic Layer for any Data Provider in a report.

• Central Management Server (CMS) SQL Engine: Execute arbitrary CMS SQL queries against CI_INFOOBJECTS, CI_APPOBJECTS, and CI_SYSTEMOBJECTS for deep platform introspection.

• User & Security Administration: List user accounts, inspect profile details, enable/disable accounts, list user groups, inspect group memberships, monitor active sessions, and terminate connections.

• Semantic Layer & Universe Lineage: Query UNX and UNV universes, inspect business classes/dimensions/measures, and map reports referencing each universe.

• Schedule & Instance Diagnostics: View scheduled execution rules, inspect instance history (Success, Failed, Running), and diagnose error messages of failed jobs.

• Intelligent Diagnostics & Batch Health Monitoring: Scan, cluster, and diagnose failed nocturnal batch executions (SI_SCHEDULE_STATUS = 3) for Web Intelligence reports and Publications (bursting). Normalizes error signatures and delivers Pydantic v2 structured reports with up to 3 ranked probable causes and actionable administrator remediation steps.

• Repository Hierarchy Traversal: Recursively traverse CMS folder trees and corporate categories.

• Modular & Web-Ready: Architecture decoupled into standalone domain services (services/), ready for native integration into a future FastAPI or Flask web application.

Tech Stack

Prerequisites

1. Python 3.13+: Verified with Python 3.13.0+.

2. uv Package Manager (recommended) or standard pip + python3 -m venv.

   • Install uv on macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

   • Or via Homebrew: brew install uv

3. Network Access to SAP BusinessObjects 4.3 SP5:

   • Access to your SAP BI Platform REST Web Services URL (typically http://<host>:<port>/biprws).

   • A valid SAP BusinessObjects user account (e.g. Enterprise, LDAP, or WinAD) with rights to query the CMS and access Web Intelligence documents.

Getting Started

1. Clone or Open the Repository

git clone https://github.com/your-username/BO_MCP.git
cd BO_MCP

2. Authentication Configuration

The MCP server supports two credential methods, resolved by priority:

Option A (Recommended for Enterprise): Secure OS Keyring (Zero-Plaintext)

Store credentials directly in your operating system's native encrypted keychain (macOS Keychain, Windows Credential Manager, or Linux SecretService). Passwords are never written to disk in plaintext or logged.

1. Run the interactive configuration wizard:

   python server.py configure

   (Prompts for API URL, Username, and Password with masked input via getpass)

2. Manage or test stored credentials:

   python server.py status    # Check active resolved credentials
   python server.py test      # Test stored credentials against the live SAP BO server
   python server.py clear     # Remove credentials from the OS Keyring

3. Manual OS Keyring Configuration (No Python/CLI required): You or your IT administrator can also add the credential directly in the OS GUI:

   • macOS (Keychain Access): Add a new generic password item with service sap-business-objects-mcp, your SAP username, and password.

   • Windows (Credential Manager): Under Windows Credentials -> Add a generic credential, specify Internet or network address sap-business-objects-mcp, your username, and password.

   • Linux (Seahorse / SecretService): Add an item under default keyring with service sap-business-objects-mcp.

4. OS Keyring Account Auto-Discovery: If credentials are saved in the OS Keyring, you do not need to store your username in configuration files. If SAP_BO_USERNAME is omitted from .env or client configuration, the server automatically discovers the active account name directly from the OS Keyring. You only need to define SAP_BO_REST_API_URL.

Option B (Development / Testing): Local .env File

For local development or automated CI/CD pipelines, you can provide credentials via .env:

cp .env.example .env

# SAP BusinessObjects REST API Configuration (BI 4.3 SP5)
SAP_BO_REST_API_URL="http://your-bo-host:8080/biprws"

# Authentication Credentials (Priority 1 if defined)
SAP_BO_USERNAME="Administrator"
SAP_BO_PASSWORD="YourPasswordHere"

3. Install Dependencies

Using uv (recommended):

uv sync

Alternatively, using standard pip:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

4. Verify MCP Server Installation

Run FastMCP inspection to verify that all 48 tools are registered:

uv run fastmcp inspect server.py

Expected output:

Server
  Name:         SAP Business Objects
  Version:      2.13.1
  Generation:   2

Components
  Tools:        48
  Prompts:      0
  Resources:    0
  Templates:    0

Environment
  FastMCP:      2.13.1
  MCP:          1.22.0

Architecture & Deep Dive

Modular Domain Services Architecture

The codebase follows a clean, domain-driven service architecture. Business logic is separated into independent services, making each module testable in isolation and ready to be imported into a future Web API (e.g., FastAPI) without modifying FastMCP.

BO_MCP/
├── core/
│   ├── auth/                  # Enterprise credential resolution (Keyring, Env, CLI, Auto-discovery)
│   │   ├── __init__.py
│   │   ├── cli.py             # Masked getpass setup wizard (configure, status, test, clear)
│   │   ├── models.py          # AuthCredentials with Pydantic SecretStr protection
│   │   └── providers.py       # ChainedCredentialProvider, Env, Keyring with auto-discovery
│   ├── session.py             # SessionManager & UserSession for multi-user/client isolation
│   ├── client.py              # BOEClient: HTTP keep-alive session, token lifecycle, error handling
│   ├── exceptions.py          # Custom domain exceptions (BOEAuthError, BOEProcessingError, etc.)
│   └── models.py              # Pydantic v2 schemas: BatchDiagnosticsReport, ClusterDiagnosis, etc.
├── wiki/                      # Self-contained LLM-Wiki (Karpathy + Google OKF specification)
│   ├── index.md               # Global OKF catalog & progressive disclosure entry point
│   ├── log.md                 # Chronological append-only operation log
│   ├── raw/                   # Immutable primary sources & original design RFCs
│   ├── architecture/          # System design, Enterprise Auth, Sessions & Diagnostics specs
│   ├── sap_bo/                # SAP BO 4.3 SP5 domain rules (CMS SQL, IDT vs CMC, Raylight)
│   ├── tools/                 # Complete MCP tool catalogs & Tier 1/Tier 2 safety matrices
│   └── troubleshooting/       # Error code triage runbooks (IES 10901, WIS 30553, ORA-01017)
├── services/
│   ├── __init__.py
│   ├── admin_service.py       # CMS Admin: generic SQL queries, users, groups, active sessions
│   ├── diagnostic_service.py  # Intelligent Diagnostics: error clustering, multi-cause ranking, RCA
│   ├── infostore_service.py   # InfoStore: recursive folder traversal, categories, Webi lists
│   ├── schedule_service.py    # Schedules: recurring jobs, instance history, failure diagnostics
│   ├── universe_service.py    # Universes: UNX/UNV, semantic hierarchy (/sl/v1), lineage
│   └── webi_service.py        # Web Intelligence: prompts, LOVs, refresh, tables, formulas, SQL
├── server.py                  # FastMCP server exposing 48 typed MCP tools + Auth CLI subcommands
├── sdk_parser_new.py          # Unified Facade ensuring 100% backward compatibility
├── .agents/
│   └── mcp_config.json        # Workspace configuration for Antigravity IDE
├── .env                       # Local environment secrets (excluded from git)
├── .env.example               # Clean configuration template
└── README.md

System Flow Diagram

+-------------------------------------------------------------+
|                     AI Agent Surface                        |
|   (Antigravity IDE / Antigravity CLI "agy" / Claude Desktop)|
+------------------------------+------------------------------+
                               |
                   JSON-RPC over STDIO
                               |
                               v
+-------------------------------------------------------------+
|                    FastMCP Server (server.py)               |
|  - Exposes 48 MCP Tools with docstrings & typed schemas     |
|  - Subcommands: configure, status, test, clear              |
+------------------------------+------------------------------+
                               |
              SessionManager (core/session.py)
              Resolves credentials via ChainedCredentialProvider
              (Priority 1: .env -> Priority 2: OS Keyring)
                               |
                               v
+-------------------------------------------------------------+
|               Domain Services Layer (services/)             |
|  ├── DiagnosticService  (Batch RCA, Error Clustering, Models)|
|  ├── WebiService        (Prompts, Refresh, Blocks, SQL)     |
|  ├── UniverseService    (Semantic Tree, Lineage, UNX/UNV)   |
|  ├── ScheduleService    (Instances, Diagnostics, Jobs)      |
|  ├── AdminService       (CMS SQL Query, Users, Groups)      |
|  └── InfostoreService   (Folders, Categories)               |
+------------------------------+------------------------------+
                               |
                   BOEClient (core/client.py)
                   - Isolated per UserSession
                   - requests.Session() keep-alive
                   - X-SAP-LogonToken lifecycle
                   - Configurable timeouts (default 120s)
                               |
                               v
+-------------------------------------------------------------+
|            SAP BusinessObjects Enterprise (biprws)          |
|  ├── /biprws/logon/long       (Authentication)              |
|  ├── /biprws/raylight/v1      (Web Intelligence API)        |
|  ├── /biprws/sl/v1            (Semantic Layer API)          |
|  ├── /biprws/infostore        (InfoStore Hierarchy API)     |
|  └── /biprws/v1/cmsquery      (Central Management Server)   |
+-------------------------------------------------------------+

Available MCP Tools Reference (48 Tools)

1. Authentication (2 Tools)

2. Universes & Semantic Layer (5 Tools)

3. Web Intelligence Documents & Lifecycle (6 Tools)

4. Webi Prompts, Parameters & Refresh (3 Tools)

5. Webi Tabs, Blocks & Tabular Data (5 Tools)

6. Data Providers, SQL & Change Data Source (8 Tools)

Change Data Source & Mapping Strategies Evaluation

When migrating reports from UNV to UNX or repointing between universes, the SAP Raylight REST engine evaluates objects using one or more mapping strategies from left to right:

7. Central Management Server (CMS) Admin & Security (8 Tools)

8. Schedules & Instance Diagnostics (4 Tools)

9. InfoStore, Folders & Categories (6 Tools)

10. Intelligent Diagnostics & Batch Health Monitoring (1 Tool)

Automated Root Cause Analysis (RCA) & Error Clustering

The diagnose_batch_failures tool automates nocturnal batch monitoring and incident triage by querying the CMS repository (CI_INFOOBJECTS) via POST /biprws/v1/cmsquery for instances with SI_SCHEDULE_STATUS = 3 (Failed).

1. Error Normalization: Recursively extracts text from nested CMS error structures (SI_STATUSINFO, SI_SUBST_STRINGS, SI_RESOURCEID), strips volatile runtime noise (timestamps, thread PIDs, hex addresses, IP addresses), and isolates standard SAP BO and database error codes (WIS, ORA, CRS, FBE, socket timeouts).

2. Signature Clustering & Deduplication: Groups identical failures into clusters using deterministic SHA-256 fingerprinting. This prevents LLM context exhaustion when diagnosing hundreds of batch failures.

3. Smart Context Enrichment: For clusters linked to prompt or calculation errors (WIS 30270, WIS 30271), automatically queries /biprws/raylight/v1/documents/{id}/parameters to identify unmapped or missing mandatory prompt parameters.

4. Multi-Cause Ranking & Actionable Remediation: Assigns up to 3 ranked potential causes per cluster with confidence scores (probability_score) and concrete administrator remediation actions.

5. Pydantic v2 Structured Output: Returns a strictly validated BatchDiagnosticsReport model for programmatic consumption.

Environment Variables

Client Integration Guide

1. Google Antigravity IDE

Workspace Configuration

Create a .agents/mcp_config.json file in your workspace (see mcp_config.example.json). When you open this folder in Antigravity IDE, all 48 tools are registered automatically:

{
  "mcpServers": {
    "sap-business-objects": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "env": {}
    }
  }
}

Natural Language Prompts in Sidebar Chat (Agent Mode)

• "Log into SAP BusinessObjects and perform intelligent diagnostics on batch executions that failed in the last 12 hours."

• "Execute a CMS query to list all Webi report instances that failed scheduling today."

• "Extract the raw SQL query generated by data provider DP3 of Webi report 6096."

• "Inspect prompt parameters for report 12345, answer with year=2026, and trigger a document refresh."

• "List all user accounts in the Administrators group and inspect active CMS sessions."

• "Traverse the corporate repository hierarchy starting from Public Folders (ID 23)."

2. Antigravity CLI (agy)

Add the server to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "sap-business-objects": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/BO_MCP",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

Run agy and prompt directly:

agy
> Login to SAP BusinessObjects and list all active CMS sessions.

3. FastMCP Development Inspector (Web UI)

Test tools via an interactive browser form:

uv run fastmcp dev server.py

4. Claude Desktop & Other MCP Hosts

For Anthropic Claude Desktop, add the configuration to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

With credentials stored securely in your OS Keyring, no passwords or usernames are needed in the config:

{
  "mcpServers": {
    "sap-business-objects": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/BO_MCP",
        "run",
        "python",
        "server.py"
      ],
      "env": {
        "SAP_BO_REST_API_URL": "http://your-bo-host:8080/biprws"
      }
    }
  }
}

Agent Skill: sap-business-objects

The repository includes a production-grade operational skill located at .agents/skills/sap-business-objects, designed for Google Antigravity, Gemini CLI (agy), and compatible autonomous AI agents.

Core Capabilities:

• Autonomous Intent Routing: Matches user prompts to the exact MCP tools across 7 operational domains (universes, Webi documents, prompts, tabular data, exports, CMS administration, and batch failure RCA).

• Safe-by-Default Action Tiers: Enforces confirmation protocols for destructive actions (e.g., delete_webi_doc, terminate_session, set_user_status) while running safe queries autonomously.

• Dedicated Operational Runbooks:

  • semantic_and_webi.md: Step-by-step guidance for universes, SQL extraction, table block extraction, and in-session refreshed PDF/Excel/CSV exports.

  • cms_admin_and_security.md: Virtual table querying (CI_INFOOBJECTS, CI_SYSTEMOBJECTS, CI_APPOBJECTS), session monitoring, and user/group administration.

  • batch_diagnostics_and_schedules.md: Root cause analysis (RCA) for nocturnal batch failures, error clustering, and strict IDT connection testing rules.

• Repository Rules (project_rules.md): Defines architectural standards and enforces that SAP BusinessObjects relational connection testing is performed exclusively via the Information Design Tool (IDT), never the Central Management Console (CMC).

Available Scripts & Commands

Testing & Verification

The project includes an offline unit test suite powered by pytest, pytest-mock, and pytest-cov.

Why Offline Testing?

Because SAP BusinessObjects Enterprise (BOE) requires a complex, proprietary on-premise installation and commercial licenses, tests are designed to execute completely offline in < 1 second without connecting to a live SAP server. They simulate:

• HTTP status codes (200, 401 Unauthorized, 404 Not Found, 500 Internal Server Error).

• SAP BI platform specific error payloads (WSR 00999, invalid session tokens).

• REST content negotiation (JSON vs. XML Accept: text/xml headers for query specifications).

• Automatic and custom mapping strategies for changing Webi data sources.

• Integrity and docstring coverage for all 48 FastMCP tools.

• Intelligent diagnostics error signature clustering, multi-cause ranking, and Pydantic validation.

Running Tests Locally

# Run all unit tests
uv run pytest

# Run with test coverage report
uv run pytest --cov=core --cov=services --cov=server --cov-report=term-missing

# Run code style & formatting checks
uv run ruff check .
uv run ruff format --check .

Contributing Guidelines

Contributions are welcome! Whether you are fixing bugs, adding new SAP BO REST tools, or improving documentation, we appreciate your help.

For full contribution details, please read CONTRIBUTING.md.

Quick Contribution Workflow

1. Fork & Clone: Fork the repository on GitHub and clone your fork locally.

2. Environment Setup: Install development dependencies with uv sync --dev.

3. Branching: Create a focused feature branch off main:

   git checkout -b feat/your-feature-name

4. Code Standards:

   • Follow PEP 8 and project style using uv run ruff check --fix . and uv run ruff format ..

   • Maintain type annotations and descriptive docstrings for all @mcp.tool() functions.

   • Keep domain business logic inside services/ and transport/session logic inside core/client.py.

5. Testing:

   • Add offline unit tests in tests/ using MockBOEClient. Do not write tests that require a live SAP BO server.

   • Ensure all existing and new tests pass: uv run pytest.

6. Submit a Pull Request: Push your branch to GitHub and open a Pull Request targeting main. The automated GitHub Actions CI will validate your PR against Python 3.13.

Troubleshooting

Security & Operational Best Practices

1. Protect Sensitive Credentials: Never commit .env files, logon tokens, or CMS credentials to source control. Use .env.example as a template.

2. Least Privilege: Configure dedicated SAP BO service accounts with permissions restricted to the target universes, folders, and reports required for your AI workflows.

3. Session Hygiene: Always log off inactive sessions using the logout tool or terminate orphaned sessions via terminate_session.

4. Production Safeguards: Exercise caution when using destructive tools like delete_webi_doc, delete_folder, purge_dp, or set_user_status.

Author & License

• Author: Alessio Ballarin (@alexraio)

• Version: 0.2.0 (Modular Domain Architecture)

• License: Apache License 2.0 - see the LICENSE file for complete terms and copyright notices.