User Intent MCP
一个支持多模态用户意图采集的 MCP（Model Context Protocol）服务器，让 AI Agent 能够向用户提问并获取回复。
功能特性
核心能力
- 双传输模式 - 支持 SSE（HTTP）和 STDIO 两种传输模式
- 多模态输入 - 接受文字和图片回复
- 消息隔离 - 每个用户只能看到自己的消息
- 队列管理 - 自动问题队列，支持 PENDING/COMPLETED/DISMISSED 状态
认证与多租户
- 飞书 OAuth - 企业级认证，支持飞书（Lark）OAuth 2.0
- 30天会话缓存 - 长期登录会话，提升用户体验
- 多租户支持 - 用户级和企业级隔离
- 管理后台 - 系统初始化和用户管理
通知系统
- 飞书通知 - 新消息推送通知
- WebSocket 监听器 - 通过飞书 WebSocket API 实时接收消息
- 声音提醒 - 新问题的音频通知
- 可配置提醒 - 用户可自主启用/禁用通知
现代化前端
- React 19 + TypeScript - 类型安全的现代 React 开发
- Redux Toolkit - 高效的状态管理
- 响应式设计 - 基于 Tailwind CSS 的移动友好界面
- 侧边栏导航 - 直观的任务历史浏览
- 快捷键支持 - 快速操作支持
- 国际化支持 - 多语言支持（中英文）
架构
后端技术栈
- FastAPI - 现代化 Python Web 框架
- FastMCP - MCP 协议实现
- SQLite - 轻量级嵌入式数据库
- Uvicorn - ASGI 服务器
- lark-oapi - 飞书/Lark SDK
前端技术栈
- React 19 - 最新 React，支持并发特性
- Redux Toolkit - 可预测的状态管理
- React Router v7 - 声明式路由
- Tailwind CSS v4 - 原子化 CSS 框架
- Vite - 下一代前端构建工具
- Vitest - 单元测试框架
- i18next - 国际化框架
项目结构
interactive-mcp/
├── src/ # 后端源代码
│ ├── core.py # MCP 服务器核心与配置
│ ├── server.py # 统一入口（SSE/STDIO）
│ ├── web_multi_tenant.py # FastAPI 多租户应用
│ ├── auth.py # 管理员认证
│ ├── users.py # 用户管理
│ ├── oauth.py # 飞书 OAuth
│ ├── feishu.py # 飞书通知服务
│ ├── feishu_ws_listener.py # WebSocket 消息监听器
│ └── static/ # 静态资源（Service Worker）
├── frontend/ # React 前端
│ ├── src/
│ │ ├── features/ # 功能模块
│ │ │ ├── auth/ # 认证（登录/重定向）
│ │ │ ├── admin/ # 管理后台
│ │ │ ├── tasks/ # 任务/问题管理
│ │ │ └── user/ # 用户资料
│ │ ├── components/ui/ # 可复用 UI 组件
│ │ ├── store/ # Redux Store
│ │ ├── services/ # API 服务
│ │ ├── hooks/ # 自定义 Hooks
│ │ └── i18n/ # 国际化
│ └── package.json
├── docs/ # 文档
├── data/ # SQLite 数据库（运行时创建）
└── pyproject.toml # Python 包配置快速开始
环境要求
- Python 3.10 或更高版本
- Node.js 18 或更高版本（前端开发需要）
安装依赖
# 安装后端依赖
pip install -e .
# 安装飞书 SDK（可选，用于通知功能）
pip install lark_oapi
# 安装前端依赖（可选，用于开发）
cd frontend && npm install启动服务
生产模式（使用预构建前端）： ```bash
启动服务器，包含 MCP SSE 端点和内置前端
python -m uvicorn src.web_multi_tenant:app --host 0.0.0.0 --port 8000 ```
开发模式： ```bash
终端 1：后端服务（SSE 传输模式）
cd src && PYTHONPATH=. uvicorn web_multi_tenant:app --host 0.0.0.0 --port 8000
终端 2：前端开发服务器
cd frontend && npm run dev
访问 http://localhost:5173
**STDIO 模式（用于 MCP 客户端）：**MCP 前台运行，Web 服务器后台运行
python -m src.server --mode stdio ```
首次使用
- 访问
http://localhost:8000 - 按照初始化向导操作：
- 设置管理员账号密码
- 配置飞书应用（可稍后配置）
- 通过飞书 OAuth 登录
- 在用户中心获取 API Key
MCP 客户端配置
获取 API Key
- 访问
http://localhost:8000 - 点击「使用飞书登录」
- 授权后在用户中心复制 API Key（格式：
uk_xxxxxxxx）
STDIO 模式
{
"mcpServers": {
"user-intent": {
"command": "uv",
"args": ["run", "python", "/path/to/src/server.py", "--mode", "stdio"],
"env": {
"USERINTENT_API_KEY": "uk_your_api_key"
}
}
}
}SSE 模式
{
"mcpServers": {
"user-intent": {
"transport": "sse",
"url": "http://localhost:8000/mcp/sse",
"headers": {
"Authorization": "Bearer uk_your_api_key"
}
}
}
}环境变量
| 变量 | 说明 | 默认值 | |:---|:---|:---| | USERINTENT_API_KEY | 用户 API Key（用于认证） | - | | USERINTENT_DB_PATH | SQLite 数据库路径 | data/intent.db | | USERINTENT_WEB_PORT | Web 服务器端口 | 8000 | | USERINTENT_WEB_HOST | Web 服务器主机 | 0.0.0.0 | | USERINTENT_TIMEOUT | 请求超时时间（秒） | 3000 |
管理后台
访问 http://localhost:8000/admin 进入系统管理：
| 功能 | 说明 | |:---|:---| | 系统概览 | 查看用户数量和请求统计 | | 用户管理 | 查看/禁用/启用已注册用户 | | 飞书配置 | 配置飞书应用凭据 | | 系统设置 | 修改管理员密码 | | WebSocket 状态 | 监控/重启飞书 WebSocket 监听器 |
飞书应用配置
创建飞书应用
- 在飞书开放平台创建应用
- 配置 OAuth 回调地址：
https://your-domain.com/auth/feishu/callback - 开通权限：
contact:user.base:readonly- 获取用户基本信息im:message:send_as_bot- 发送消息
- 配置事件订阅：
- 使用 WebSocket 长连接
- 订阅
im.message.receive_v1事件
环境配置
通过管理后台：
- 登录管理后台
- 进入「飞书配置」页面
- 输入
app_id、app_secret和redirect_uri - 保存（WebSocket 监听器将自动重启）
通过数据库： ``sql INSERT INTO admin_config (key, value) VALUES ('feishu_app_id', 'cli_xxxxxxxxx'), ('feishu_app_secret', 'your_secret'), ('feishu_redirect_uri', 'http://localhost:8000/auth/feishu/callback'); ``
前端开发
技术栈详情
- React 19 支持并发特性
- TypeScript 类型安全
- Redux Toolkit 状态管理
- React Router v7 路由管理
- Tailwind CSS v4 及
@tailwindcss/typography - i18next + react-i18next 国际化
- Vite 快速 HMR
- Vitest 单元测试
开发命令
cd frontend
# 启动开发服务器
npm run dev
# 构建生产版本
npm run build
# 运行测试
npm run test
# 运行测试（含覆盖率）
npm run test:coverage
# 代码检查
npm run lint功能模块
- auth/ - 登录页面、OAuth 重定向处理
- admin/ - 管理员登录、仪表板、系统初始化
- tasks/ - 问题/回复管理、历史记录、侧边栏
- user/ - 用户资料、API Key 管理
生产部署
使用 systemd（Linux）
创建 /etc/systemd/system/user-intent-mcp.service：
[Unit]
Description=User Intent MCP Server
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/user-intent-mcp
Environment="PYTHONPATH=/opt/user-intent-mcp/src"
ExecStart=/usr/bin/python3 -m uvicorn web_multi_tenant:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target启用并启动： ``bash sudo systemctl enable user-intent-mcp sudo systemctl start user-intent-mcp ``
使用 Docker
FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -e . && pip install lark_oapi
# 构建前端（可选，也可使用预构建镜像）
# RUN cd frontend && npm install && npm run build
ENV PYTHONPATH=/app/src
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "web_multi_tenant:app", "--host", "0.0.0.0", "--port", "8000"]构建并运行： ``bash docker build -t user-intent-mcp . docker run -d -p 8000:8000 -v $(pwd)/data:/app/data user-intent-mcp ``
Nginx 反向代理
server {
listen 80;
server_name intent.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# SSE 和 WebSocket 支持
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# SSE 超时设置
proxy_buffering off;
proxy_read_timeout 86400;
}
}测试
# 后端单元测试
PYTHONPATH=src pytest tests/test_multi_tenant.py -v
# 后端集成测试
PYTHONPATH=src pytest tests/test_integration.py -v
# 前端测试
cd frontend && npm run test文档
版本历史
v1.0.0（当前版本）
- 完整的 React + Redux 前端重构
- 飞书 WebSocket 监听器，实时接收消息
- 通知声音提醒
- 侧边栏导航与任务历史
- 图片上传支持
- 快捷键支持
- 多语言支持（i18n）
- 30天会话缓存
- 生产部署支持
v0.1.0
- SQLite 多用户支持
- 飞书 OAuth 集成
- 基础消息队列
- SSE 和 STDIO 传输模式
- 管理后台
许可证
MIT License
贡献
欢迎贡献！请随时提交 Pull Request。
---
