home-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

Home-MCP 是一个基于 Model Context Protocol (MCP) 的智能家居集成服务器，旨在为 AI 助手提供标准化的 Home Assistant 设备控制接口。当前实现包含基础的数学运算工具（add、subtract），为后续扩展智能家居功能做准备。

开发命令

基础命令

# 构建项目
pnpm build

# 开发模式（热重载）
pnpm dev

# 生产模式启动
pnpm start

# 运行测试
pnpm test

# 测试覆盖率
pnpm test:coverage

代码规范

# 代码检查
pnpm lint

# 自动修复
pnpm lint:fix

# 格式化代码
pnpm format

# 综合检查和修复
pnpm check:fix

拼写检查

# 检查所有文件的拼写
pnpm spellcheck

# 仅检查源代码拼写
pnpm spellcheck:src

# 仅检查文档拼写
pnpm spellcheck:docs

# 导出拼写错误单词列表
pnpm spellcheck:fix

技术架构

核心组件

• MCP 服务器：使用 @modelcontextprotocol/sdk 实现的 stdio 服务器
• 工具系统：基于 MCP 协议的工具定义和调用处理
• 类型安全：完整的 TypeScript 类型定义和 JSON Schema 验证

项目结构

src/
├── index.ts          # MCP 服务器入口点，包含工具定义和请求处理

关键实现

• 服务器配置：src/index.ts:7-17 - MCP 服务器基础配置
• 工具列表：src/index.ts:20-61 - 可用工具的定义和 schema
• 请求处理：src/index.ts:64-119 - 工具调用逻辑和错误处理
• 启动逻辑：src/index.ts:121-130 - 服务器启动和错误处理

开发指南

添加新工具

1. 在 ListToolsRequestSchema 处理器中添加工具定义
2. 在 CallToolRequestSchema 处理器中实现工具逻辑
3. 添加适当的参数验证和错误处理
4. 返回标准格式的响应

文档开发流程

重要：更新文档后必须进行本地验证，避免Vercel部署失败

1. 创建或更新文档

   • 使用 /docs-create [type] [title] 创建新文档
   • 或直接编辑现有的 .mdx 文件

2. 本地验证（必须执行）

   # 启动文档开发服务器
   nr dev:docs
   
   # 等待服务启动（约10-15秒）
   
   # 验证首页访问
   curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
   # 应返回200状态码
   

3. 检查常见问题

   • 编译错误：查看终端输出，修复MDX语法或组件导入问题
   • _meta.ts配置：确保新文档在对应的_meta.ts文件中正确配置
   • 组件导入：避免使用有问题的Nextra组件，出现问题时可用普通HTML元素替代

4. 验证成功标准

   • 服务启动无报错
   • 首页返回200状态码
   • 新文档页面正常访问
   • 拼写检查通过：pnpm spellcheck

5. 停止服务

   # 使用 Ctrl+C 停止服务
   

文档问题排查经验

根据实际遇到的问题总结：

• TypeError: Cannot convert undefined or null to object

  • 通常由Nextra组件导入问题引起
  • 解决方案：移除有问题的组件，使用普通HTML或CSS样式替代

• Validation of "_meta" file has failed

  • _meta.ts文件引用了不存在的文档
  • 解决方案：从_meta.ts中移除无效引用，或创建对应的文档文件