MCP Server Interactive

MCP交互服务器

A. MCP（模型上下文协议）服务器 用Python编写，直接在AI聊天主机内呈现交互式UI面板，例如 VS代码GitHub副本聊天 和 克劳德桌面.

交互式HTML应用程序通过沙盒iframe嵌入聊天中，并由服务器的业务逻辑使用 MCP应用程序 协议。

______________________________________________________________________

特性

______________________________________________________________________

项目结构

mcp-server-interactive/
├── server/                 # Python MCP server
│   ├── app/
│   │   ├── main.py         # FastMCP + FastAPI entry point
│   │   ├── core/           # Config, logging, constants
│   │   ├── domain/         # Models + state machines
│   │   ├── schemas/        # Pydantic request / response schemas
│   │   ├── services/       # Business logic
│   │   ├── tools/          # MCP tool definitions
│   │   ├── resources/      # MCP resource handlers (serve HTML)
│   │   ├── agents/         # Pluggable AI agent registry
│   │   └── utils/          # Helpers
│   ├── tests/
│   └── pyproject.toml
├── ui/                     # TypeScript / Vite frontend apps
│   ├── src/
│   │   ├── mcp-app.ts      # Wrapper around @modelcontextprotocol/ext-apps
│   │   ├── poll-app.ts
│   │   ├── quiz-app.ts
│   │   ├── board-app.ts
│   │   ├── monitor-app.ts
│   │   └── timer-app.ts
│   ├── templates/          # HTML entry points
│   │   ├── poll-app.html
│   │   ├── quiz-app.html
│   │   ├── board-app.html
│   │   ├── monitor-app.html
│   │   └── timer-app.html
│   ├── inline-assets.mjs   # Post-build asset inlining script
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
├── .env
└── README.md

______________________________________________________________________

快速开始

先决条件

• Python>=3.11
• 紫外线 --Python包管理器
• Node.js>=18

1.配置环境

cp .env.example .env   # edit values as needed

2.安装Python依赖项

cd server
uv sync

3.构建用户界面

cd ui
npm install
npm run build

构建步骤编译TypeScript，然后运行 inline-assets.mjs 在中生成自包含的HTML文件 ui/dist/templates/.

4.运行服务器

cd server
uv run serve

如果Windows智能应用程序控制（或应用程序控制策略）阻止生成的脚本启动器，请使用以下等效命令：

cd server
uv run python -m app.main

服务器启动于 http://localhost:3001.

• 健康检查： http://localhost:3001/health
• Swagger文档： http://localhost:3001/docs

5.连接您的MCP客户端

将以下内容添加到MCP客户端配置中（例如。 mcp.json):

{
  "servers": {
    "interactive": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

然后提示LLM：

• *“显示投票”*
• *“打开测验”*
• *“显示我的任务板”*
• *“打开系统监视器”*
• *“显示我的计时器”*

______________________________________________________________________

发展

测试

cd server
uv run pytest -v

棉绒和格式

cd server
uv run ruff check .
uv run ruff format .

类型检查

cd server
uv run mypy app/

UI开发服务器（热重新加载）

cd ui
npm run dev

______________________________________________________________________

运作原理

1. LLM调用MCP工具（例如。 show_poll).
2. 工具结果包含 _meta.ui.resourceUri 指向 ui://poll-app/panel.html.
3. 主机获取资源（使用MIME类型提供 text/html;profile=mcp-app)并将其呈现在聊天中的沙盒iframe中。
4. 服务器通过以下方式将初始数据推送到iframe ontoolresult.
5. 用户交互呼叫 app.callServerTool()，主机将其中继回服务器。
6. 服务器返回更新的数据，UI重新渲染到位。

______________________________________________________________________

建筑

┌─────────────────────────┐         ┌─────────────────────────────┐
│   Python MCP Server     │         │   TypeScript UI App         │
│   port 3001             │         │   (sandboxed iframe)        │
│                         │         │                             │
│  FastMCP tools          │◄────────│  mcp-app.ts (SDK wrapper)   │
│  MCP resources          │  relay  │  app.callServerTool()       │
│  Services / Domain      │ via host│  app.ontoolresult           │
└─────────────────────────┘         └─────────────────────────────┘
        Streamable HTTP                    postMessage (JSON-RPC)
        MCP spec 2025-03-26

______________________________________________________________________

环境变量

______________________________________________________________________

路线图

• \[\]Redis会话存储
• \[\]Docker构建（服务器+UI在一个容器中）
• \[\]结构化日志记录（structlog）
• \[\]mypy严格+全类型覆盖
• \[\]CI/CD管道
• \[\]AI代理集成（LLM驱动的问答主机、民意调查分析）