# SAP BusinessObjects MCP Server (`bo-mcp`)

[![FastMCP](https://img.shields.io/badge/FastMCP-2.13.1-blue.svg)](https://github.com/jlowin/fastmcp)
[![MCP](https://img.shields.io/badge/MCP-1.22.0-green.svg)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![Package Manager](https://img.shields.io/badge/uv-package%20manager-purple.svg)](https://astral.sh/uv)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![CI](https://github.com/alexraio/sap-business-objects-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/alexraio/sap-business-objects-mcp/actions/workflows/ci.yml)
[![SAP BO](https://img.shields.io/badge/SAP%20BusinessObjects-BI%204.3%20SP5-orange.svg)](https://www.sap.com)

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 46 specialized enterprise tools directly from natural language prompts.

---

## Table of Contents

- [Key Features](#key-features)
- [Tech Stack](#tech-stack)
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
  - [1. Clone or Open the Repository](#1-clone-or-open-the-repository)
  - [2. Environment Configuration](#2-environment-configuration)
  - [3. Install Dependencies](#3-install-dependencies)
  - [4. Verify MCP Server Installation](#4-verify-mcp-server-installation)
- [Architecture & Deep Dive](#architecture--deep-dive)
  - [Modular Domain Services Architecture](#modular-domain-services-architecture)
  - [Directory Structure](#directory-structure)
  - [System Flow Diagram](#system-flow-diagram)
  - [Domain Services Breakdown](#domain-services-breakdown)
  - [Authentication & Session Lifecycle](#authentication--session-lifecycle)
- [Available MCP Tools Reference (46 Tools)](#available-mcp-tools-reference-46-tools)
  - [1. Authentication (2 Tools)](#1-authentication-2-tools)
  - [2. Universes & Semantic Layer (5 Tools)](#2-universes--semantic-layer-5-tools)
  - [3. Web Intelligence Documents & Lifecycle (5 Tools)](#3-web-intelligence-documents--lifecycle-5-tools)
  - [4. Webi Prompts, Parameters & Refresh (3 Tools)](#4-webi-prompts-parameters--refresh-3-tools)
  - [5. Webi Tabs, Blocks & Tabular Data (5 Tools)](#5-webi-tabs-blocks--tabular-data-5-tools)
  - [6. Data Providers, SQL & Change Data Source (8 Tools)](#6-data-providers-sql--change-data-source-8-tools)
  - [7. Central Management Server (CMS) Admin & Security (8 Tools)](#7-central-management-server-cms-admin--security-8-tools)
  - [8. Schedules & Instance Diagnostics (4 Tools)](#8-schedules--instance-diagnostics-4-tools)
  - [9. InfoStore, Folders & Categories (6 Tools)](#9-infostore-folders--categories-6-tools)
- [Environment Variables](#environment-variables)
- [Client Integration Guide](#client-integration-guide)
  - [1. Google Antigravity IDE](#1-google-antigravity-ide)
  - [2. Antigravity CLI (`agy`)](#2-antigravity-cli-agy)
  - [3. FastMCP Development Inspector (Web UI)](#3-fastmcp-development-inspector-web-ui)
  - [4. Claude Desktop & Other MCP Hosts](#4-claude-desktop--other-mcp-hosts)
- [Available Scripts & Commands](#available-scripts--commands)
- [Testing & Verification](#testing--verification)
- [Contributing Guidelines](#contributing-guidelines)
- [Troubleshooting](#troubleshooting)
- [Security & Operational Best Practices](#security--operational-best-practices)
- [Author & License](#author--license)

---

## Key Features

- **Automated Authentication**: Log on using user/password or trusted credentials, retrieve and store the `X-SAP-LogonToken` transparently across sessions.
- **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.
- **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

| Layer | Component | Version / Description |
| :--- | :--- | :--- |
| **Runtime** | Python | `>= 3.13` (Modern Python 3.13+ typing, dataclasses, pattern matching) |
| **Package Management** | Astral `uv` | Fast virtual environment & dependency management via `pyproject.toml` |
| **MCP Framework** | `fastmcp` | `2.13.1` (FastMCP 2.0 Generation 2, 44 registered tools) |
| **MCP Specification** | `mcp` | `1.22.0` (Standard Model Context Protocol) |
| **HTTP Engine** | `requests` | `2.32.5` persistent HTTP keep-alive session with custom timeout |
| **Data Validation** | `pydantic` | `2.12.5` |
| **Configuration** | `python-dotenv` | `1.2.1` for loading `.env` configuration relative to script location |
| **Target Platform** | SAP BusinessObjects BI | BI 4.3 SP5 (Support Package 5) REST Web Services (`biprws` and `raylight`) |

---

## 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

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

### 2. Environment Configuration

Copy the sample environment file to create your local `.env`:

```bash
cp .env.example .env
```

Configure your SAP BusinessObjects server URL and credentials in `.env`:

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

# Authentication Credentials
SAP_BO_USERNAME="Administrator"
SAP_BO_PASSWORD="YourPasswordHere"
```

> [!IMPORTANT]
> The `.env` file is excluded from git via `.gitignore`. Never commit actual SAP credentials to source control.

### 3. Install Dependencies

Using `uv` (recommended):

```bash
uv sync
```

Alternatively, using standard `pip`:

```bash
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 44 tools are registered:

```bash
uv run fastmcp inspect server.py
```

Expected output:

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

Components
  Tools:        44
  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.

```text
BO_MCP/
├── core/
│   ├── __init__.py
│   ├── client.py              # BOEClient: HTTP keep-alive session, token lifecycle, error handling
│   └── exceptions.py          # Custom domain exceptions (BOEAuthError, BOEProcessingError, etc.)
├── services/
│   ├── __init__.py
│   ├── webi_service.py        # Web Intelligence: prompts, LOVs, refresh, tables, formulas, SQL
│   ├── universe_service.py    # Universes: UNX/UNV, semantic hierarchy (/sl/v1), lineage
│   ├── schedule_service.py    # Schedules: recurring jobs, instance history, failure diagnostics
│   ├── admin_service.py       # CMS Admin: generic SQL queries, users, groups, active sessions
│   └── infostore_service.py   # InfoStore: recursive folder traversal, categories, Webi lists
├── server.py                  # FastMCP server exposing 44 typed MCP tools
├── 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

```text
+-------------------------------------------------------------+
|                     AI Agent Surface                        |
|   (Antigravity IDE / Antigravity CLI "agy" / Claude Desktop)|
+------------------------------+------------------------------+
                               |
                   JSON-RPC over STDIO
                               |
                               v
+-------------------------------------------------------------+
|                    FastMCP Server (server.py)               |
|  - Exposes 44 MCP Tools with docstrings & typed schemas     |
|  - Injects environment variables from .env                  |
+------------------------------+------------------------------+
                               |
                   Delegates to Domain Services
                               |
                               v
+-------------------------------------------------------------+
|               Domain Services Layer (services/)             |
|  ├── 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)
                   - 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 (44 Tools)

### 1. Authentication (2 Tools)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `login` | `username?`, `password?` | Authenticates against SAP BO, acquiring the `X-SAP-LogonToken`. Falls back to `.env` if omitted. |
| `logout` | _none_ | Closes the active session on the BI platform and invalidates the session token. |

### 2. Universes & Semantic Layer (5 Tools)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_universes` | _none_ | Lists all published UNX and UNV universes (ID, name, folder ID). |
| `get_universe_details` | `universe_id` | Retrieves universe type (`unx`/`unv`), name, and CUID. |
| `get_universe_structure` | `universe_id` | Traverses the full business layer tree (classes, dimensions, measures, attributes, hierarchies). |
| `get_universe_related_reports` | `universe_id` | Queries the CMS to find all Webi reports referencing the universe (`SI_SL_DOCUMENTS` / `SI_WEBI`). |
| `get_universe_connection_id` | `universe_id` | Retrieves the Data Connection ID associated with the universe. |

### 3. Web Intelligence Documents & Lifecycle (5 Tools)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_documents` | `page=1`, `pagesize=50` | Retrieves a paginated list of Webi documents from the repository. |
| `get_doc_details` | `webi_doc_id` | Retrieves report metadata: name, folder path, CUID, scheduled status, and state. |
| `get_doc_properties` | `webi_doc_id` | Retrieves document configuration properties (refreshOnOpen, autoRefresh, etc.). |
| `save_webi_doc` | `webi_doc_id`, `webi_doc_name` | Saves/overwrites a Webi document while preserving user comments. |
| `delete_webi_doc` | `webi_doc_id` | Permanently deletes a Webi document from the CMS repository. |

### 4. Webi Prompts, Parameters & Refresh (3 Tools)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_doc_parameters` | `webi_doc_id` | Lists all prompt parameters (ID, prompt question, technical name, data type, optional/mandatory flag). |
| `get_parameter_lov` | `webi_doc_id`, `parameter_id` | Retrieves the List of Values (LOV) allowed for a constrained prompt parameter. |
| `refresh_webi_doc` | `webi_doc_id`, `parameters?` | Injects prompt answers and triggers report calculation in the active session. |

### 5. Webi Tabs, Blocks & Tabular Data (5 Tools)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_reports` | `webi_doc_id` | Lists all sheets/tabs in a Webi document (returns report IDs and tab names). |
| `get_report_elements` | `webi_doc_id`, `report_id` | Lists all visual elements (tables, charts, sections) inside a report tab. |
| `get_report_element_data` | `webi_doc_id`, `report_id`, `element_id`, `max_rows=1000` | Extracts structured tabular data rows from a table block up to `max_rows`. |
| `get_variables` | `webi_doc_id` | Retrieves all calculated variables and custom formulas defined in a document. |
| `get_comments` | `webi_doc_id` | Retrieves collaborative user comments and cell annotations. |

### 6. Data Providers, SQL & Change Data Source (8 Tools)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_dp` | `webi_doc_id` | Lists all Data Provider identifiers (e.g. `DP0`, `DP1`) in a document. |
| `get_dp_details` | `webi_doc_id`, `dp_id` | Retrieves data source name, ID, type, and update status for a Data Provider. |
| `get_dp_sql` | `webi_doc_id`, `dp_id` | **Extracts the raw SQL query** statement generated by the Semantic Layer. |
| `get_dp_specification` | `webi_doc_id`, `dp_id` | Retrieves query specification tree (result objects, query filters, sort rules) via XML specification. |
| `refresh_dp` | `webi_doc_id`, `dp_id` | Refreshes a single Data Provider without recalculating the rest of the report. |
| `purge_dp` | `webi_doc_id`, `dp_id` | Purges cached data rows from a Data Provider to reduce storage size. |
| `get_dp_mapping_proposal` | `webi_doc_id`, `dp_id`, `target_datasource_id`, `strategies?`, `resolve_names?` | **Evaluates Change Data Source mapping strategies** (UNV to UNX or repointing), returning matching statuses (`Ok`, `Ambiguous`, `NotFound`), match rates, and human-readable object names. |
| `change_dp_datasource` | `webi_doc_id`, `dp_id`, `target_datasource_id`, `strategies?`, `custom_mappings?`, `save?` | **Executes Change Data Source** on a Data Provider, applies strategy matches and custom overrides, submits changes to Raylight, and commits to the repository. |

#### 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:

| Strategy | Matching Mechanism | Precision & Safety | Best Used For |
| :--- | :--- | :--- | :--- |
| **`SameID`** | Matches exact internal object IDs (`OBJ_...`). | **100% Deterministic** (Zero risk). | **UNV -> UNX migrations** where the UNX was converted using Information Design Tool (IDT), which preserves original IDs. |
| **`SamePath`** | Matches full qualified folder tree path (`[Class]/[Subclass]/[Object]`). | **Very High (98%)** (Safe). | Distinguishes homonyms safely (e.g. `[Customer]/[Country]` vs `[Supplier]/[Country]`) even if IDs were regenerated. |
| **`SameName`** | Matches exact object display names regardless of folder hierarchy. | **High (85-90%)**. | Universes where classes or folders were reorganized or flattened, but business object names were kept identical. |
| **`SameTechnicalName`** | Matches underlying database column or technical field name. | **High (85%)**. | Scenarios where business names were translated or rebranded, but database column names remain unchanged. |
| **`CloseName`** | Fuzzy string distance (Levenshtein) matching. | **Medium / Caution**. | Minor spelling adjustments or plurals. May produce false positives; recommended only with manual review. |

> [!TIP]
> **Recommended Strategy Chain**: `SameID,SamePath,SameName` (The **Gold Standard** default).
> It guarantees 100% precision for IDT-converted universes, resolves structural hierarchy matches next, and gracefully falls back to display name matching without risking the false positives associated with uncontrolled fuzzy matching. Custom mapping overrides (`custom_mappings=[{"source_id": "...", "target_id": "..."}]`) can be supplied for any unresolved edge cases.

### 7. Central Management Server (CMS) Admin & Security (8 Tools)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `cms_query` | `query`, `page=1`, `pagesize=1000` | **Executes arbitrary CMS SQL queries** against `CI_INFOOBJECTS`, `CI_APPOBJECTS`, `CI_SYSTEMOBJECTS`. |
| `get_users` | `page=1`, `pagesize=100` | Lists user accounts (ID, username, email, disabled status, last logon). |
| `get_user_details` | `user_id` | Retrieves full profile properties of a specific user ID. |
| `set_user_status` | `user_id`, `disabled: bool` | Enables (`disabled=False`) or disables (`disabled=True`) a user account. |
| `get_user_groups` | `page=1`, `pagesize=100` | Retrieves all User Groups along with member counts. |
| `get_group_users` | `group_id` | Lists all users that are members of a specific User Group. |
| `get_active_sessions` | _none_ | Monitors active connections and user sessions open on the CMS. |
| `terminate_session` | `session_id` | Forcibly terminates an active connection session by connection ID. |

### 8. Schedules & Instance Diagnostics (4 Tools)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_doc_schedules` | `webi_doc_id` | Lists scheduled execution rules defined for a Webi document. |
| `get_doc_instances` | `webi_doc_id`, `max_instances=50` | Retrieves historical run instances (*Success*, *Failed*, *Running*) with timestamps. |
| `get_instance_details` | `instance_id` | Retrieves diagnostic information for an instance run, including failure error messages. |
| `delete_instance` | `instance_id` | Deletes a historical report execution instance from the CMS repository. |

### 9. InfoStore, Folders & Categories (6 Tools)
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_folders` | `folder_id` | Recursively traverses subfolder IDs starting from a parent folder. |
| `get_folder_details` | `folder_id` | Retrieves metadata of a repository folder (name, CUID, parent ID, description). |
| `create_folder` | `name`, `parent_folder_id`, `description?` | Creates a new folder in the InfoStore repository under a parent folder. |
| `delete_folder` | `folder_id` | Permanently deletes a folder from the InfoStore repository. |
| `get_webi_docs` | `folder_id` | Lists all Webi document IDs located directly inside a repository folder. |
| `get_categories` | _none_ | Lists all Corporate Categories defined in the BI platform repository. |

---

## Environment Variables

| Variable | Required? | Default | Description | Example |
| :--- | :---: | :---: | :--- | :--- |
| `SAP_BO_REST_API_URL` | **Yes** | `None` | URL to SAP BI Platform REST Web Services (`biprws`) | `http://boserver.corp:8080/biprws` |
| `SAP_BO_USERNAME` | Optional | `None` | Default username for the `login` tool | `Administrator` |
| `SAP_BO_PASSWORD` | Optional | `None` | Default password for the `login` tool | `SecretP@ssw0rd` |

---

## Client Integration Guide

### 1. Google Antigravity IDE

#### Workspace Configuration
Create a `.agents/mcp_config.json` file in your workspace (see [`mcp_config.example.json`](file:///mcp_config.example.json)). When you open this folder in Antigravity IDE, all 46 tools are registered automatically:

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

#### Natural Language Prompts in Sidebar Chat (Agent Mode)
- *"Accedi a SAP BO ed esegui una query CMS per trovare tutti i report Webi che hanno fallito la schedulazione oggi."*
- *"Estrai la query SQL generata dal data provider DP3 del report Webi 6096."*
- *"Mostrami i prompt del report 12345, rispondi con anno=2026 ed esegui il refresh."*
- *"Elenca gli utenti del gruppo Administrators e verifica le sessioni attive sul CMS."*

---

### 2. Antigravity CLI (`agy`)

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

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

Run `agy` and prompt directly:

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

---

### 3. FastMCP Development Inspector (Web UI)

Test tools via an interactive browser form:

```bash
uv run fastmcp dev server.py
```

---

## Available Scripts & Commands

| Command | Purpose |
| :--- | :--- |
| `uv sync --dev` | Install all dependencies including testing and linting tools |
| `uv run pytest` | Run offline unit test suite with coverage report (45 tests) |
| `uv run ruff check .` | Run fast linting and style validation |
| `uv run fastmcp inspect server.py` | Inspect registered tools (verifies all 46 tools) |
| `uv run fastmcp dev server.py` | Launch interactive web inspector for live debugging |
| `uv run python server.py` | Run the MCP server in STDIO mode |

---

## 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 46 FastMCP tools.

### Running Tests Locally
```bash
# 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](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`:
   ```bash
   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

| Symptom / Error | Probable Cause | Recommended Resolution |
| :--- | :--- | :--- |
| `WSR 00999: Internal Server Error` | Corrupt Web Intelligence report structure or invalid REST payload syntax. | Verify document ID via `get_documents`, ensure correct query specification XML, and inspect CMS logs. |
| `401 Unauthorized / Invalid Token` | The `X-SAP-LogonToken` has expired or credentials are invalid. | Run the `login` tool to refresh the session token. |
| `404 Not Found` | The requested document ID, universe ID, or folder ID does not exist in the CMS. | Query the CMS via `cms_query` to confirm object existence and verify folder permissions. |
| `Connection refused / timeout` | Network firewall or routing blocking access to the SAP BO REST port (default `6405` / `8080`). | Verify `BO_BASE_URL` in `.env` and verify connectivity using `curl -v http://<host>:<port>/biprws/infostore`. |

---

## 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](https://github.com/alexraio))
- **Version**: `0.2.0` (Modular Domain Architecture)
- **License**: [Apache License 2.0](LICENSE) - see the [LICENSE](LICENSE) file for complete terms and copyright notices.