NitroStack Python SDK Reference — For AI Code Editors

Do not copy TypeScript NitroStack (@McpApp, Zod, UseGuards(), @nitrostack/widgets React SDK). This page is Python-only.

Package: nitrostack (pip install nitrostack). CLI: nitrostack-py.

Agent skills (installed by nitrostack-py init from https://github.com/nitrocloudofficial/skills-python-sdk):

Bootstrap

from nitrostack import McpApplicationFactory
app = await McpApplicationFactory.create(AppModule)
await app.start()

Optional: @mcp_app(module=AppModule, server=ServerConfig(name=..., version=...)) then create(App).

Modules / DI

@module(name="app", controllers=[...], providers=[...], imports=[...], exports=[...])
@injectable(deps=[ServiceA])  # constructor args MUST match deps

ConfigModule.for_root(env_file_path=".env", defaults={...}). Health: @health_check(name=...).

Tools / resources / prompts

@tool(name=..., description=..., input_schema=PydanticModel, output_schema=..., task_support="optional")
@resource(uri=..., name=..., description=..., mime_type="application/json")
@prompt(name=..., description=..., arguments=[PromptArgument(...)])
@initial_tool
@widget("route")  # HTML at widgets/out/route.html

Handler: async def fn(self, input: Model, context: ExecutionContext). Coerce Inspector "" with Pydantic field_validator(..., mode="before").

Pipeline

@use_guards / @use_middleware / @use_interceptors / @use_pipes / @use_filters.

Protocols: can_activate, use, intercept, transform, catch. Built-ins: ApiKeyGuard, JwtGuard, OAuthGuard.

OAuthGuard allows no token when OAUTH_REQUIRED is unset.

Auth modules

ApiKeyModule.for_root, JWTModule.for_root, OAuthModule.for_root. Scopes: has_scope, has_any_scope, has_all_scopes, require_scopes. context.auth.aud is a list.

Extra decorators

@cache(ttl=...), @rate_limit(max=..., window=...), @on_event(name).

Tasks / MRTR

task_support, context.task.update_progress, throw_if_cancelled. input_required, accepted_content.

Testing

from nitrostack.testing import NitroTestingModule
h = await NitroTestingModule.create(AppModule)
await h.call_tool("add", {"input": {"a": 5, "b": 10}})
await h.read_resource("calc://info")
await h.get_prompt("name", {})

Widgets / Studio

Static HTML only. NITROSTACK_APP_MODE=universal|openai|mcp-app. Inspector HTTP /mcp no trailing slash, auth off. NitroStudio folder-connect will not detect Python.

Errors

ToolExecutionError, ValidationError, ResourceNotFoundError, PromptNotFoundError, ConfigurationError, DependencyResolutionError, OAuthError, TokenInactiveError, AudienceMismatchError, task errors.

Imports

from nitrostack import tool, resource, prompt, widget, injectable, module, mcp_app, McpApplicationFactory, ServerConfig, ExecutionContext, use_guards, OAuthGuard, ...

No nitro.yaml. Config is .env + ServerConfig.