pywry.mcp¶

MCP (Model Context Protocol) server for exposing PyWry widgets to AI agents.

Server¶

pywry.mcp.create_server ¶

create_server(settings: MCPSettings | None = None) -> FastMCP

Create and configure the MCP server with PyWry tools and skills.

Parameters:

Name	Type	Description	Default
`settings`	`MCPSettings`	MCP configuration settings. If None, loads from get_settings().	`None`

Returns:

Type	Description
`FastMCP`	Configured FastMCP server instance.

Raises:

Type	Description
`ImportError`	If fastmcp package is not installed.

pywry.mcp.run_server ¶

run_server(transport: str | None = None, port: int | None = None, host: str | None = None, headless: bool | None = None, settings: MCPSettings | None = None) -> None

Run the MCP server.

All parameters override the corresponding MCPSettings values. If not provided, values are loaded from configuration.

Parameters:

Name	Type	Description	Default
`transport`	`str`	Transport type: "stdio", "sse", or "streamable-http".	`None`
`port`	`int`	Port for HTTP transports (ignored for stdio).	`None`
`host`	`str`	Host for HTTP transports.	`None`
`headless`	`bool`	Run in headless mode (inline widgets). If None, uses config or PYWRY_HEADLESS.	`None`
`settings`	`MCPSettings`	MCP configuration settings. If None, loads from get_settings().	`None`

Raises:

Type	Description
`ValueError`	If unknown transport is specified.

Tool Definitions¶

pywry.mcp.tools.get_tools ¶

get_tools() -> list[Tool]

Return all MCP tools with complete schemas.

Returns:

Type	Description
`list[Tool]`	List of all available MCP tools.

Agentic Tools¶

pywry.mcp.agentic.plan_widget `async` ¶

plan_widget(description: str, ctx: Context) -> str

Plan a PyWry widget from a plain-English description using LLM sampling.

Uses ctx.sample() with a validated WidgetPlan Pydantic model so the LLM returns every field needed to create the widget in a single round-trip. The plan is returned as JSON — pass its fields directly to create-widget.

Parameters:

Name	Type	Description	Default
`description`	`str`	Natural-language description of the widget to build, e.g. "A crypto price dashboard with a refresh button and a symbol selector".	required

pywry.mcp.agentic.build_app `async` ¶

build_app(description: str, ctx: Context, open_window: bool = False) -> str

Autonomously build a complete PyWry widget app from a description.

End-to-end pipeline powered by LLM sampling:

Plan — sample a validated WidgetPlan from the description.
Create — register the widget in the MCP session state.
Export — generate the full runnable Python source code.

The result contains the widget_id and the complete Python code ready to run.

Parameters:

Name	Type	Description	Default
`description`	`str`	Plain-English description of the app to build, e.g. "A task tracker with add/remove buttons and a progress bar".	required
`open_window`	`bool`	When True and a native PyWry window is available, open the widget immediately.	`False`

pywry.mcp.agentic.export_project `async` ¶

export_project(widget_ids: list[str], ctx: Context, project_name: str = 'pywry_app', output_dir: str = '') -> str

Package one or more PyWry widgets into a complete runnable Python project.

Generates the following file tree::

<project_name>/
    main.py            ← entry-point that loads all widgets
    requirements.txt   ← pinned dependencies
    README.md          ← quickstart documentation
    widgets/
        <id>.py        ← one file per widget, fully self-contained

When output_dir is supplied the files are written to disk; otherwise the complete file tree is returned as JSON ({relative_path: content}).

Parameters:

Name	Type	Description	Default
`widget_ids`	`list[str]`	List of widget ids to include (created earlier in this session).	required
`project_name`	`str`	Name for the top-level project directory / Python package.	`'pywry_app'`
`output_dir`	`str`	Optional filesystem path to write the project into. If empty, returns the file contents as JSON.	`''`

pywry.mcp.agentic.scaffold_app `async` ¶

scaffold_app(ctx: Context) -> str

Interactively scaffold a PyWry widget app via multi-turn user elicitation.

Uses ctx.elicit() to progressively collect: - App title and description - Display mode (native window / inline / browser) - Primary widget type - Whether to include Plotly or AG-Grid - Toolbar layout preference

After gathering requirements, calls plan_widget internally to generate the full specification and returns the resulting WidgetPlan JSON plus next steps.

