MCP-进行中
项目介绍
<p align="center">
<img src="https://gips0.baidu.com/it/u=1492093644,99220372&fm=3081&app=3081&f=PNG?w=1044&h=1058" width=300>
</p>
🎯 什么是
1. MCPWIPServer模块 (
2. MCPWIPClient模块 (
3. RAG模块 (
MCP-WIP: MCP Widget Integration Protocol
mcp-wip旨在革新强大的AI引擎与实际UI组件之间的连接。通过mcp-wip，您的大模型可以直接选择由MCP服务器提供的清晰声明性清单指定的组件。组件实现保持技术无关性，使前端能够通过简单的自定义桥梁轻松集成任何框架。该协议设计为MCP标准的扩展，允许无缝集成到您自己的MCP服务器中。
<p align="center"> <video src="https://github.com/user-attachments/assets/10d421f9-b6c2-4791-978c-68ac9aafef72"></video> </p>这是一个早期开发阶段的实验项目。请将其视为Alpha版。欢迎对该项目的所有贡献！
🎯 什么是mcp-wip？
MCP-WIP提供了一种统一的方法，让大模型根据用户请求智能地选择和实例化UI组件。系统使用**检索增强生成(RAG)**将用户意图与适当的组件（由标准声明性清单描述）匹配，从而在对话式AI和交互式UI组件之间提供无缝集成。
主要特性
- 智能组件选择：大模型自动选择最相关的组件基于用户意图
- 组件上下文注入：MCP-WIP客户端支持从组件直接检索并注入额外的上下文，允许大模型精确重建先前实例化的组件状态和用户交互。
- RAG增强搜索：可选且高度可定制的RAG支持，用于高效地从大型目录中检索组件
- 模块化架构：MCP客户端、MCP服务器和组件之间的干净分离
- 工具集成：与服务器端工具的无缝集成以及自动工具调用解析（代理AI）
- 会话管理：多轮对话的可定制内存支持和上下文处理
- FastAPI集成：使用FastAPI的RESTful API，易于集成
🏗️ 架构
该项目遵循模块化架构，主要分为三个组件：
┌─────────────────────────────────────────────────────────────┐
│ 前端（技术无关性） |
│ 组件渲染器及UI │
└──────────────────────────┬──────────────────────────────────┘
│ HTTP REST API
┌──────────────────────────▼──────────────────────────────────┐
│ MCPWIPClient │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ • 聊天编排 │ │
│ │ • 基于RAG的组件检索 │ │
│ │ • 大模型集成（兼容OpenAI） │ │
│ │ • 会话内存管理 │ │
│ │ • 工具调用（代理行为） │ │
│ └────────────────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────┘
│ Stdio传输（或可流式传输HTTP）
┌──────────────────────────▼──────────────────────────────────┐
│ MCPWIPServer (FastMCP) │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ • 自定义工具 │ │
│ │ • 资源模板 │ │
│ │ • 作为资源的组件清单 │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
组件职责
MCPWIPClient
- 协调与大模型的聊天互动
- 通过RAG或完全公开MCP wip资源目录来管理组件选择
- 处理向MCP服务器调用工具，启用完整的代理功能
- 处理MCP服务器上的模板资源请求
- 维护会话上下文和记忆
- 提供前端集成的REST API端点
MCPWIPServer
- 加载并提供组件清单作为MCP资源
- 暴露用于数据检索和操作的自定义工具
- 管理动态数据获取的资源模板
- 作为可用组件的单一真实来源
组件系统
- 每个组件由一个JSON清单定义
- 清单描述能力、参数和使用场景
- 组件在前端动态渲染
- 大模型根据用户请求或意图选择合适的组件
前端桥接SDK
- 最受欢迎的前端框架SDK
- 抽象UI组件定义，具有预定义的功能以检索/注入组件上下文
- 将大模型选择的组件资源URI映射到实际的技术特定UI组件（例如React组件）
- React SDK已可用（参见
sdks/react）
📦 安装
先决条件
- Python >= 3.12
uv包管理器- Node.js >= 18（用于React前端，可选）
设置
-
克隆仓库
git clone <仓库地址> cd mcp-wip -
安装Python依赖项
# 使用uv uv sync # 使用fastapi路由 uv sync --extra fastapi # 使用memvid rag uv sync --extra rag # 直接同步所有依赖项 uv sync --all-extras -
安装React SDK依赖项（用于前端）
cd sdks/react npm install
🚀 快速开始
运行示例
系统采用模块化方法，客户端通过StdioTransport运行服务器作为子进程：
uv run -m example.main
此单一命令：
- 使用
example/resources/widgets/中的组件初始化MCPWIPServer - 在9000端口启动MCPWIPClient，使用FastAPI
- 设置带有预计算Memvid索引的RAG
- 在
http://localhost:9000/wip/暴露REST API端点
可用端点
GET /wip/start-session- 开始新的聊天会话POST /wip/chat- 发送消息并获取AI响应及组件选择POST /wip/context-injection- 注入组件上下文到对话GET /wip/manifest- 获取所有可用组件清单POST /wip/call-tool/{tool_name}- 调用特定服务器工具
React演示前端
您可以启动示例前端：
cd example/chat
npm run dev
React演示前端旨在成为增强型聊天界面的试点，设计超越了标准的对话UI。它展示了动态组件初始化和交互——让您看到如何在聊天会话期间加载、渲染和控制组件。该界面处理将组件上下文注入回MCP-WIP后端，使大模型能够访问用户在组件中所做的操作信息。
本项目的中心思想是将传统的UI（由可重用组件如表单、选择器或卡片构建）与自然对话交互相结合，实现“对话式组件”。这种混合方法为最终用户提供灵活性，可以与基于表单的工具和自然语言代理进行交互，实现无缝、强大的协作工作流程。
🔧 模块指南
1. MCPWIPServer模块 (core/mcp_server/)
服务器模块负责组件注册和自定义工具。
组件声明性清单
您可以像这样定义新组件：
new_widget = WidgetManifest(
uri="wip://image-carousel",
input_parameters_schema={
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {"type": "string"},
"description": "每个图像URL对应的唯一标识符列表。",
},
},
"required": ["ids"],
"additionalProperties": False,
"description": "渲染图像轮播所需的参数，将ID与图像URL及其可选字幕关联。",
},
capabilities=["全屏", "菜单"],
description="""此组件帮助用户以交互式轮播的形式查看多个产品图像，
提供增强的用户界面以详细探索项目。通过允许用户轻松浏览不同产品的视图或变体，
改善了体验。图像轮播特别适用于展示项目各种选项的画廊，
或在目录或作品集中从多个角度展示产品布局。""",
use_cases_hints="当用户请求查看产品或一组产品的详细信息时应选择此组件。",
version="1.0.0",
name="图像轮播",
)
MCP-WIP清单URI必须采用"wip://...."格式才能正确检索
基本服务器设置
from fastmcp import FastMCP
from core.mcp_server.server import MCPWIPServer
# 创建FastMCP服务器
server = FastMCP("mcp-wip-server")
"""
在这里您可以添加工具、资源和提示，就像在FastMCP中一样
通过@tool、@prompt和@resource装饰器
更多信息，请参阅FastMCP文档或example/server.py
"""
# 使用保存在widget目录中的JSON清单初始化MCPWIPServer
mcp_server = MCPWIPServer(
input_dir="example/resources/widgets",
server=server,
load_from_directory=True
)
# 可选地以这种方式添加更多清单
mcp_server.add_manifest_json_resource(new_widget) # 来自前面示例的新组件
if __name__=="__main__":
# 作为进程运行（用于StdioTransport）
mcp_server.run_as_process()
2. MCPWIPClient模块 (core/mcp_client/)
客户端协调大模型交互和组件选择。
客户端初始化
from fastmcp.client import StdioTransport
from openai import AsyncOpenAI
from core.mcp_client.client import MCPWIPClient
# 设置传输以与自定义服务器通信
# example.server 应替换为您自己的MCPWIPServer的Python文件
transport = StdioTransport(
"uv",
args=["run", "-m", "example.server", "--transport", "stdio"]
)
# 初始化大模型客户端
llm_client = AsyncOpenAI(
api_key=os.getenv("GROQ_API_KEY"),
base_url="https://api.groq.com/openai/v1"
)
# 初始化MCPWIPClient
wip_client = MCPWIPClient(
llm_client=llm_client,
mcp_server_transport=transport,
system_prompt=SYSTEM_PROMPT, # 如果需要自定义系统提示（推荐）
rag=rag, # 可选：BaseRAG实例，您可以使用预定义的或自己的
model="openai/gpt-oss-20b"
)
运行一轮聊天
# 运行一轮聊天
messages = await wip_client.run_chat_turn(
user_message="显示我10月的日历",
session_id="session-123"
)
# 响应包括ToolMessage和AssistantMessage
# AssistantMessage是一个JSON格式化的字符串，如下结构
run_chat_turn的响应将包含一个JSON格式化的字符串形式的AssistantMessage，其字段如下：
{
"uri": "wip://使用的组件",
"parameters": [
{"name": "参数1", "value": "某个值"}
],
"text": "自由文本回复"
}
- 如果不需要组件，
uri将是""，parameters将是[]，text将包含AI的回答。
所有响应严格遵循此JSON结构，输出为字符串。
3. RAG模块 (rag/)
RAG模块提供了智能组件检索。 您可以继承抽象的BaseRAG类以集成您偏好的RAG解决方案。在项目中，借助memvid库实现了简单的内存解决方案，无需额外的矢量数据库。
有关使用示例，请参阅example/main.py。
无RAG
如果没有提供RAG，所有组件都会在每次轮次中暴露给大模型。对于小型组件目录（< 20个组件），这效果很好。
4. 组件清单
组件定义为具有以下结构的JSON清单：
{
"uri": "wip://组件名称",
"input_parameters_schema": {
"type": "object",
"properties": {
"param1": {"type": "string"}
}
},
"capabilities": ["显示", "交互"],
"name": "组件名称",
"description": "组件功能的详细描述",
"use_cases_hints": "何时使用此组件",
"version": "1.0.0"
}
5. 组件前端集成
在您的组件清单已在MCP-WIP服务器上注册后，可以在您喜欢的前端框架中实现实际的组件逻辑，使用提供的SDK（目前唯一可用的是React，但将添加更多）。
React桥接SDK
组件结构：
import type { WidgetProps, WidgetComponent } from '@mcp-wip/react-widget-sdk';
const MyWidget: WidgetComponent = ({ parameters }) => {
return <div>组件内容</div>;
};
// 必需元数据
MyWidget.widgetName = "我的组件";
MyWidget.description = "组件描述";
MyWidget.visualization = "both"; // "small" | "both" | "独立"
MyWidget.getIcon = () => <span>🎯</span>;
// 可选生命周期方法
MyWidget.initWidget = (parameters, setParams) => { /* 异步设置 */ };
MyWidget.getWidgetContext = () => { /* 返回当前状态 */ };
MyWidget.setWidgetContext = (prevParams) => { /* 处理上下文更新 */ };
注册组件：
import { registerWidgets } from '@mcp-wip/react-widget-sdk';
registerWidgets({
'wip://my-widget': MyWidget,
'wip://image-carousel': ImageCarouselWidget,
});
渲染组件：
import { WidgetRenderer } from '@mcp-wip/react-widget-sdk';
<WidgetRenderer
uri="wip://image-carousel"
parameters={[{ name: "ids", value: ["sku123"] }]}
/>
🔄 完整工作流程示例
场景：用户请求库存检查
- 用户发送消息："检查SKU-123的库存"
- 客户端接收请求 通过
POST /wip/chat - RAG搜索 最相关的k个组件
- 大模型处理 用户意图、来自先前请求的附加上下文和检索到的组件清单
- 大模型决定 应实例化"wip://stock-inspector"，并尝试从清单中获取所需参数
{
"uri": "wip://stock-level-inspector",
"parameters": [{"name": "sku", "value": "SKU-123"}],
"text": ""
}
- 前端将组件URI映射到
StockVisualizer组件，并实例化它 - 组件直接使用MCPWIP服务器上的
get_stock工具获取SKU "SKU-123"的库存可用性（由MCPWIPClient处理） StockVisualizer在下一次用户请求之前将其上下文传递回MCPWIPClient会话
📚 项目结构
mcp-wip/
├── core/
│ ├── mcp_client/ # 客户端编排逻辑
│ │ ├── client.py # 主MCPWIPClient类
│ │ ├── memory_handler.py # 会话内存管理
│ │ └── models.py # Pydantic模型
│ └── mcp_server/ # 服务器逻辑
│ ├── server.py # 主MCPWIPServer类
│ └── models.py # 组件清单模型
├── api/
│ ├── routes.py # FastAPI路由
│ └── models.py # API请求/响应模型
├── rag/
│ ├── base.py # 基础RAG接口
│ └── memvid_rag.py # Memvid实现
├── example/
│ ├── main.py # 主入口点
│ ├── server.py # 服务器配置
│ ├── resources/ # 组件清单和RAG数据
│ └── chat/ # React前端
├── sdks/
│ └── react/ # React组件SDK
└── utils/
└── widget_json_converter.py
🛣️ 路线图
- 协议定义
- React SDK
- 其他前端桥接SDK（Flatter等）
- 在桥接接口上管理身份验证数据
- 组件清单版本管理支持
- 组件内的上下文注入
- 前端桥接附加功能（通知系统、遥测）
- TypeScript MCPWIPClient
- 其他大模型提供商支持
欢迎任何形式的帮助！
🙏 致谢
有关详细的API文档，请参阅每个模块中的内联文档字符串。