Metadata-Version: 2.4
Name: claribi-mcp
Version: 0.1.0
Summary: Python client for the clariBI MCP server. Typed tool methods auto-generated from the live tool catalog.
Author-email: clariBI <support@claribi.com>
License: MIT
Project-URL: Homepage, https://claribi.com/docs/mcp/overview
Project-URL: Documentation, https://claribi.com/docs/mcp/sdks
Project-URL: Repository, https://github.com/ICS-cz/Claribi
Project-URL: Bug Tracker, https://github.com/ICS-cz/Claribi/issues
Project-URL: Changelog, https://github.com/ICS-cz/Claribi/blob/master/CHANGELOG.md
Keywords: claribi,mcp,model-context-protocol,analytics,bi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# claribi-mcp

Python client for the [clariBI MCP Server](https://claribi.com/app/developer-portal).

The clariBI MCP Server lets you sign up users, list dashboards, run
analyses, and generate reports via the [Model Context Protocol](https://modelcontextprotocol.io).
This SDK is a thin synchronous JSON-RPC client built on `httpx`
with one typed Python method per registered server tool:

```python
from claribi_mcp import Client

with Client(api_key="claribi_mcp_...") as client:
    client.initialize()
    dashboards = client.list_dashboards()
    print(dashboards.structured["items"])

    result = client.run_analysis(question="What was revenue last quarter?")
    print(result.text)
```

## Install

```bash
pip install claribi-mcp
```

## Authentication

Either:

* **API key** — mint a `claribi_mcp_*` key from
  [Developer Portal → MCP Server → Clients & Keys](https://claribi.com/app/developer-portal)
  and pass it as `api_key=`.
* **OAuth 2.1 bearer token** — pass `auth=BearerTokenAuth(access_token=..., refresh_callable=...)`.

```python
from claribi_mcp import Client, BearerTokenAuth

def refresh():
    new_token, new_expires_at = some_oauth_refresh()
    return new_token, new_expires_at

client = Client(
    auth=BearerTokenAuth(
        access_token=initial_token,
        expires_at=initial_expires_at,
        refresh_callable=refresh,
    ),
)
```

## Tool surface

The SDK exposes one typed method per server tool. Methods are
auto-generated from the live `/api/mcp-server/tool-catalog/`
endpoint so they always match what the server actually supports.

Headline methods (read-only):

* `client.list_dashboards(limit=20, offset=0, search=None)`
* `client.get_dashboard(dashboard_id=...)`
* `client.list_reports(...)`, `client.get_report(...)`
* `client.list_data_sources(...)`, `client.get_data_source_schema(...)`
* `client.get_usage()`, `client.get_billing_status()`
* `client.check_pricing(tier=None)`

Write methods (require `analysis:run`, `reports:write`, etc. scopes):

* `client.run_analysis(question=..., wait_seconds=30)`
* `client.get_analysis_status(job_id=...)`
* `client.generate_report(name=..., template_id=None, output_format='pdf')`
* `client.create_checkout_session(tier='professional', billing_period='monthly')`

Signup methods (no auth required):

* `client.register_account(email=..., organization_name=..., accept_terms=True)`
* `client.verify_email(pending_id=..., code=..., password=...)`

## Sign up via SDK

```python
client = Client()  # no auth — public tools only
pending = client.register_account(
    email="me@example.com",
    organization_name="My Team",
    accept_terms=True,
)
pending_id = pending.structured["pending_id"]
code = input("Enter the 6-digit code from your email: ")
verified = client.verify_email(
    pending_id=pending_id,
    code=code,
    password="a-strong-password",
)
api_key = verified.structured["mcp_api_key"]
print(f"Save this key: {api_key}")
```

## Codegen

Regenerate the typed tool surface against your server:

```bash
python scripts/codegen.py \
    --catalog https://claribi.com/api/mcp-server/tool-catalog/ \
    --output  claribi_mcp/generated
```

## License

MIT.
