home-mcp: Command for Claude Code

$1 $2

我需要在项目中创建一个新的MCP工具。请帮我完成完整的开发流程：

1. 分析需求

基于我提供的工具名称 <tool-name> 和描述 <tool-description>：

• 确定工具类型：属于哪种Home Assistant设备或服务控制
• 分析参数需求：确定输入参数的类型和验证规则
• 设计API接口：定义工具的方法签名和返回格式

2. 生成文件结构

创建以下标准文件：

src/
├── services/
│   └── {kebab-tool-name}.ts          # 工具实现类
├── types/
│   └── {kebab-tool-name}.ts          # 类型定义
└── test/
    └── {kebab-tool-name}.test.ts     # 测试文件

docs/content/mcp-tools/
└── {kebab-tool-name}.mdx             # 工具文档

3. 服务类实现模式

基于现有 LightService 模式：

3.1 基础结构

import { Param, Tool } from "bestmcp";
import { z } from "zod";
import type { HassState, ServiceData } from "../types";

interface IHassService {
  getStates(params?: { entity_id?: string }): Promise<HassState[]>;
  callServices(params: { domain: string; service: string; service_data: Record<string, unknown> }): Promise<{
    changed_states?: HassState[];
  }>;
}

export class {ToolName}Service {
  private static hassServiceInstance: IHassService | null = null;

  public static setHassService(hassService: IHassService) {
    {ToolName}Service.hassServiceInstance = hassService;
  }

  private getHassService(): IHassService {
    if (!{ToolName}Service.hassServiceInstance) {
      throw new Error("{ToolName}Service 未初始化，请先调用 setHassService()");
    }
    return {ToolName}Service.hassServiceInstance;
  }

  @Tool("{工具描述}")
  public async {ToolName}(
    // 参数定义...
  ) {
    // 实现逻辑...
  }
}

3.2 标准方法模式

• 设备查找：getEntitiesByName() 方法
• 参数验证：使用 Zod schema 进行严格类型检查
• 错误处理：统一的错误处理和用户友好的错误消息
• 状态更新：调用 Home Assistant 服务并返回结果

4. 类型定义标准

基于现有 types/light.ts 模式：

4.1 基础类型

• 参数类型：工具方法的输入参数接口
• 返回类型：工具方法的返回值接口
• 错误类型：自定义错误类和错误代码
• 配置类型：预设配置和常量定义

4.2 Home Assistant 集成

• 服务参数：Hass{ToolName}ServiceParams 接口
• 状态信息：{ToolName}DeviceInfo 接口
• 控制结果：{ToolName}ControlResult 接口

5. 测试文件模式

基于现有测试结构：

5.1 测试覆盖范围

• 参数验证测试：Zod schema 验证逻辑
• 服务调用测试：Home Assistant API 交互
• 错误处理测试：各种错误场景
• 边界条件测试：极值和异常输入