内容
# NovartcMcp
`NovartcMcp` 是 `NovaRTC` 项目的专用 MCP 服务器。
它把项目中的 HTTP 接口、环境诊断能力、MySQL UTC 检查能力，以及 WebSocket + protobuf 实时消息能力，统一暴露给 Codex 等支持 MCP 的客户端，让 AI 可以直接参与项目调试、联调和排障。
## Features
- HTTP API 工具化：登录、联系人、会话、历史消息、已读
- 环境诊断：检查 HTTP、IM、Redis、MongoDB、MySQL、RocketMQ 依赖状态
- 配置读取：直接解析 `application-dev.yml`
- MySQL UTC 校验：确保数据库连接和会话时区按 UTC 工作
- MongoDB 消息查询：按 `messageId` 查询标准化消息或原始文档
- 持久化尾查：查看最近写入的消息记录
- 实时消息桥接：通过 WebSocket `/ws` + protobuf 发送单聊 / 群聊文本消息
- 短时订阅：认证后限时监听实时消息
- Codex 集成：已支持通过 `~/.codex/config.toml` 注册为 MCP 服务器
## Use Cases
`NovartcMcp` 适合以下场景：
- 验证 `NovaRTC` 本地环境是否完整启动
- 让 Codex 直接登录系统并查询联系人、会话和历史消息
- 验证 `U1001 -> U1002` 的消息链路是否能实时发送并成功入库
- 检查 MySQL 是否严格按 UTC 连接，避免时间错乱
- 通过 Mongo 直接核对消息是否真实写入底层集合
- 短时订阅 WebSocket 消息，辅助排查实时链路问题
- 作为 `NovaRTC` 项目的 AI 调试入口和运维入口
## Project Layout
```text
D:\NovaRTC\NovartcMcp
├─ server.js
├─ package.json
├─ yarn.lock
├─ README.md
├─ MCP-使用手册.md
├─ MCP-工具参数速查表.md
├─ MCP-联调验证案例.md
└─ MCP-故障排查手册.md
```
## Requirements
- Node.js 18+
- Yarn 1.x
- 可访问的 NovaRTC 本地服务：
- HTTP API: `http://127.0.0.1:7000/api`
- WebSocket: `ws://127.0.0.1:9688/ws`
- 可访问的依赖服务：
- MySQL: `127.0.0.1:3307`
- Redis: `127.0.0.1:6379`
- MongoDB: `127.0.0.1:27017`
- RocketMQ: `127.0.0.1:9876`
## Installation
```powershell
cd D:\NovaRTC\NovartcMcp
yarn install
```
## Run
```powershell
cd D:\NovaRTC\NovartcMcp
node server.js
```
说明：
`NovartcMcp` 运行在 `stdio` 模式，不额外监听 HTTP 端口。
它通过标准输入输出与 MCP 客户端通信。
## Codex Integration
Codex 的配置文件路径：
- `C:\Users\tangj\.codex\config.toml`
推荐配置如下：
```toml
[mcp_servers.novartc]
command = "node"
args = ["D:\\NovaRTC\\NovartcMcp\\server.js"]
[mcp_servers.novartc.env]
NOVARTC_API_BASE_URL = "http://127.0.0.1:7000/api"
NOVARTC_WS_URL = "ws://127.0.0.1:9688/ws"
```
修改配置后请重启 Codex。
## Available Tools
当前已实现工具：
- `novartc_health_check`
- `novartc_connection_profile`
- `novartc_server_config`
- `novartc_check_dependencies`
- `novartc_mysql_utc_check`
- `novartc_get_user_presence`
- `novartc_login`
- `novartc_list_contacts`
- `novartc_start_chat`
- `novartc_list_chats`
- `novartc_get_chat_history`
- `novartc_mark_chat_read`
- `novartc_send_text_message`
- `novartc_send_group_text_message`
- `novartc_send_ping`
- `novartc_realtime_subscribe`
- `novartc_query_message_by_id`
- `novartc_query_mongo_message_raw`
- `novartc_tail_message_persistence`
## Documentation
### 1. 使用手册
文件：`D:\NovaRTC\NovartcMcp\MCP-使用手册.md`
### 2. 工具参数速查表
文件：`D:\NovaRTC\NovartcMcp\MCP-工具参数速查表.md`
### 3. 联调验证案例
文件：`D:\NovaRTC\NovartcMcp\MCP-联调验证案例.md`
### 4. 故障排查手册
文件：`D:\NovaRTC\NovartcMcp\MCP-故障排查手册.md`
## Recommended Reading Order
首次接触建议按以下顺序阅读：
1. `MCP-使用手册.md`
2. `MCP-工具参数速查表.md`
3. `MCP-联调验证案例.md`
4. `MCP-故障排查手册.md`
## Verified Capabilities
当前已经完成真实联调验证的能力包括：
- `novartc_login`
- `novartc_list_contacts`
- `novartc_start_chat`
- `novartc_mysql_utc_check`
- `novartc_send_text_message`
- `novartc_get_chat_history`
## Current Limitations
当前版本仍有边界：
- 实时订阅是限时监听，不是长期后台会话
- 群聊发送需要明确提供 `chatId` 和 `groupId`
- 还未桥接图片 / 文件实时发送
- 还未提供服务端日志实时流工具
## Roadmap
后续建议扩展能力：
- `novartc_send_group_image_message`
- `novartc_query_online_users`
- `novartc_tail_server_log`
- `novartc_realtime_subscribe_presence`
- `novartc_query_group_profile`
## Why MCP Matters For This Project
在 `NovaRTC` 这个项目里，MCP 的价值主要体现在三点：
- 统一调试入口：把 HTTP、WebSocket、MySQL、Redis、MongoDB、RocketMQ 串成一个 AI 可调用入口
- 降低联调成本：减少手工拼 token、连 ws、组 protobuf、查历史、查配置的重复操作
- 提升排障效率：让 Codex 不只是解释代码，还能直接参与项目验证和问题定位
`NovartcMcp` 的目标不是取代业务系统，而是成为 `NovaRTC` 的 AI 调试台和运维台。
