marona-sdk 0.1.1

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

Marona SDK

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

It is not the runtime client SDK. Use marona when you want an application to call a Marona-compatible runtime. Use marona-sdk when you are building developer-side integrations that need the Marona tool contract.

The SDK helps projects produce 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 For Local Development

python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Install In A Developer Integration Repo

Developer integration repos can depend on this SDK like any other pip package:

pip install marona-sdk

In requirements.txt:

marona-sdk

It installs from the package index and imports as marona_sdk.

Minimal Server

from marona_sdk import AgentApp, success

agent_app = AgentApp(
    name="Hello Tool Server",
    server_name="hello-tools",
    slug="hello",
    description="Example Marona-compatible tool server.",
    category="Tools",
)

@agent_app.tool(description="Say hello to a user.")
def say_hello(name: str) -> dict:
    return success(f"Hello {name}.", greeting=f"Hello {name}.")

app = agent_app.create_fastapi_app()

Standard Tool Results

All Marona-compatible tools should return the SDK result shape. The required fields are:

• status: machine-readable result status.
• success: boolean result success flag.
• message: short user-facing status line.
• content: primary user-facing text/content for the agent to use.
• content_type: provider-neutral semantic type, for example text, document, message, list, media, or search_results.
• presentation_hint: provider-neutral usage hint, for example display_as_provided.
• context: short provider-neutral guidance for interpreting the result.

Provider-specific payloads must live under generic standard fields:

• data: one structured provider-specific object.
• items: a list of structured provider-specific 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 Edge runtime injects the current conversation files into that array automatically, so the tool does not need custom runtime logic or a provider-specific input name.

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.

Example:

return success(
    "Loaded email.",
    content=email_text,
    content_type="email_message",
    presentation_hint="display_as_provided",
    context="Return content as provided unless the user asks for a summary.",
)

Run it:

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

Then inspect:

http://127.0.0.1:62900/health
http://127.0.0.1:62900/hub-registration
http://127.0.0.1:62900/mcp/

Developer Hub Helper

DeveloperHubClient is only for developer workflow commands such as create, sync, and submit. Apps, devices, bots, and user interfaces should use the separate marona runtime client package.

Release

Build and verify the package before uploading:

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

For normal marona-sdk releases, upload with the project-scoped PyPI token:

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

For the first upload of a new package, PyPI requires an account-scoped upload token. After the project exists, use a project-scoped token for normal releases.