nimbus-dev-sdk

The MIT-licensed, dependency-free authoring contract for Nimbus connectors and extensions — Python binding.

pip install nimbus-dev-sdk    # note: nimbus-dev-sdk, NOT nimbus-sdk

import nimbus_sdk  # the import name differs from the distribution name

PyPI has a flat namespace and nimbus-sdk belongs to an unrelated project, so the distribution is published as nimbus-dev-sdk.

Quickstart

To go from nothing to a connector that performs the contract-version handshake and then serves MCP tools over the same two streams, follow quickstart-python.md. It scaffolds a project whose manifest.py declares "runtime": "python" — legal only since RFC-0009 widened the enum — and whose tests spawn the connector as a real process.

npx @nimbus-dev/create-connector@latest my-connector --lang python

The scaffolder is a Node CLI published on npm, not a pip-installable front end. Running it needs Node 22+, but only at scaffold time — the project it generates has no Node dependency; neither pyproject.toml nor any test in the generated tree mentions it.

What this is

The contract is defined once, language-neutrally, in docs/spec/. This package carries that specification data and binds it to Python. The TypeScript SDK is the reference implementation; both are held to the same conformance corpus.

The specification data is bundled into the distribution, so it is available without a network call or a checkout:

from nimbus_sdk import load_schema, negotiate_contract_version

schema = load_schema("nimbus-item.schema.json")
result = negotiate_contract_version(["1"], ["1"])  # NegotiationOk(version="1")

Status

Early. This release carries the contract-version constants, the negotiation algorithm, and the published JSON Schemas. It also carries the IPC surface — from nimbus_sdk.ipc import NdjsonLineReader, parse_hello, perform_handshake — deliberately a separate import root from nimbus_sdk, mirroring the . vs ./ipc split the TypeScript package publishes. It now also carries the diagnostics / telemetry contract v0 — from nimbus_sdk.diagnostics import encode_diagnostic, parse_diagnostic, meets_level — a third, likewise separate import root, running the same conformance corpus as the TypeScript reference byte-identically, plus a Python-only format_timestamp helper: datetime.isoformat() emits six fractional digits and a +00:00 offset, and timespec="milliseconds" fixes only the first, so neither produces the contract's timestamp format on its own. This package ships no emitter — there is no Python counterpart to TypeScript's createEmitter — so writing an encoded line to a sink is left to the caller. It now also carries the connector_kit batteries for hand-rolled MCP connectors — from nimbus_sdk.connector_kit import resolve_url_with_base, json_result, require_env — a fourth, likewise separate import root. It carries URL resolution (the kit's SSRF chokepoint) and the should_strip_auth predicate that goes with it, the environment seam, the MCP result builders, the search helpers, an HTTP transport behind a replaceable Transport Protocol, a ToolRouter, and the two REST factories. UrllibTransport enforces url-resolution.md §8 itself — urllib carries Authorization across a cross-origin redirect where fetch strips it, so the kit installs a redirect handler that drops the credential on an origin change, and only on an origin change.

It also carries the manifest signing surface — from nimbus_sdk.signing import canonicalize_manifest, sign_manifest, verify_manifest_signature — another separate import root, binding canonical JSON and the detached JWS envelope in step with the TypeScript and Go bindings. Read the security note before you sign anything in a shared environment: CPython ships no Ed25519 primitive and this package takes no runtime dependency, so the curve arithmetic here is written from scratch and is not constant-time. Signing and key generation both leak through timing to an attacker able to measure them, and are intended for connector authoring and CI rather than a multi-tenant signing service. Verification touches only public data and carries no such caveat. The disclosure is docs/SECURITY.md.

perform_handshake is the one exchange this package performs end to end: write our hello, read the peer's, agree on a contract major or refuse. The stream is injected, never opened — the package does no I/O of its own — and a refusal comes back as a value, because nothing here owns a process to exit.

from nimbus_sdk.ipc import HandshakeOk, NdjsonLineReader, perform_handshake

# `io` is any object with `read() -> bytes | None` and `write(bytes) -> None`. Return
# None at end of stream: sys.stdin.buffer.read() gives b"" there, which would loop.
reader = NdjsonLineReader()  # supply your own if the session keeps reading this stream
result = perform_handshake(io, reader=reader)
if isinstance(result, HandshakeOk):
    result.version  # the agreed contract major, e.g. "1"
    result.pending  # frames the peer sent right after its hello — process these first

It is synchronous, where the TypeScript binding is async. Python's standard streams block and a startup handshake has nothing to overlap with, so async def would drag every connector into an event loop for nothing; an asyncio caller wraps it with await asyncio.to_thread(perform_handshake, io).

Connector kit

nimbus_sdk.connector_kit is the Python binding of @nimbus-dev/sdk/connector-kit — batteries for a hand-rolled MCP connector, not a contract: unlike ipc and diagnostics, it has no conformance corpus of its own beyond url-resolution, which resolve_url_with_base binds. It is deliberately a separate import root from nimbus_sdk, matching the boundary the TypeScript exports map has published since 1.15.0 by giving connector-kit its own entry point.

from nimbus_sdk.connector_kit import json_result, resolve_url_with_base

# resolve_url_with_base is the kit's SSRF chokepoint: a relative path is prefixed onto
# the base, and an absolute URL only passes through when it shares the base's origin.
url = resolve_url_with_base("https://api.example.com", "/v1/issues")
print(url)  # https://api.example.com/v1/issues

result = json_result({"matches": []})
print(result["content"][0]["text"])  # a pretty-printed JSON text block

License

MIT — see LICENSE.