# Tencent Meeting MCP

把腾讯会议接入任意支持 MCP 的 AI 客户端——ChatGPT（网页版 / 桌面版）、Antigravity、Codex、Claude Code 等。

底层调用腾讯会议官方命令行工具 [`tmeet`](https://www.npmjs.com/package/@tencentcloud/tmeet)，本项目负责把它包装成一个标准的 **MCP 服务器**（Streamable HTTP / stdio 双传输），并补齐分页、时间定位、分享链接解析这些原接口不直接提供的能力。

> 非官方项目，与腾讯公司无隶属关系。使用时请遵守腾讯会议的用户协议与所在企业的数据合规要求。

---

## 为什么需要这一层

ChatGPT 的自定义连接器只接受**公网可达的远程 MCP**（SSE / Streamable HTTP），而腾讯会议对外提供的是**本地命令行工具 + 本地凭证**，两者无法直连。中间缺的这层适配，就是这个项目。

```
ChatGPT / Antigravity / Codex
        │  MCP (JSON-RPC)
        ▼
   本项目 server.py
        │  子进程调用
        ▼
   tmeet CLI  ──OAuth──▶  腾讯会议云端接口
```

鉴权完全复用 `tmeet` 自己的 OAuth 凭证（默认存在 `~/.tmeet`），本项目不接触、不存储你的账号密码或 Token。

## 功能

- **会议**：查待开 / 已结束、按关键词或会议号搜索、查详情、查参会人
- **录制**：录制列表、播放页地址、AI 智能纪要、逐字稿
- **逐字稿增强**：按段落索引自动跨页合并，支持 `start` / `end` 时间窗，直接问「39:40 之后说了什么」即可
- **分享链接**：把 `meeting.tencent.com/crm/...` 这类分享链接解析回会议，再取纪要或转写
- **写操作**：创建、修改、取消会议；带 `readOnlyHint` / `destructiveHint` 注解，客户端会强制二次确认
- **只读模式**：一条配置关掉全部写工具

## 快速开始

### 1. 前置

```bash
# Node.js 18+，然后安装腾讯会议 CLI
npm install -g @tencentcloud/tmeet@latest

# 登录（会打开浏览器授权）
tmeet auth login

# 确认已登录
tmeet auth status
```

### 2. 安装并启动

```bash
git clone https://github.com/<your-name>/tencent-meeting-mcp.git
cd tencent-meeting-mcp

python -m venv .venv
# Windows
.venv\Scripts\pip install -r requirements.txt
copy .env.example .env
# macOS / Linux
# .venv/bin/pip install -r requirements.txt && cp .env.example .env

# 启动（仅本地）
.venv/bin/python server.py
```

Windows 用户可以直接双击 `start.cmd`，它会启动服务并把地址打印出来。

### 3. 自检

```bash
.venv/bin/python smoke_test.py
# initialize ok → tools/list ok: 15 tools → tools/call ok
```

### 4. 让客户端连上

**本地客户端（Antigravity / Codex / Claude Code）** 直接连 `http://127.0.0.1:8787/mcp/<MCP_SECRET>`，不需要公网。

Antigravity（`~/.gemini/config/mcp_config.json`）：

```json
{
  "mcpServers": {
    "tencent-meeting": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py", "--stdio"]
    }
  }
}
```

Codex（`~/.codex/config.toml`）：

```toml
[mcp_servers.tencent-meeting]
url = "http://127.0.0.1:8787/mcp/<MCP_SECRET>"
```

**ChatGPT 网页版 / 桌面版** 需要公网 HTTPS。三种方式，按需选一种：

| 方式 | 地址是否固定 | 说明 |
|---|---|---|
| ngrok 免费固定域名 | 是 | 注册后在 `.env` 填 `NGROK_DOMAIN`，脚本自动拉隧道 |
| Cloudflare named tunnel | 是 | 需要自己的域名，`python setup_tunnel.py mcp.example.com` |
| Cloudflare 临时隧道 | 否 | 每次重启都变，只适合临时验证 |

配好后在 ChatGPT：插件 → `+` → 添加自定义 MCP 服务器 → 粘贴 `https://<your-domain>/mcp/<MCP_SECRET>` → 身份验证选**无身份验证**。

详细步骤、排错对照表见 [教程.md](教程.md)。

## 工具清单

| 工具 | 类型 | 说明 |
|---|---|---|
| `list_upcoming_meetings` | 只读 | 待开始 / 进行中的会议 |
| `list_ended_meetings` | 只读 | 已结束会议，可指定时间窗 |
| `search_meetings` | 只读 | 按关键词 / 会议号 / 时间搜索 |
| `get_meeting` | 只读 | 会议详情 |
| `get_meeting_participants` | 只读 | 实际参会人及进出时间 |
| `list_records` | 只读 | 录制列表 |
| `get_record_address` | 只读 | 播放页地址 |
| `resolve_recording_link` | 只读 | 解析分享链接为会议与录制 |
| `get_smart_minutes` | 只读 | AI 智能纪要 |
| `get_transcript` | 只读 | 逐字稿，支持 `start` / `end` 时间窗与续页 |
| `search_minutes` | 只读 | 跨会议搜纪要 |
| `get_minutes` | 只读 | 单场会议纪要 |
| `create_meeting` | 写 | 创建会议 |
| `update_meeting` | 写 | 修改时间 / 主题 / 受邀人 |
| `cancel_meeting` | 写 | 取消会议 |

`MCP_READ_ONLY=1` 时只注册前 12 个。

## 配置项

见 [.env.example](.env.example)，常用的几项：

| 变量 | 默认 | 作用 |
|---|---|---|
| `MCP_SECRET` | 空 | URL 路径密钥，强烈建议设置 |
| `MCP_READ_ONLY` | `0` | `1` = 只读模式 |
| `MCP_JSON_RESPONSE` | `1` | `0` 改为 SSE 响应，个别客户端扫描工具失败时切换 |
| `TMEET_BIN` | 自动探测 | `tmeet` 可执行文件路径 |
| `MCP_MAX_OUTPUT_CHARS` | `12000` | 单次返回上限，防止撑爆上下文 |

## 已知限制

- **看不到视频画面**。MCP 连接器目前不支持把工具返回的图片交给模型，本项目只提供纪要、逐字稿和播放链接。要做画面理解，需在服务端接视觉模型，转成文字再返回。
- **非参会者的分享链接**只能读到公开元数据（主题、时间、时长、播放页），转写和纪要受腾讯账号权限限制。
- **企业账号**可能无法申领官方 AI Skill Token，但本项目走的是 CLI OAuth，只要 `tmeet auth login` 成功即可使用；企业级管理视图（全员会议、企业录制库）不在能力范围内。
- 服务端必须在运行时才能响应，电脑关机则客户端报连接失败。

## 安全

- `MCP_SECRET` 是公网暴露时的唯一门禁，请用随机串（`python -c "import secrets;print(secrets.token_urlsafe(24))"`）。
- 先用 `MCP_READ_ONLY=1` 跑一段时间，确认模型不会误调写操作。
- 仓库不包含 `.env`、隧道地址、日志和任何会议数据，提交前请确认 `.gitignore` 生效。

## License

[MIT](LICENSE)