Introduction to NitroStack for Python

Name: NitroStack
Author: NitroStack

Welcome to the Python NitroStack SDK. This guide covers the architecture of nitrostack — a NestJS-inspired framework for building production-grade Model Context Protocol (MCP) servers in Python 3.10+.

Do not copy TypeScript @McpApp / Zod examples into a Python project. Use @module, @injectable(deps=[...]), Pydantic BaseModel, and McpApplicationFactory.create.

Agent skill: nitrostack-python-mcp-app-architecture — installed by nitrostack-py init into .cursor/skills/, .claude/skills/, and other agent folders. Source: skills-python-sdk.

What you get

Piece	Python
Package	`nitrostack` (`pip install nitrostack`)
CLI	`nitrostack-py` (also `python -m nitrostack.cli.main`)
Schemas	Pydantic v2 `BaseModel` as `input_schema`
DI	`@injectable(deps=[ServiceA, ServiceB])` + constructor args
Pipeline	`use_guards` / `use_middleware` / `use_interceptors` / `use_pipes` / `use_filters`
Widgets	Static HTML under `widgets/out/{route}.html` + `@widget`
Skills	Cloned from `skills-python-sdk` on `init` / refreshed on `upgrade`

Core architecture

NitroStack Python uses the same mental model as the TypeScript SDK — modules, controllers, providers, and a request pipeline — with Python-idiomatic APIs.

Python

from nitrostack import (
    module,
    injectable,
    tool,
    mcp_app,
    McpApplicationFactory,
    ServerConfig,
    ExecutionContext,
)
from pydantic import BaseModel, Field

class AddInput(BaseModel):
    a: float = Field(description="First number")
    b: float = Field(description="Second number")

@injectable(deps=[])
class CalculatorService:
    def add(self, a: float, b: float) -> float:
        return a + b

@injectable(deps=[CalculatorService])
class CalculatorController:
    def __init__(self, service: CalculatorService):
        self.service = service

    @tool(name="add", description="Add two numbers", input_schema=AddInput)
    async def add(self, input: AddInput, context: ExecutionContext) -> float:
        return self.service.add(input.a, input.b)

@module(name="calculator", controllers=[CalculatorController], providers=[CalculatorService])
class CalculatorModule:
    pass

@module(name="app", imports=[CalculatorModule])
class AppModule:
    pass

Generated apps typically start from main.py with factory-from-module (no @mcp_app class required):

Python

import asyncio
from nitrostack import McpApplicationFactory
from app_module import AppModule

async def main():
    app = await McpApplicationFactory.create(AppModule)
    await app.start()

if __name__ == "__main__":
    asyncio.run(main())

Optional: wrap a class with @mcp_app(module=AppModule, server=ServerConfig(name="...", version="1.0.0")) and pass that class to the factory.

Next steps

Installation — pip install nitrostack and Python 3.10+
Quick Start — scaffold with nitrostack-py init
Server Concepts — modules, DI, ServerConfig