Metadata-Version: 2.4
Name: marona-sdk
Version: 0.1.3
Summary: Official developer SDK for building Marona-compatible apps, tool servers, skills, and workflows.
Author: Blessing Nyuwani
License-Expression: MIT
Project-URL: Homepage, https://www.marona.ai
Project-URL: Repository, https://github.com/BlessingNyuwani/agentnet-mcp-sdk
Project-URL: Documentation, https://hub.marona.ai
Keywords: marona,sdk,mcp,agents,ai,tools,workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1.0,>=0.115
Requires-Dist: httpx<1.0,>=0.28
Requires-Dist: mcp<2.0,>=1.28
Requires-Dist: pydantic<3.0,>=2.10
Requires-Dist: uvicorn[standard]<1.0,>=0.34
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: pytest<9.0,>=8.3; extra == "dev"
Requires-Dist: twine<7.0,>=6.0; extra == "dev"
Dynamic: license-file

# Marona SDK

Official developer SDK for building Marona-compatible apps, MCP servers, tool
servers, skills, and workflows.

Use `marona-sdk` when you are building an app that exposes tools to Marona Hub.
Use `marona` when you are building an application or interface that calls a
Marona-compatible runtime.

The SDK helps your app expose the Marona standard automatically:

- `GET /health`
- `GET /manifest`
- `GET /hub-registration`
- `POST /mcp/` using the official MCP Python SDK `FastMCP`
- tool outputs with `status`, `success`, `message`, `content`,
  `content_type`, `presentation_hint`, and `context`

## Install

```bash
pip install marona-sdk
```

In `requirements.txt`:

```text
marona-sdk
```

Import it as:

```python
from marona_sdk import AgentApp, success
```

## 1. Create An App

Every app needs a unique app ID, also called a slug. Examples:

- `weather-mcp`
- `knowledge-mcp`
- `company-crm-mcp`

```python
from marona_sdk import AgentApp, success

agent_app = AgentApp(
    name="Weather Tools",
    slug="weather-mcp",
    description="Weather lookup tools for agents and AI interfaces.",
    category="Weather",
    visibility="public",
)
```

Use `visibility="public"` when the app should be discoverable in Hub.
Use `visibility="private"` when the app is only for the owner's workspace.

## 2. Add A Tool

```python
@agent_app.tool(
    title="Get forecast",
    description="Return the weather forecast for a city.",
    input_schema={
        "type": "object",
        "properties": {
            "city": {"type": "string"},
        },
        "required": ["city"],
        "additionalProperties": False,
    },
)
def get_forecast(city: str) -> dict:
    return success(
        f"The forecast for {city} is sunny.",
        content=f"The forecast for {city} is sunny.",
        content_type="text",
        presentation_hint="display_as_provided",
        context="Display the forecast directly unless the user asks for another format.",
        data={"city": city, "condition": "sunny"},
    )
```

## 3. Run The Server

```python
app = agent_app.create_fastapi_app()
```

Run locally:

```bash
uvicorn examples.hello_server:app --host 127.0.0.1 --port 62900
```

Inspect:

```text
http://127.0.0.1:62900/health
http://127.0.0.1:62900/manifest
http://127.0.0.1:62900/hub-registration
http://127.0.0.1:62900/mcp/
```

## 4. Publish To Marona Hub

`DeveloperHubClient` is for developer workflow commands such as create, sync,
and submit.

```python
from marona_sdk import DeveloperHubClient

client = DeveloperHubClient(
    hub_url="https://hub.marona.ai",
    api_key="mrn_dev_...",
)
```

Apps, devices, bots, and user interfaces should use the separate `marona`
runtime client package.

## Standard Tool Results

All Marona-compatible tools should return the SDK result shape:

- `status`: machine-readable result status
- `success`: boolean result success flag
- `message`: short user-facing status line
- `content`: primary user-facing text or content
- `content_type`: provider-neutral content type, such as `text`, `document`,
  `message`, `list`, `media`, or `search_results`
- `presentation_hint`: provider-neutral usage hint, such as
  `display_as_provided`
- `context`: short guidance for interpreting the result

Provider-specific data should live under generic fields:

- `data`: one structured object
- `items`: a list of structured objects
- `count`: item count when `items` is used
- `artifacts`: generic artifact descriptors
- `job`: generic async job metadata

If a tool declares its own `output_schema`, the SDK merges these standard fields
into that schema before exposing `/manifest` and `/hub-registration`.

## Standard Tool Inputs For User Files

Tools that consume uploaded files should declare the SDK-standard
`attachments` input property. The runtime injects the current conversation
files into that array automatically.

```python
from marona_sdk import standard_attachments_property

input_schema = {
    "type": "object",
    "properties": {
        "question": {"type": "string"},
        "attachments": standard_attachments_property(),
    },
    "required": [],
    "additionalProperties": False,
}
```

Each attachment can include `artifact_id`, `filename`, `mime_type`, `kind`,
`url`, `file_url`, `content_base64`, `content`, and `metadata`.

## Package Names

- Python developer SDK: `marona-sdk`, import `marona_sdk`
- Dart developer SDK: `marona_sdk`, import `package:marona_sdk/marona_sdk.dart`
- TypeScript developer SDK: `marona-sdk`, import from `"marona-sdk"`
- Runtime client SDKs: `marona`

## Release

Build and verify:

```bash
rm -rf dist build marona_sdk.egg-info
python3.11 -m build
python3.11 -m twine check dist/*
```

Upload with the project-scoped PyPI token:

```bash
TWINE_USERNAME=__token__ TWINE_PASSWORD='MARONA_SDK_PROJECT_TOKEN' python3.11 -m twine upload dist/*
```