Prompts¶

pywry.mcp.prompts.get_prompts ¶

get_prompts() -> list[Prompt]

Return MCP prompts for agent skills.

Returns:

Type	Description
`list of Prompt`	All available skill prompts.

pywry.mcp.prompts.get_prompt_content ¶

get_prompt_content(name: str) -> GetPromptResult | None

Get the content for a specific prompt.

Parameters:

Name	Type	Description	Default
`name`	`str`	Prompt name (e.g., 'skill:native').	required

Returns:

Type	Description
`GetPromptResult or None`	Prompt content or None if not found.

Resources¶

pywry.mcp.resources.get_resources ¶

get_resources() -> list[Resource]

Return all MCP resources.

Returns:

Type	Description
`list of Resource`	All available MCP resources.

pywry.mcp.resources.get_resource_templates ¶

get_resource_templates() -> list[ResourceTemplate]

Return resource templates for parameterized access.

Returns:

Type	Description
`list of ResourceTemplate`	Available resource templates.

pywry.mcp.resources.read_resource ¶

read_resource(uri: str) -> str | None

Read resource content by URI.

Parameters:

Name	Type	Description	Default
`uri`	`str`	Resource URI (e.g., 'pywry://component/button').	required

Returns:

Type	Description
`str or None`	Resource content or None if not found.

pywry.mcp.resources.get_component_source ¶

get_component_source(component_name: str) -> str | None

Get source code for a component class from toolbar.py.

Parameters:

Name	Type	Description	Default
`component_name`	`str`	Name of the component (e.g., 'button', 'select').	required

Returns:

Type	Description
`str or None`	Source code of the component class or None if not found.

pywry.mcp.resources.export_widget_code ¶

export_widget_code(widget_id: str) -> str | None

Generate Python code to recreate a widget.

Parameters:

Name	Type	Description	Default
`widget_id`	`str`	ID of the widget to export.	required

Returns:

Type	Description
`str or None`	Python code to recreate the widget or None if not found.

pywry.mcp.resources.read_component_doc ¶

read_component_doc(comp_name: str) -> str | None

Read component documentation.

Parameters:

Name	Type	Description	Default
`comp_name`	`str`	Component name.	required

Returns:

Type	Description
`str or None`	Markdown documentation or None if not found.

pywry.mcp.resources.read_source_code ¶

read_source_code(comp_name: str) -> str | None

Read component source code.

Parameters:

Name	Type	Description	Default
`comp_name`	`str`	Component name or 'components' for all.	required

Returns:

Type	Description
`str or None`	Source code or None if not found.

pywry.mcp.resources.read_events_doc ¶

read_events_doc() -> str

Read built-in events documentation.

Returns:

Type	Description
`str`	Markdown documentation of all built-in events.

pywry.mcp.resources.read_skill_doc ¶

read_skill_doc(skill_name: str) -> str | None

Read skill documentation.

Parameters:

Name	Type	Description	Default
`skill_name`	`str`	Name of the skill.	required

Returns:

Type	Description
`str or None`	Skill documentation or None if not found.

pywry.mcp.resources.read_quickstart_guide ¶

read_quickstart_guide() -> str

Return the quick start guide content.

Returns:

Type	Description
`str`	Quick start guide markdown.

Builders¶

pywry.mcp.builders.build_toolbar_item ¶

build_toolbar_item(cfg: dict[str, Any]) -> Any | None

Build a single toolbar item from config dict.

Parameters:

Name	Type	Description	Default
`cfg`	`dict[str, Any]`	Configuration dictionary with 'type' and component-specific options.	required

Returns:

Type	Description
`Any or None`	Toolbar component instance or None if type is unknown.

pywry.mcp.builders.build_toolbars ¶

build_toolbars(toolbars_data: list[dict[str, Any]]) -> list[Any]

Build Toolbar objects from config dicts.

Parameters:

Name	Type	Description	Default
`toolbars_data`	`list[dict[str, Any]]`	List of toolbar configurations with 'position' and 'items'.	required

Returns:

Type	Description
`list[Any]`	Built toolbar instances.

Handler Context¶

pywry.mcp.handlers.HandlerContext ¶

HandlerContext(args: dict[str, Any], events: EventsDict, make_callback: MakeCallback, headless: bool)

