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

启动服务

生产模式（使用预构建前端）：

# 启动服务器，包含 MCP SSE 端点和内置前端
python -m uvicorn src.web_multi_tenant:app --host 0.0.0.0 --port 8000

开发模式：

# 终端 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

首次使用

1. 访问 http://localhost:8000
2. 按照初始化向导操作：
   • 设置管理员账号密码
   • 配置飞书应用（可稍后配置）
3. 通过飞书 OAuth 登录
4. 在用户中心获取 API Key

MCP 客户端配置

获取 API Key

1. 访问 http://localhost:8000
2. 点击「使用飞书登录」
3. 授权后在用户中心复制 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 监听器

飞书应用配置

创建飞书应用

1. 在飞书开放平台创建应用
2. 配置 OAuth 回调地址：https://your-domain.com/auth/feishu/callback
3. 开通权限：
   • contact:user.base:readonly - 获取用户基本信息
   • im:message:send_as_bot - 发送消息
4. 配置事件订阅：
   • 使用 WebSocket 长连接
   • 订阅 im.message.receive_v1 事件

环境配置

通过管理后台：

1. 登录管理后台
2. 进入「飞书配置」页面
3. 输入 app_id、app_secret 和 redirect_uri
4. 保存（WebSocket 监听器将自动重启）

通过数据库：

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

启用并启动：

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"]

构建并运行：

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

文档

• React+Redux 重构设计文档
• 开发计划
• 测试计划
• v0.1.0 设计文档
• v0.1.0 产品需求

版本历史

v1.0.0（当前版本）

• 完整的 React + Redux 前端重构
• 飞书 WebSocket 监听器，实时接收消息
• 通知声音提醒
• 侧边栏导航与任务历史
• 图片上传支持
• 快捷键支持
• 多语言支持（i18n）
• 30天会话缓存
• 生产部署支持

v0.1.0

• SQLite 多用户支持
• 飞书 OAuth 集成
• 基础消息队列
• SSE 和 STDIO 传输模式
• 管理后台

许可证

MIT License

贡献

欢迎贡献！请随时提交 Pull Request。

---

English Version