MCP Chatkit Widget

ChatKit小工具MCP服务器

   ](https://www.python.org/downloads/)

一种模型上下文协议（MCP）服务器 自动地 将ChatKit Studio小部件定义转换为可调用的MCP工具，使AI代理能够动态生成丰富的交互式UI组件，这些组件可以在ChatKit UI中呈现。

目的

mcp-chatkit-widget 弥合了静态UI组件定义和AI代理运行时工具调用之间的差距。它会自动转换 ChatKit工作室 .widget 代理可以调用MCP工具中的文件来生成交互式小部件。

主要特点

• 自动生成刀具：转换每个 .widget 将文件导入具有类型安全输入验证的MCP工具
• 动态模式转换：将JSON模式定义转换为Pydantic模型以进行运行时验证
• 模板渲染：使用Jinja2呈现具有验证数据的小部件模板
• 丰富的小部件库：包括ChatKit Studio图库中的16个预构建小部件（航班跟踪器、天气、电子邮件编辑器等），可通过自定义小部件进行扩展
• 类型安全：使用Pydantic v2进行完整类型注释和验证
• 精心策划的探索护栏：需要传递一个显式 widgets_dir 所以只有

发现并注册精心策划的定义，防止意外加载 从任意路径

运作原理

1. 小部件发现：需要CLI --widgets-dir 论点指向策划

目录；如果参数丢失或无效，加载会很快失败。

1. 架构解析：从小部件定义中提取JSON模式和Jinja2模板
2. 模型生成：创建用于输入验证的动态Pydantic模型
3. 工具注册：在FastMCP服务器上注册MCP工具
4. 运行时执行：验证输入、呈现模板并返回ChatKit小部件组件

安装

来自PyPI

uv add mcp-chatkit-widget

来源（发展）

# Clone the repository
git clone https://github.com/ShaojieJiang/mcp-chatkit-widget.git
cd mcp-chatkit-widget

# Install with uv (recommended)
uv sync --all-groups

# Or with pip
pip install -e ".[dev,docs]"

需求

• Python 3.12或更高版本
• FastMCP >= 2.13.0.2
• OpenAI聊天套件 >= 1.1.0

用法

运行MCP服务器

使用所需的启动服务器 --widgets-dir 指向你策划的论点 小部件目录：

uv run mcp-chatkit-widget --widgets-dir /path/to/widgets

指向 examples/widgets 公开内置定义或提供自己的定义 策划 .widget 目录。

与MCP客户端集成

克劳德桌面版

将服务器添加到Claude Desktop配置中(claude_desktop_config.json):

{
  "mcpServers": {
    "chatkit-widget": {
      "command": "/path/to/uvx",
      "args": [
        "--from",
        "mcp-chatkit-widget@latest",
        "mcp-chatkit-widget",
        "--widgets-dir",
        "/path/to/widgets"
      ]
    }
  }
}

LangGraph代理

from langgraph.prebuilt import create_react_agent
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to the MCP server
server_params = StdioServerParameters(
    command="mcp-chatkit-widget",
    args=[]
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize session
        await session.initialize()

        # List available tools
        tools_result = await session.list_tools()
        print(f"Available widgets: {[tool.name for tool in tools_result.tools]}")

        # Create agent with widget tools
        agent = create_react_agent(model, tools=tools_result.tools)

直接刀具调用

from pathlib import Path

from mcp_chatkit_widget.server import register_widget_tools, server

# Load the curated widgets directory so the FastMCP tool manager
# knows about the bundled widget tools before invocation.
widgets_dir = Path(__file__).resolve().parents[1] / "examples" / "widgets"
register_widget_tools(widgets_dir)

# Example: Generate a flight tracker widget
flight_widget = server.call_tool(
    "flight_tracker",
    arguments={
        "number": "PA 845",
        "date": "Fri, Apr 25",
        "progress": "60",
        "airline": {
            "name": "Pan American Airways",
            "logo": "/panam_logo.png"
        },
        "departure": {
            "airport": "SFO",
            "city": "San Francisco",
            "time": "10:30 AM"
        },
        "arrival": {
            "airport": "JFK",
            "city": "New York",
            "time": "7:45 PM"
        }
    }
)

# `result.content[0].text` is the JSON string of the ChatKit WidgetComponentBase instance
print(result.content[0].text)

重要助手

该包导出帮助程序，以便脚本、演示和测试可以重用它们 渲染管道，而无需运行完整的MCP服务器。

• load_widgets(widgets_dir: Path) 强制执行策划目录，加载 .widget

文件，并在路径丢失、无效或包含格式错误时引发 模板。

• render_widget_definition(widget_def, **kwargs) 根据以下内容验证输入

模式支持的Pydantic模型，呈现存储的模板，并返回 WidgetComponentBase 这反映了预览有效负载。

• generate_widget_tools(server, widget_defs) 在您的计算机上注册经过消毒的工具

类似于FastMCP的服务器，因此您可以在其他地方重用相同的帮助程序。

from pathlib import Path

from mcp_chatkit_widget import (
    generate_widget_tools,
    load_widgets,
    render_widget_definition,
)

widgets = load_widgets(Path("/path/to/widgets"))
widget = render_widget_definition(widgets[0], title="Hello")

# Optionally wire the helpers into your own FastMCP server.
generate_widget_tools(custom_server, widgets)

检查刀具输出

FastMCP返回小部件模板发出的JSON .build() 助手，因此响应已经与ChatKit模式匹配。脚本，例如 examples/run_widget/run_widget.py 展示如何打印JSON并通过 display_widget_payload。不需要手动实例化ChatKit类——助手总是通过以下方式重新呈现小部件 render_widget_definition，因此您看到的有效载荷是服务器将发送给代理的规范结构。

可用小部件

服务器包括16个预构建的小部件：

• 沟通：渠道消息、电子邮件草稿
• 旅行：航班跟踪器、乘坐状态
• 事件：创建事件、查看事件、事件会话
• 任务：创建任务，启用通知
• 娱乐：玩家卡，播放列表
• 天气：天气现状，天气预报
• 购物：购买完成、软件购买、购买项目

每个小部件都会自动成为名为的MCP工具 snake_case （例如，“飞行跟踪器”→ flight_tracker).

添加自定义小部件

1. 出口A .widget 文件来自 ChatKit工作室
2. 放置 .widget 将文件保存到您控制的策划目录中
3. 使用以下命令启动MCP服务器 --widgets-dir 指向该目录

加载器只检查通过传递的目录 --widgets-dir，所以全部 发现的小部件由您的部署工作流明确批准。使用 examples/widgets 当你想启动打包的 定义，或在自定义目录中交换以选择加入定制的小部件。

建筑

flowchart TD
    A["MCP Client
(Claude, LangGraph, Custom Agents)
(AI Agent)"]
    B["FastMCP Server
mcp-chatkit-widget"]
    B1["Widget Loader
Discovers *.widget files
Parses JSON definitions"]
    B2["Schema & Rendering
JSON Schema → Pydantic models
WidgetTemplate .build() → WidgetRoot"]
    B3["MCP Tools
Registers tools dynamically
flight_tracker, weather_current, etc."]
    C["ChatKit Widget
(JSON Structure)"]

    A -->|"MCP Protocol (JSON-RPC)"| B
    B --> B1 --> B2 --> B3 --> C

数据流

1. 初创公司：服务器发现所有 .widget 文件
2. 注册：每个小部件都成为具有经过验证的模式的MCP工具
3. 调用：带有参数的代理调用工具
4. 验证：Pydantic模型验证输入数据
5. 渲染：Jinja2模板呈现经过验证的数据
6. 施工: render_widget_definition 调用模板的 .build() 因此，渲染的JSON变为 WidgetRoot 与预览层次结构匹配
7. 返回：小部件实例已发送回代理

发展

运行测试

在合并之前，始终对项目管理环境进行梳理和测试：

# Run linting and type checking
uv run make lint

# Run all tests with coverage
uv run make test

您可以在实验时直接运行目标测试：

pytest tests/test_server.py
pytest -v tests/

代码质量

# Run linting and type checking
uv run make lint

# Auto-format code
uv run make format

# Type check only
uv run mypy mcp_chatkit_widget/

建筑文件

# Serve documentation locally
uv run make doc

# Documentation will be available at http://0.0.0.0:8080

项目布局

mcp-chatkit-widget/
├── mcp_chatkit_widget/
│   ├── __init__.py
│   ├── server.py            # FastMCP server entrypoint
│   ├── widget_loader.py     # Discovers .widget files
│   ├── schema_utils.py      # JSON Schema → Pydantic helpers
│   ├── pydantic_conversion.py  # Schema conversion helpers
│   ├── rendering.py         # Jinja rendering helpers
│   ├── tooling.py           # MCP tool registration utilities
│   ├── naming.py            # Widget ⇄ tool name helpers
│   └── py.typed
├── examples/
│   ├── run_widget/          # Sample rendering scripts
│   └── widgets/             # Packaged widget definitions
├── custom_widgets/          # Optional curated widget sources
├── docs/
│   ├── release-notes.md
│   └── plan.md
├── tests/
│   ├── test_server.py
│   ├── test_tooling.py
│   ├── test_rendering.py
│   ├── schema_utils/
│   ├── widget_loader/
│   └── widget_integration/
├── Makefile
├── mkdocs.yml
├── pyproject.toml
├── uv.lock
├── langgraph.json
├── LICENSE.txt
└── README.md

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 运行测试和梳理(make test && make lint)
4. 提交您的更改(git commit -m 'Add amazing feature')
5. 推到分支(git push origin feature/amazing-feature)
6. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 LICENSE.txt 文件以获取详细信息。

资源

• ChatKit工作室 -创建和导出小部件定义
• 模型上下文协议 -MCP规范
• FastMCP -高级MCP服务器框架
• OpenAI聊天工具包Python SDK -小部件组件库

支持

• 问题:
• 文档: docs/