Context object containing shared state for handlers.

pywry.mcp.state.get_app ¶

get_app() -> PyWry

Get or create the global PyWry app instance.

Adapts to the rendering environment: - Desktop (PYWRY_HEADLESS=0 or unset): Native windows via WindowMode.NEW_WINDOW - Headless (PYWRY_HEADLESS=1): Inline widgets via WindowMode.BROWSER

Returns:

Type	Description
`PyWry`	The global PyWry application instance.

pywry.mcp.state.register_widget ¶

register_widget(widget_id: str, widget: Any) -> None

Register a widget.

Parameters:

Name	Type	Description	Default
`widget_id`	`str`	Unique identifier for the widget.	required
`widget`	`Any`	The widget instance.	required

pywry.mcp.state.store_widget_config ¶

store_widget_config(widget_id: str, config: dict[str, Any]) -> None

Store widget configuration for export.

Parameters:

Name	Type	Description	Default
`widget_id`	`str`	The widget identifier.	required
`config`	`dict[str, Any]`	The widget configuration.	required

pywry.mcp.state.get_widgets ¶

get_widgets() -> dict[str, Any]

Get all widgets.

Returns:

Type	Description
`dict[str, Any]`	Dictionary of widget IDs to widget instances.

pywry.mcp.state.get_widget ¶

get_widget(widget_id: str) -> Any | None

Get a widget by ID.

Parameters:

Name	Type	Description	Default
`widget_id`	`str`	The widget identifier.	required

Returns:

Type	Description
`Any or None`	The widget instance or None if not found.

pywry.mcp.state.get_widget_config ¶

get_widget_config(widget_id: str) -> dict[str, Any] | None

Get widget configuration by ID.

Parameters:

Name	Type	Description	Default
`widget_id`	`str`	The widget identifier.	required

Returns:

Type	Description
`dict or None`	The widget configuration or None if not found.

pywry.mcp.state.list_widget_ids ¶

list_widget_ids() -> list[str]

List all active widget IDs.

Returns:

Type	Description
`list of str`	List of widget identifiers.

pywry.mcp.state.remove_widget ¶

remove_widget(widget_id: str) -> bool

Remove a widget.

Parameters:

Name	Type	Description	Default
`widget_id`	`str`	The widget identifier.	required

Returns:

Type	Description
`bool`	True if widget was removed, False if not found.

pywry.mcp¶

Server¶

pywry.mcp.create_server ¶

pywry.mcp.run_server ¶

Tool Definitions¶

pywry.mcp.tools.get_tools ¶

Agentic Tools¶

pywry.mcp.agentic.plan_widget async ¶

pywry.mcp.agentic.build_app async ¶

pywry.mcp.agentic.export_project async ¶

pywry.mcp.agentic.scaffold_app async ¶

Prompts¶

pywry.mcp.prompts.get_prompts ¶

pywry.mcp.prompts.get_prompt_content ¶

Resources¶

pywry.mcp.resources.get_resources ¶

pywry.mcp.resources.get_resource_templates ¶

pywry.mcp.resources.read_resource ¶

pywry.mcp.resources.get_component_source ¶

pywry.mcp.resources.export_widget_code ¶

pywry.mcp.resources.read_component_doc ¶

pywry.mcp.resources.read_source_code ¶

pywry.mcp.resources.read_events_doc ¶

pywry.mcp.resources.read_skill_doc ¶

pywry.mcp.resources.read_quickstart_guide ¶

Builders¶

pywry.mcp.builders.build_toolbar_item ¶

pywry.mcp.builders.build_toolbars ¶

Handler Context¶

pywry.mcp.handlers.HandlerContext ¶

MCP Widget State¶

pywry.mcp.state.get_app ¶

pywry.mcp.state.register_widget ¶

pywry.mcp.state.store_widget_config ¶

pywry.mcp.state.get_widgets ¶

pywry.mcp.state.get_widget ¶

pywry.mcp.state.get_widget_config ¶

pywry.mcp.state.list_widget_ids ¶

pywry.mcp.state.remove_widget ¶

pywry.mcp.agentic.plan_widget `async` ¶

pywry.mcp.agentic.build_app `async` ¶

pywry.mcp.agentic.export_project `async` ¶

pywry.mcp.agentic.scaffold_app `async` ¶