ChatKit小工具MCP服务器
一种模型上下文协议（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所以只有
发现并注册精心策划的定义，防止意外加载 从任意路径
运作原理
- 小部件发现：需要CLI
--widgets-dir论点指向策划
目录；如果参数丢失或无效，加载会很快失败。
- 架构解析：从小部件定义中提取JSON模式和Jinja2模板
- 模型生成：创建用于输入验证的动态Pydantic模型
- 工具注册：在FastMCP服务器上注册MCP工具
- 运行时执行：验证输入、呈现模板并返回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).
添加自定义小部件
- 出口A
.widget文件来自 ChatKit工作室 - 放置
.widget将文件保存到您控制的策划目录中 - 使用以下命令启动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数据流
- 初创公司：服务器发现所有
.widget文件 - 注册：每个小部件都成为具有经过验证的模式的MCP工具
- 调用：带有参数的代理调用工具
- 验证：Pydantic模型验证输入数据
- 渲染：Jinja2模板呈现经过验证的数据
- 施工:
render_widget_definition调用模板的.build()因此，渲染的JSON变为WidgetRoot与预览层次结构匹配 - 返回：小部件实例已发送回代理
发展
运行测试
在合并之前，始终对项目管理环境进行梳理和测试：
# 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贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 运行测试和梳理(
make test && make lint) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 LICENSE.txt 文件以获取详细信息。
资源
- ChatKit工作室 -创建和导出小部件定义
- 模型上下文协议 -MCP规范
- FastMCP -高级MCP服务器框架
- OpenAI聊天工具包Python SDK -小部件组件库
支持
- 问题:
- 文档: docs/