marona-sdk 0.1.3

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

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

pip install marona-sdk

In requirements.txt:

marona-sdk

Import it as:

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

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

@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

app = agent_app.create_fastapi_app()

Run locally:

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

Inspect:

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.

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.

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:

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:

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