Google Home MCP Server

用于通过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控制台
   • 创建一个新项目
   • 选择“智能家居”作为项目类型
   • 配置账户链接：
     • OAuth客户端ID
     • OAuth客户端密钥
     • 授权URL
     • 令牌URL

2. 设置OAuth 2.0：

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

3. 安装依赖项：

pnpm install

4. 配置服务器：

   • 将config.json.example复制为config.json
   • 填入您的：
     • OAuth客户端ID
     • OAuth客户端密钥

5. 构建服务器：

pnpm build

6. 启动服务器：

pnpm start

可用工具

1. 列出智能插头

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

2. 控制智能插头

{
  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. 获取智能插头状态

{
  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. 在开发模式下启动：

pnpm dev

2. 运行测试：

pnpm test

3. 调试日志：
   • 记录所有API调用
   • 捕获错误详情
   • 跟踪设备状态变化

贡献

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

许可证

MIT

ghome-mcp-server