Google Home MCP 服务器

一个通过 Smart Home API 控制 Google Home 智能插座的MCP服务器实现。

功能

• 列出所有可用的智能插座及其状态
• 控制智能插座（开关）
• 获取特定智能插座的实时状态
• 自动刷新设备状态
• 通过Smart Home API进行OAuth2认证

前提条件

1. 启用了Smart Home API的Google Cloud项目
2. Actions on Google Smart Home Action项目
3. Smart Home Action的OAuth 2.0客户端凭证
4. Node.js 18或更高版本
5. 访问Google Home智能插座

设置

1. 创建一个Smart Home Action：

   • 转到Actions on Google控制台
   • 创建新项目
   • 选择"Smart Home"作为项目类型
   • 配置账户链接：
     • OAuth Client ID
     • OAuth Client Secret
     • 授权URL
     • Token URL

2. 设置OAuth 2.0：

   • 配置您的OAuth服务器端点
   • 设置用户身份验证流程
   • 实现令牌生成/验证

3. 安装依赖项：
   bash
   pnpm install

4. 配置服务器：

   • 将config.json.example复制为config.json
   • 填写您的：
     • OAuth Client ID
     • OAuth Client Secret

5. 构建服务器：
   bash
   pnpm build

6. 启动服务器：
   bash
   pnpm start

可用工具

1. 列出智能插座

typescript
{
name: "list_smart_plugs",
description: "列出所有可用的智能插座及其当前状态",
response: Array<{
id: string;
name: string;
state: {
on: boolean;
online: boolean;
}
}>
}

2. 控制智能插座

typescript
{
name: "control_smart_plug",
description: "打开或关闭智能插座",
parameters: {
deviceId: string; // 来自list_smart_plugs的设备ID
state: boolean; // true表示开，false表示关
},
response: {
success: boolean;
device: {
id: string;
name: string;
state: {
on: boolean;
online: boolean;
}
}
}
}

3. 获取智能插座状态

typescript
{
name: "get_smart_plug_state",
description: "获取特定智能插座的当前状态",
parameters: {
deviceId: string; // 来自list_smart_plugs的设备ID
},
response: {
id: string;
name: string;
state: {
on: boolean;
online: boolean;
}
}
}

API详情

该服务器实现了Smart Home API意图：

1. SYNC意图

   • 当用户链接其帐户时调用
   • 报告可用设备和功能
   • 处理设备发现

2. QUERY意图

   • 报告设备的当前状态
   • 处理来自Google Assistant的状态查询
   • 返回在线/离线状态

3. EXECUTE意图

   • 处理设备控制命令
   • 执行开/关操作
   • 报告命令成功/失败

错误处理

服务器实现了全面的错误处理，并具有特定的错误代码：

• CONFIG_ERROR: 配置加载或验证错误
• API_ERROR: 来自Smart Home API的错误
• DEVICE_NOT_FOUND: 在可用设备中找不到设备ID
• COMMAND_ERROR: 执行设备命令时发生错误

每个错误包括：

• 错误消息
• 错误代码
• 如有提供，详细的错误信息

安全性

• OAuth 2.0认证流程
• 安全的令牌处理
• 请求验证
• 命令授权
• HTTPS通信
• 输入清理

开发

1. 以开发模式启动：
   bash
   pnpm dev

2. 运行测试：
   bash
   pnpm test

3. 调试日志：

   • 所有API调用都被记录
   • 捕获错误详情
   • 跟踪设备状态变化

贡献

1. 分叉仓库
2. 创建特性分支
3. 提交更改
4. 推送到分支
5. 创建拉取请求

许可证

MIT

ghome-mcp-server