内容
# Google Chat Webhook MCP 服务器
[](https://github.com/ice3x2/google-chat-webhook-mcp/actions)
[](https://www.npmjs.com/package/google-chat-webhook-mcp)
[](https://opensource.org/licenses/MIT)
MCP（模型上下文协议）服务器，通过Webhook将消息发送到Google Chat。自动将Markdown转换为Google Chat Cards V2格式，并支持图像验证、结构化日志记录和备用处理。
## 功能
- **MCP协议支持**：与Claude Code、GitHub Copilot等MCP客户端集成
- **Markdown → Cards V2自动转换**：支持标题、列表、代码块、表格、图像等
- **图像URL验证**：通过HEAD请求验证（HTTP状态、Content-Type、大小）
- **自动备用**：在Cards V2失败时自动转换为文本
- **结构化日志记录**：JSON格式，30天保留期
- **测试自动化**：快照测试、集成测试、CI/CD流水线
## 安装
### npm（推荐）
```bash
npm install -g google-chat-webhook-mcp
```
### 从源码（开发）
```bash
git clone https://github.com/ice3x2/google-chat-webhook-mcp.git
cd google-chat-webhook-mcp
npm install
npm run build
```
## Google Chat Webhook设置
在配置MCP服务器之前，请先创建Google Chat Webhook URL：
1. 打开Google Chat空间
2. 菜单 → "应用和集成" → "管理Webhook"
3. 点击"添加Webhook"
4. 输入名称并**复制URL**
5. 在下面的配置中使用它
## MCP客户端配置
### 1. Claude Code
#### 配置文件位置
- **Windows**：`%USERPROFILE%\.claude.json`
- **macOS/Linux**：`~/.claude.json`
**注意**：Claude Desktop使用不同的路径：
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux：`~/.config/Claude/claude_desktop_config.json`
#### npm安装
```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
```
#### 从源码安装
```json
{
"mcpServers": {
"google-chat": {
"command": "node",
"args": ["C:\\path\\to\\google-chat-webhook-mcp\\dist\\index.js"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
```
**⚠️注意**：Windows路径使用`\\`或 `/`（例如`C:/path/to/...`）
#### 配置范围
Claude Code支持三种配置范围：
1. **用户范围**（全局）：`~/.claude.json` - 在所有项目中可用
2. **项目范围**（共享）：项目根目录下的`.mcp.json` - 版本控制，团队共享
3. **本地范围**（私有）：项目特定的个人设置
**优先级**：本地 > 项目 > 用户
#### 项目范围配置（.mcp.json）
对于团队共享的MCP服务器，在项目根目录下创建`.mcp.json`：
```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "${GOOGLE_CHAT_WEBHOOK_URL}"
}
}
}
}
```
**好处**：
- ✅ 版本控制与Git
- ✅ 团队共享配置
- ✅ 环境变量支持：`${VAR}`或`${VAR:-默认值}`
- ✅ 项目特定MCP服务器
**环境变量**：每个团队成员可以设置自己的Webhook URL：
```bash
# Linux/macOS
export GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
# Windows (PowerShell)
$env:GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
```
#### 如何应用
**用户范围配置**（~/.claude.json）：
1. 编辑`~/.claude.json`（或`%USERPROFILE%\.claude.json`在Windows上）
2. 保存文件
3. 如果Claude Code已经运行，请重启
**项目范围配置**（.mcp.json）：
1. 在项目根目录下创建`.mcp.json`
2. 为敏感数据设置环境变量
3. 将`.mcp.json`提交到版本控制系统
4. 使用诸如"发送消息到Google Chat"的命令
### 2. GitHub Copilot（VS Code）
[VS Code GitHub Copilot](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)通过**代理模式**支持MCP。在工作区或用户设置中配置MCP服务器。
#### 配置文件位置
选择以下之一：
- **用户设置**：`~/.vscode/settings.json`或`%APPDATA%\Code\User\settings.json`（Windows）
- **工作区设置**：项目根目录下的`.vscode/settings.json`
#### 配置（mcp.json格式）
添加到`settings.json`：
```json
{
"github.copilot.chat.mcp.servers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
```
#### 功能
- **代理模式集成**：MCP工具在代理工作流中可用
- **每会话工具选择**：为每个会话选择要启用的工具
- **STDIO和SSE支持**：支持两种传输类型
- **调试**：内置重启命令和输出日志记录
#### 使用代理模式
1. 在VS Code中打开GitHub Copilot聊天
2. 启用代理模式（如果尚未启用）
3. 开始对话 - Copilot将自动访问MCP工具
4. 工具需要批准后才能执行
**示例：**
```plaintext
@workspace Send a deployment summary to Google Chat
```
**📝 注意**：GitHub Copilot的MCP支持包括代理模式，允许创建复杂的 workflows。请确保使用最新的VS Code和GitHub Copilot扩展。
### 3. 其他MCP客户端
与任何MCP兼容的客户端配合使用：
```json
{
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "your-webhook-url"
}
}
```
## 用法
### MCP工具（3个工具）
Claude Code或其他MCP客户端中可用的工具：
#### 1. `send_google_chat_text`
发送简单的文本消息
**示例（Claude Code）：**
```plaintext
Send "Hello from Claude!" to Google Chat
```
**参数：**
```json
{
"text": "Hello, Google Chat!"
}
```
#### 2. `send_google_chat_cards_v2`
直接发送Cards V2格式（高级用户）
**参数：**
```json
{
"text": "Card Message",
"cardsV2": [
{
"cardId": "unique-card",
"card": {
"header": { "title": "Card Title" },
"sections": [
{
"widgets": [
{ "textParagraph": { "text": "Card content" } }
]
}
]
}
}
]
}
```
#### 3. `send_google_chat_markdown` ⭐ **推荐**
将Markdown转换为Cards V2并发送
**示例（Claude Code）：**
```plaintext
Send this markdown to Google Chat:
# Project Update
- Task 1: ✅ Completed
- Task 2: 🚧 In Progress
**Deadline**: Tomorrow
```
**参数：**
```json
{
"markdown": "# Title\n\n**Bold** and *italic*\n\n- List item 1\n- List item 2\n\n```python\nprint('Hello')\n```",
"cardTitle": "Markdown Message",
"fallbackToText": true
}
```
**选项：**
- `cardTitle`: 显示在卡片顶部的标题（可选）
- `fallbackToText`: 转换失败时自动发送为文本（默认：false）
### Claude Code用法示例
设置完成后，Claude将自然聊天时自动使用MCP工具：
**👤 用户：**
> "Send a project status update to Google Chat. Show 3 completed tasks and 2 in-progress tasks as a markdown list."
**🤖 Claude：>
> （自动调用`send_google_chat_markdown`工具）
>
> 我已将消息发送到Google Chat。项目状态已更新。
### 支持的Markdown语法
Claude或MCP客户端中编写的Markdown会自动转换为Google Chat Cards V2。
| 语法 | Markdown示例 | Google Chat渲染 |
|--------|------------------|----------------------|
| **标题** | `# H1`, `## H2`, `### H3` | 标题，字体大小不同 |
| **粗体** | `**bold**`或 `__bold__` | **bold** |
| **斜体** | `*italic*`或 `_italic_` | *italic* |
| **内联代码** | `` `code` `` | `code`（等宽字体） |
| **代码块** | ` ```python\ncode\n``` ` | 语法高亮框 |
| **有序列表** | `1. First\n2. Second` | 1. First<br>2. Second |
| **无序列表** | `- Item`或 `* Item` | • Item |
| **嵌套列表** | ` - nested`（2个空格缩进） | • nested（Em space） |
| **表格** | `\| A \| B \|\n\|--\|--\|` | 等宽字体表格 |
| **图像** | `` | 图像小部件（验证后） |
| **链接** | `[text](https://...)` | 可点击链接 |
| **水平线** | `---`或 `***` | 分隔符 |
| **块引用** | `> quote` | 缩进 + 灰色文本 |
**示例Markdown：```markdown
# Project Deployment Complete 🚀
## Key Changes
- **性能**：API响应速度快30%
- **Bug Fix**：登录错误已解决
- 新功能已添加
## 部署状态
| Environment | Status | Version |
|-------------|--------|---------|
| Production | ✅ | v2.1.0 |
| Staging | ✅ | v2.1.0 |
## 下一步
1. 监控24小时
2. 收集用户反馈
3. 计划下一个sprint
代码示例：
```python
def deploy():
print("Deploying v2.1.0...")
return True
```
查看 [documentation](https://docs.example.com) 了解详情。
```
**结果：** 标题、列表、表格和代码块在Google Chat中都视觉区分。
## 环境变量
### 必需
| 变量 | 描述 | 示例 |
|----------|-------------|---------|
| `GOOGLE_CHAT_WEBHOOK_URL` | Google Chat Webhook URL | `https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx` |
### 可选（日志记录）
| 变量 | 描述 | 默认值 | 值 |
|----------|-------------|---------|--------|
| `LOG_LEVEL` | 日志级别 | `INFO` | `DEBUG`, `INFO`, `WARN`, `ERROR` |
| `LOG_DIR` | 日志目录路径 | `./logs` | 绝对/相对路径 |
| `LOG_RETENTION_DAYS` | 日志保留天数 | `30` | 数字（天） |
| `LOG_ENABLE_CONSOLE` | 启用控制台输出 | `true` | `true`, `false` |
### 配置方法
#### Claude Code（~/.claude.json）
```json
| `LOG_RETENTION_DAYS` | 日志保留天数 | `30` | 数字（天） |
### 配置方法
#### Claude Code（~/.claude.json）
```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx",
"LOG_LEVEL": "INFO",
"LOG_RETENTION_DAYS": "30"
}
}
}
}
```
#### .env 文件（开发）
在项目根目录下创建 `.env`：
```env
GOOGLE_CHAT_WEBHOOK_URL=https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx
LOG_LEVEL=INFO
LOG_DIR=./logs
LOG_RETENTION_DAYS=30
LOG_ENABLE_CONSOLE=true
```
## 限制
### Google Chat API 约束
| 项目 | 限制 | 解决方法 |
|------|-------|------------|
| **图像协议** | 仅支持HTTPS | 替换HTTP URL为文本链接 |
| **图像大小** | 最大5MB | 显示为链接（验证失败） |
| **图像权限** | 公共URL | 需要身份验证时无访问权限 |
| **Content-Type** | 仅限 `image/*` | HTML页面被拒绝 |
| **Markdown支持** | 有限 | 近似不支持的语法 |
### Markdown转换限制
**✅ 完全支持：**
- 标题（H1~H6）
- 粗体，斜体，内联代码
- 有序/无序列表（最多3级）
- 代码块（语法高亮）
- 表格（等宽字体）
- 链接，图像
**⚠️ 部分支持：**
- 复杂嵌套 → 简化
- HTML标签 → 转换为文本
- 引用块 → 显示为缩进
**❌ 不支持：**
- 脚注
- 定义列表
- 数学公式（LaTeX）
- 任务复选框（`- [ ]`，`- [x]`）
- Emoji快捷方式（`:smile:`，Unicode表情符号支持）
## 常见问题
### Q: 图像不显示
**A**: 图像验证失败的原因：
1. **仅支持HTTPS**（HTTP不支持）
2. **文件大小**：必须小于5MB
3. **公共访问**：必须可公开访问，无需身份验证
4. **Content-Type**：响应头必须为 `image/*`
**调试：**
```bash
cat logs/app-YYYY-MM-DD.log | grep "image_validation_failed"
```
### Q: Cards V2转换失败
**A**: 使用`fallbackToText`选项：
```json
{
"markdown": "...",
"fallbackToText": true
}
```
检查日志获取详细信息：
```bash
cat logs/errors-YYYY-MM-DD.log
```
### Q: 日志文件过多
**A**: 调整环境变量：
```json
{
"env": {
"LOG_LEVEL": "WARN",
"LOG_RETENTION_DAYS": "7"
}
}
```
### Q: 多个Google Chat空间
**A**: 注册单独的MCP服务器实例：
```json
{
"mcpServers": {
"google-chat-team-a": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/.../team-a/..."
}
},
"google-chat-team-b": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/.../team-b/..."
}
}
}
}
```
## 许可
MIT License - [LICENSE](LICENSE)
## 链接
- [模型上下文协议](https://github.com/modelcontextprotocol)
- [Claude Code](https://claude.ai/desktop)
- [Google Chat API](https://developers.google.com/chat)
#### 设置文件位置
请选择以下之一：
- **用户设置**: `~/.vscode/settings.json` 或 `%APPDATA%\Code\User\settings.json` (Windows)
- **工作区设置**: 项目根目录下的 `.vscode/settings.json`
- **Claude Code 设置** （自动导入）: 从 `~/.claude.json` 复制
#### 设置方法 (mcp.json 格式)
在 `settings.json` 中添加：
```json
{
"github.copilot.chat.mcp.servers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
```
#### 功能
- **代理模式集成**: 在代理工作流中使用 MCP 工具
- **会话级工具选择**: 每个会话可以选择启用的工具
- **STDIO 和 SSE 支持**: 支持两种传输方式
- **调试**: 具有重启命令和输出日志记录
#### 在代理模式下使用
1. 在 VS Code 中打开 GitHub Copilot 聊天窗口
2. 启用代理模式（可能已默认启用）
3. 开始对话 - Copilot 自动访问 MCP 工具
4. 工具执行前需要确认
**示例：**
```
@workspace 将部署摘要发送到 Google Chat
```
**📝 参考**: GitHub Copilot 的 MCP 支持包括代理模式在内的复杂工作流。 请使用最新版本的 VS Code 和 GitHub Copilot 扩展。
### 3. 其他 MCP 客户端
所有支持 MCP 协议的客户端均可使用：
```json
{
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "your-webhook-url"
}
}
```
1. 打开 Google Chat 空间
2. 顶部菜单 → "应用和集成" → "Webhook 管理"
3. 点击 "添加 Webhook"
4. 输入名称并复制 URL
5. 在环境变量中设置
## 用法
### MCP 工具（3 种）
Claude Code 或其他 MCP 客户端可以使用以下工具：
#### 1. `send_google_chat_text`
简单的文本消息发送
**示例（Claude Code）：**
```
Send "Hello from Claude!" to Google Chat
```
**参数：**
```json
{
"text": "您好，Google Chat！"
}
```
#### 2. `send_google_chat_cards_v2`
直接以 Cards V2 格式发送（适用于高级用户）
**参数：**
```json
{
"text": "卡片消息",
"cardsV2": [
{
"cardId": "unique-card",
"card": {
"header": { "title": "卡片标题" },
"sections": [
{
"widgets": [
{ "textParagraph": { "text": "卡片内容" } }
]
}
]
}
}
]
}
```
#### 3. `send_google_chat_markdown` ⭐ **推荐**
自动将 Markdown 转换为 Cards V2 发送
**示例（Claude Code）：**
```
Send this markdown to Google Chat:
# 项目更新
- 任务 1：✅ 已完成
- 任务 2：🚧 进行中
**截止日期**：明天
```
**参数：**
```json
{
"markdown": "# 标题\n\n**粗体文字**和 *斜体*\n\n- 列表项 1\n- 列表项 2\n\n```python\nprint('Hello')\n```",
"cardTitle": "Markdown 消息",
"fallbackToText": true
}
```
**选项：**
- `cardTitle`: 显示在卡片顶部的标题（可选）
- `fallbackToText`: 转换失败时自动发送为文本（默认：false）
### Claude Code 使用示例
设置完成后，与 Claude 以自然语言对话即可自动使用 MCP 工具：
**👤 用户：**
> "将项目状态更新发送到 Google Chat。列出 3 个已完成的任务和 2 个正在进行的任务，以 Markdown 列表显示。"
**🤖 Claude：**
> （自动调用 `send_google_chat_markdown` 工具）
>
> 已将消息发送到 Google Chat。项目状态已更新。
**👤 用户：**
> "在刚刚发送的消息中添加代码示例。"
**🤖 Claude：**
> （再次生成 Markdown 消息并发送）
### 支持的 Markdown 语法
Claude 或 MCP 客户端编写 Markdown 消息时，会自动转换为 Google Chat Cards V2。
| 语法 | Markdown 示例 | Google Chat 渲染 |
|------|---------------|-------------------|
| **标题** | `# H1`, `## H2`, `### H3` | 粗体字 + 尺寸差异 |
| **粗体** | `**bold**` 或 `__bold__` | **bold** |
| **斜体** | `*italic*` 或 `_italic_` | *italic* |
| **内联代码** | `` `code` `` | `code` （固定宽度字体） |
| **代码块** | ` ```python\ncode\n``` ` | 语法高亮框 |
| **有序列表** | `1. First\n2. Second` | 1. First<br>2. Second |
| **无序列表** | `- Item` 或 `* Item` | • Item |
| **嵌套列表** | ` - nested` （2 个空格缩进） | • nested （Em space） |
| **表格** | `\| A \| B \|\n\|--\|--\|` | 固定宽度字体表格 |
| **图片** | `` | 图片小部件（URL 验证后） |
| **链接** | `[文本](https://...)` | 可点击的链接 |
| **水平线** | `---` 或 `***` | 分隔线 |
| **引用** | `> quote` | 缩进 + 灰色文本 |
**示例 Markdown：**
```markdown
# 项目部署完成 🚀
## 主要变更
- **性能改进**：API 响应速度提高 30%
- **错误修复**：登录错误解决
- 新增功能
## 部署状态
| 环境 | 状态 | 版本 |
|------|------|------|
| 生产环境 | ✅ | v2.1.0 |
| 预发布环境 | ✅ | v2.1.0 |
## 下一步
1. 监控 24 小时
2. 收集用户反馈
3. 计划下个冲刺
代码示例：
```python
def deploy():
print("Deploying v2.1.0...")
return True
```
详细内容请参阅 [文档](https://docs.example.com)。
```
**转换结果：** Google Chat 中标题、列表、表格、代码块均以视觉上区分显示。
## 环境变量
### 必需环境变量
| 变量名 | 说明 | 示例 |
|--------|------|------|
| `GOOGLE_CHAT_WEBHOOK_URL` | Google Chat Webhook URL | `https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx` |
### 可选环境变量（日志记录）
| 变量名 | 说明 | 默认值 | 允许值 |
|--------|------|--------|--------|
| `LOG_LEVEL` | 日志级别 | `INFO` | `DEBUG`, `INFO`, `WARN`, `ERROR` |
| `LOG_DIR` | 日志目录路径 | `./logs` | 绝对/相对路径 |
| `LOG_RETENTION_DAYS` | 日志保留天数 | `30` | 数字（天） |
| `LOG_ENABLE_CONSOLE` | 控制台输出 | `true` | `true`, `false` |
### 设置方法
#### Claude Code (~/.claude.json)
```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx",
"LOG_LEVEL": "INFO",
"LOG_RETENTION_DAYS": "30"
}
}
}
}
```
#### .env 文件（开发用）
在项目根目录创建 `.env` 文件：
```env
GOOGLE_CHAT_WEBHOOK_URL=https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx
LOG_LEVEL=INFO
LOG_DIR=./logs
LOG_RETENTION_DAYS=30
LOG_ENABLE_CONSOLE=true
```
#### 系统环境变量
**Windows（PowerShell）：**
```powershell
$env:GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
```
**Linux/macOS（Bash/Zsh）：**
```bash
export GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
```
## 开发
```bash
# 依赖安装
npm install
# 构建
npm run build
# 开发模式（直接执行 TypeScript）
npm run dev
# Lint 检查
npm run lint
# Lint 自动修复
npm run lint:fix
# 测试
npm run test:snapshot # 快照测试（12 个）
npm run test:logging # 日志系统测试
npm run test:integration # 集成测试（需要 Webhook）
npm test # 完整测试
```
## 架构
```plain
src/
├── index.ts # 入口
├── server.ts # MCP 服务器设置
├── tools/ # MCP 工具
│ ├── sendTextMessage.ts # 文本发送
│ ├── sendCardsV2Message.ts # Cards V2 发送
│ ├── sendMarkdownMessage.ts # Markdown 发送（主要）
│ └── markdownToCards.ts # Markdown → Cards V2 转换
├── utils/ # 工具
│ ├── imageValidator.ts # 图片 URL 验证
│ ├── cardsV2Validator.ts # Cards V2 模式验证
│ ├── logger.ts # 日志系统
│ └── logCleaner.ts # 日志清理
└── types/ # 类型定义
├── markdown.ts
├── googleChat.ts
└── log.ts
```
## 日志记录
### 日志文件结构
```plain
logs/
├── app-2025-10-29.log # 每天日志（所有级别）
├── errors-2025-10-29.log # 错误日志
└── ... # 30 天自动删除
```
### 日志格式（JSON）
```json
{
"timestamp": "2025-10-29T12:34:56.789Z",
"level": "INFO",
"module": "sendMarkdownMessage",
"event": "message_sent",
"messageId": "spaces/xxx/messages/yyy",
"elapsed": 123,
"usedFallback": false,
"cardTitle": "Test Card"
}
```
### 日志事件
- `message_sent`: 消息发送成功
- `fallback_used`: 使用备用方案（Cards V2 → 文本）
- `image_validation_failed`: 图片验证失败
- `send_failed`: 发送失败
- `validation_failed`: 验证失败
### 日志清理
- 服务器启动时自动清理（30 天以上日志删除）
- 每 24 小时自动运行
- 可通过环境变量 `LOG_RETENTION_DAYS` 配置
## 限制
### Google Chat API 限制
| 项目 | 限制 | 对应措施 |
|------|------|-----------|
| **图片协议** | 仅支持 HTTPS | HTTP URL 替换为文本链接 |
| **图片大小** | 最大 5MB | 验证失败时显示为链接 |
| **图片认证** | 仅支持公开 URL | 需要认证时无法访问 |
| **Content-Type** | 仅支持 `image/*` | HTML 页面等将被拒绝 |
| **Markdown 支持** | 有限 | 不支持的语法将转换为近似值 |
### Markdown 转换限制
**✅ 完全支持：**
- 标题（H1~H6）
- 粗体、斜体、内联代码
- 有序/无序列表（最多 3 级嵌套）
- 代码块（语法高亮）
- 表格（固定宽度字体）
- 链接、图片
- 水平线
**⚠️ 部分支持：**
- 复杂的嵌套结构 → 简化
- HTML 标签 → 文本转换
- 引用 → 缩进表示
**❌ 不支持：**
- 脚注（footnotes）
- 定义列表（definition lists）
- 数学公式（LaTeX）
- 任务复选框（`- [ ]`, `- [x]`）
- Emoji 快捷代码（`:smile:` 等，支持 Unicode Emoji）
### 性能与限制
- **图片验证超时**: 5 秒
- **Webhook 请求超时**: 5 秒
- **日志文件大小**: 无限制（30 天自动删除）
- **并发请求**: 无限制（遵守 Google Chat API 限制）
### 安全考虑
⚠️ **Webhook URL 是敏感信息：**
- 请勿提交到 Git
- 禁止在公开存储中暴露
- 建议定期重新生成
- `.env` 文件必须加入 `.gitignore`
## FAQ
### Q: 图片无法显示
**A**: 图片 URL 验证失败原因：
1. **仅支持 HTTPS** （HTTP 不支持）
2. **文件大小**: 需小于 5MB
3. **公开访问**: URL 需可公开访问
4. **Content-Type**: 响应头需为 `image/*`
**调试：**
```bash
# 查看日志
cat logs/app-YYYY-MM-DD.log | grep "image_validation_failed"
```
**验证失败时行为：**
- 图片将替换为文本链接
- 示例：`⚠️ 图片加载失败：https://... (HTTP 404: Not Found)`
### Q: Cards V2 转换失败
**A**: 请检查：
1. **使用 fallbackToText 选项：**
```json
{
"markdown": "...",
"fallbackToText": true
}
```
2. **日志中查找原因：**
```bash
cat logs/errors-YYYY-MM-DD.log
```
3. **不支持的 Markdown 语法：**
- 脚注（footnotes）
- 定义列表（definition lists）
- 复杂的 HTML 标签
### Q: 日志文件积累太多
**A**: 可通过环境变量调整：
```json
{
"env": {
"LOG_LEVEL": "WARN",
"LOG_RETENTION_DAYS": "7"
}
```
- `LOG_LEVEL=ERROR`: 只记录错误
- `LOG_RETENTION_DAYS=7`: 仅保留 7 天
- `LOG_ENABLE_CONSOLE=false`: 关闭控制台输出
### Q: npx 执行时 "command not found" 错误
**A**: 请检查 Node.js 和 npm 是否已安装：
```bash
node --version # 推荐 v18.0.0 以上
npm --version
```
如未安装：
- **Windows**: 从 [nodejs.org](https://nodejs.org/) 下载
- **macOS**: `brew install node`
- **Linux**: `sudo apt install nodejs npm` （Ubuntu/Debian）
### Q: 如何安全地管理 Webhook URL
**A**:
1. **使用环境变量** （不要直接写入设置文件）
2. **不要提交到 Git** （检查 `.gitignore`)
3. **定期重新生成** （疑似泄露时）
4. **Google Chat 删除 Webhook** 可使其失效
### Q: 如何发送消息到多个 Google Chat 空间
**A**: 每个空间注册不同的 MCP 服务器实例：
```json
{
"mcpServers": {
"google-chat-team-a": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/.../team-a/..."
}
},
"google-chat-team-b": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/.../team-b/..."
}
}
}
```
Claude 中可使用 "Send to team-a" 或 "Send to team-b" 进行区分使用。
## CI/CD
GitHub Actions 自动化：
- ✅ Node.js 18.x, 20.x 矩阵构建
- ✅ ESLint 构建测试
- ✅ 快照测试（12 个）
- ✅ 集成测试（主分支）
工作流： [.github/workflows/ci.yml](.github/workflows/ci.yml)
## 贡献
欢迎提交 Issues 和 PR。
## 许可证
MIT License - [LICENSE](LICENSE)
## 文档
- [日志设计](docs/logging-design.md)
- [CI 设置指南](docs/ci-setup.md)
- [Markdown 实现计划](docs/markdown-to-cards-implementation.md)
## 相关项目
- [Model Context Protocol](https://github.com/modelcontextprotocol)
- [Claude Code](https://claude.ai/desktop)
- [Google Chat API](https://developers.google.com/chat)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器