Famulor-MCP：基于MCP协议构建个人AI智能家居与自动化服务

1. 项目概述：一个面向家庭与个人服务的MCP服务器

最近在GitHub上闲逛，发现了一个挺有意思的项目，叫Famulor-MCP。光看名字，Famulor这个词有点生僻，查了一下，它源自拉丁语，有“仆人”或“服务者”的意思。而MCP，在AI工具链的语境里，特指“模型上下文协议”。所以，这个项目本质上是一个实现了MCP协议的服务器，它的定位是“家庭与个人服务”。

这立刻引起了我的兴趣。我们平时折腾AI助手，无论是Claude Desktop、Cursor还是其他集成了MCP的IDE，它们的能力边界很大程度上取决于我们能给它连接上什么样的“手”和“眼”。官方的MCP服务器大多聚焦在文件读写、搜索、计算等通用能力上。而Famulor-MCP瞄准的是一个更具体、更生活化的场景：把你的智能家居设备、本地媒体库、甚至是一些个人自动化脚本，都变成AI助手可以理解和操控的对象。简单说，它想让你的AI助手，比如Claude，能帮你关灯、放音乐、查快递，或者运行你写好的一个整理照片的脚本。

这个想法非常棒。AI大模型擅长理解和规划，但缺乏执行具体动作的能力。MCP协议就是为了解决这个问题，让AI能安全、可控地调用外部工具。Famulor-MCP则是将这个理念下沉到了每个人的日常生活空间里。它不适合企业级部署，它的核心用户就是开发者、极客，或者任何希望用自然语言更优雅地管理自己数字生活和物理环境的个人用户。接下来，我就结合对这个项目源码的梳理和实际搭建体验，来详细拆解它的设计思路、实现细节以及如何让它真正为你服务。

2. 核心架构与设计哲学解析

2.1 为什么选择MCP协议作为基石

在深入Famulor-MCP的代码之前，我们必须先理解它为什么构建在MCP之上。这不仅仅是技术选型，更是项目定位的体现。MCP是一个新兴但迅速被采纳的开放协议，由Anthropic提出，旨在标准化AI模型与外部工具、数据源之间的通信方式。它的核心优势在于“解耦”和“安全”。

首先，解耦带来了极大的灵活性。对于Famulor-MCP的开发者bekservice来说，他不需要去修改Claude、Cursor或其他任何客户端的代码。他只需要按照MCP的规范（一个基于JSON-RPC的协议）实现一个服务器。任何兼容MCP的客户端，在配置了这个服务器的地址后，就能立刻获得其提供的所有工具。这意味着，你为Famulor-MCP开发的一个“播放Spotify音乐”的工具，可以同时在Claude Desktop、Windsurf、Continue等不同环境中使用。这种“一次开发，多处运行”的特性，对于个人服务这种场景至关重要，因为用户使用的AI前端可能经常切换。

其次，内建的安全模型是关键。MCP协议在设计之初就考虑了权限控制。服务器向客户端声明自己提供哪些“工具”（Tools）和“资源”（Resources），而客户端（最终是用户）需要显式地授权AI模型去使用这些工具。在Famulor-MCP的上下文中，这意味着你可以放心地让它接入你的智能家居API密钥，因为当Claude试图调用“关闭卧室灯”时，Claude Desktop会弹出一个明确的权限请求，问你“是否允许Claude使用‘家庭设备控制’工具？”。你批准了，这次调用才会发生。这种“按次授权”或“会话授权”的机制，比传统上直接给AI模型一个长期有效的最高权限令牌要安全得多。

最后，协议标准化降低了开发复杂度。MCP规定了标准的listTools，callTool，readResource等方法。作为服务器开发者，bekservice可以专注于实现具体的家庭服务逻辑，而无需操心如何与五花八门的AI客户端建立通信、处理并发、管理会话状态。社区提供的各种MCP SDK（如TypeScript/JavaScript的@modelcontextprotocol/sdk）进一步简化了开发。Famulor-MCP正是基于此SDK构建的，这保证了其核心通信层的稳定性和兼容性。

2.2 Famulor-MCP 的模块化设计思路

打开项目的源代码结构，你能清晰地看到它的模块化设计。这不是一个把所有逻辑都塞进index.ts的玩具项目，而是体现了良好的工程化思想。

src/ ├── servers/ # 核心MCP服务器实现 ├── services/ # 具体的服务领域模块 │ ├── media/ # 媒体服务（如Plex, Jellyfin） │ ├── smart-home/# 智能家居服务（如Home Assistant） │ ├── system/ # 系统服务（如脚本执行） │ └── ... # 其他可扩展服务 ├── tools/ # 具体工具的实现 ├── types/ # 类型定义 └── utils/ # 通用工具函数

这种结构的好处非常明显：高内聚、低耦合、易扩展。services/目录下的每个子文件夹都代表一个独立的服务领域。例如，services/smart-home/里的代码只关心如何与Home Assistant或类似的平台对话，它对外暴露几个标准的函数，比如getDevices()，controlDevice(deviceId, action)。而servers/目录下的MCP服务器主文件，则负责导入这些服务模块，将它们封装成MCP协议规定的Tool对象。

当你需要新增一个服务，比如接入你的NAS管理功能，你只需要在services/下创建一个nas/目录，实现好具体的API调用逻辑，然后在主服务器文件中导入并注册它。原有的媒体控制、家居控制代码完全不受影响。这种设计使得项目具有很强的生命力，社区贡献者可以很容易地为它添加新的服务模块，而不用担心破坏现有功能。

注意：在实际阅读源码时我发现，当前版本的Famulor-MCP可能还没有完全实现如此清晰的分层，一些工具的实现可能直接放在了tools/目录下。但上述结构是其理想的目标架构，也是我推荐任何想借鉴或二次开发的朋友应该遵循的方向。将业务逻辑（服务）与协议适配层（工具封装）分离，是保持项目长期可维护性的关键。

2.3 配置驱动与安全优先

Famulor-MCP另一个值得称道的设计是它对配置文件的重视。项目通常需要一个配置文件（如config.yaml或.env）来管理各种服务的接入凭证和参数。

# 示例配置结构 smart_home: platform: home_assistant base_url: https://your-ha-instance.local access_token: YOUR_LONG_LIVED_ACCESS_TOKEN media: plex: base_url: http://your-plex-server:32400 token: YOUR_PLEX_TOKEN jellyfin: base_url: http://your-jellyfin-server:8096 api_key: YOUR_JELLYFIN_API_KEY system: allowed_script_paths: - /home/user/scripts/ - /Users/username/automation/

这种配置驱动的设计有三大好处：

1. 安全性：敏感的令牌和URL不硬编码在源码中，降低了泄露风险。配置文件可以被排除在版本控制之外（通过.gitignore）。
2. 灵活性：用户可以根据自己的家庭环境灵活启用或禁用某些服务。如果你没有Plex，完全可以不配置它，相关的工具就不会被加载到MCP服务器中。
3. 可移植性：配置文件和Docker镜像结合，可以轻松地在不同机器上部署相同的服务环境。

在安全方面，除了依赖MCP客户端的授权机制，Famulor-MCP在服务层面也应有考虑。例如，对于system服务中执行本地脚本的功能，它通过allowed_script_paths配置项严格限定了可执行的脚本目录，防止AI被诱导去运行rm -rf /之类的危险命令。这是一种深度防御的思路，不单单依赖前端的权限弹窗，在服务端也做了最小权限的约束。

3. 核心服务模块深度拆解

3.1 智能家居集成：以Home Assistant为例

智能家居控制是Famulor-MCP最吸引人的功能之一。我们以集成度最高的Home Assistant为例，看看它是如何工作的。

连接原理：Home Assistant提供了完善的RESTful API和一个WebSocket API。Famulor-MCP的smart-home服务模块，首先会使用用户在配置中提供的base_url和access_token（在HA中称为“长期访问令牌”）进行认证。通常，它会先调用REST API验证令牌有效性并获取基础信息，然后为了实时性，可能会建立WebSocket连接来监听设备状态变化。

工具暴露：连接成功后，服务模块会调用HA的API获取所有实体的列表（灯、开关、传感器、媒体播放器等）。然后，它不会把所有实体都粗暴地暴露为MCP工具，那样会产生成百上千个工具，让AI客户端侧边栏变得无法使用。相反，它采用了聚合与抽象的策略。

1. 按领域聚合：它会创建像list_light_devices，list_switch_devices这样的工具，当被调用时，返回一个设备列表。
2. 通用控制工具：创建少数几个通用的控制工具，如control_light，toggle_switch。这些工具接受device_id和action（如turn_on，turn_off，set_brightness）作为参数。
3. 场景化工具：更进一步，它可以基于配置或自动学习，创建一些场景化工具，如evening_relax_mode（调暗灯光，关闭电视，播放轻音乐）。这个工具背后可能是按顺序调用多个底层设备控制。

一个具体的工具定义示例（概念代码）：

// 在MCP服务器初始化时，动态创建工具 const tools: Tool[] = []; // 添加一个通用灯光控制工具 tools.push({ name: "control_light", description: "控制一个智能灯光设备。可以开关、调节亮度或颜色。", inputSchema: { type: "object", properties: { device_id: { type: "string", description: "灯光设备的ID，可以从list_light_devices工具获取。" }, action: { type: "string", enum: ["turn_on", "turn_off", "set_brightness", "set_color"], description: "要执行的动作。" }, brightness: { type: "number", description: "亮度百分比（0-100），仅在action为set_brightness时需要。" }, // ... 其他参数 }, required: ["device_id", "action"] } }); // 对应的工具执行函数 async function callControlLight(args: any) { const { device_id, action, brightness } = args; // 构造请求，调用Home Assistant API const response = await fetch(`${config.homeAssistantUrl}/api/services/light/turn_on`, { method: 'POST', headers: { 'Authorization': `Bearer ${config.accessToken}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ entity_id: device_id, brightness_pct: brightness }) }); // ... 处理响应和错误 }

实操心得：在配置Home Assistant令牌时，务必在HA后台创建一个“长期访问令牌”，而不是使用临时令牌。同时，建议在HA中创建一个专门给Famulor-MCP使用的用户，并只授予它控制特定设备域的权限（如light，switch，media_player），遵循权限最小化原则。虽然MCP有客户端授权，但服务端凭证的权限也应受到约束。

3.2 本地媒体库控制：Plex/Jellyfin集成

对于家庭媒体爱好者，能语音或文字命令AI播放特定的电影、音乐或剧集，是极大的便利。Famulor-MCP通过集成Plex或Jellyfin来实现这一功能。

工作流程拆解：

1. 库发现与索引：服务启动时，使用配置的令牌连接Plex/Jellyfin服务器，获取所有媒体库（电影、电视节目、音乐）的列表。为了提高AI调用的成功率，它可能会在本地建立一个小型的元数据索引或缓存，特别是媒体项的标题、年份、演员等关键信息。
2. 搜索与模糊匹配：这是核心难点。当用户对AI说“播放《星际穿越》”时，AI模型会调用类似play_media的工具，并将“星际穿越”作为参数传入。工具函数不能简单地进行字符串精确匹配，因为用户可能说简称、别名，或者包含错误。Famulor-MCP需要实现一个模糊搜索算法。它可能会将查询词与缓存中的标题进行比对，使用像Levenshtein距离或更高级的fuse.js这样的库，返回匹配度最高的几个结果。有时，它还需要处理“播放最新一集《权力的游戏》”这样的请求，这就需要理解媒体库的剧集结构。
3. 播放指令下发：找到正确的媒体项后，工具需要决定在哪里播放。Plex/Jellyfin API允许指定播放客户端（如客厅的Shield TV、卧室的iPad）。Famulor-MCP可以配置一个默认客户端，或者提供一个list_clients工具让AI先询问用户想在哪播放。最终，它调用Plex的/player/playback/playMedia或Jellyfin的/Sessions/Playing等相关API，发起播放请求。

挑战与技巧：

• 性能：全库扫描和索引可能在首次启动时较慢。可以考虑异步索引，或仅索引最近添加的媒体。
• 网络：确保运行Famulor-MCP的服务器（可能是一台常开的NAS或小型服务器）与你的Plex/Jellyfin服务器以及目标播放客户端在同一局域网内，以减少延迟和避免复杂的网络配置。
• 反馈：工具执行后，应该返回明确的结果，例如“已开始在‘客厅电视’上播放《星际穿越》(2014)”。好的反馈能帮助AI模型理解指令已成功执行，并形成更自然的对话。

3.3 系统级工具与脚本执行

这是Famulor-MCP最具潜力但也最需要谨慎处理的部分。它允许AI通过MCP工具调用你本地系统上预先写好的脚本或命令。

典型应用场景：

• 文件管理：“帮我将下载文件夹里所有.jpg图片移动到‘照片’文件夹，并按日期创建子文件夹。”
• 数据备份：“运行一下我的数据库备份脚本。”
• 自动化任务：“触发本周的账单汇总邮件发送任务。”
• 信息查询：“运行那个检查服务器状态的脚本，把结果告诉我。”

实现机制与安全边界： 项目绝不会允许AI直接执行任意Shell命令。相反，它采用“白名单脚本”模式。

1. 你在配置文件中指定一个或多个绝对路径目录（如/home/user/scripts）。
2. 在这些目录中，你放置可执行的脚本（可以是.sh，.py，.js等）。
3. 在Famulor-MCP中，会有一个工具如execute_script，它接受一个script_name参数。
4. 当该工具被调用时，服务器会验证请求的脚本名是否位于白名单目录下，防止路径遍历攻击（如../../../etc/passwd）。
5. 验证通过后，使用Node.js的child_process模块（或其他语言的等价物）在受限的环境中运行该脚本。
6. 捕获脚本的标准输出和错误输出，将其作为工具执行结果返回给AI。

# 配置示例 system_tools: enabled: true allowed_directories: - /home/pi/automation_scripts # 可以进一步限制可执行的文件扩展名 allowed_extensions: ['.sh', '.py', '.js']

重要警告：这是整个项目安全风险最高的部分。务必遵守以下原则：

1. 最小权限：运行Famulor-MCP的进程本身应该使用一个低权限的系统用户（如mcp-user），而不是root。
2. 脚本审计：白名单目录下的每一个脚本都必须是你自己编写或完全信任的。确保脚本本身没有危险操作。
3. 输入消毒：如果脚本接受来自AI的参数（比如文件名），必须在将参数传递给脚本前进行严格的消毒和验证，防止命令注入。
4. 日志记录：所有脚本执行行为，包括调用者（AI会话）、脚本名、参数、执行结果和时间，都必须详细记录，便于审计。

4. 从零到一的完整部署与配置指南

4.1 环境准备与依赖安装

假设我们在一台运行Ubuntu Server 22.04的常开设备（比如树莓派、旧笔记本或家庭服务器）上部署Famulor-MCP。

第一步：基础环境搭建

# 更新系统 sudo apt update && sudo apt upgrade -y # 安装 Node.js 和 npm (项目通常是TypeScript/Node.js项目) # 推荐使用 Node Version Manager (nvm) 安装长期支持版本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 重新打开终端或执行 source ~/.bashrc nvm install 18 nvm use 18 # 验证安装 node --version npm --version # 安装 Git sudo apt install git -y

第二步：获取项目代码

# 克隆仓库 git clone https://github.com/bekservice/Famulor-MCP.git cd Famulor-MCP # 安装项目依赖 npm install # 如果是TypeScript项目，通常还需要全局安装TypeScript和ts-node（或检查package.json） npm install -g typescript ts-node

第三步：构建项目（如果需要）检查package.json中的scripts部分。通常会有：

npm run build # 将TypeScript编译为JavaScript到dist/目录

如果项目设计为直接运行TypeScript，则可能只需要npm run dev或ts-node src/index.ts。我们以需要构建的为例：

npm run build

构建成功后，主入口文件通常在dist/index.js。

4.2 详细配置手册

部署的核心是配置文件。项目根目录下通常会有config.example.yaml或.env.example文件。复制它并创建你自己的配置文件。

cp config.example.yaml config.yaml # 或 cp .env.example .env

现在，我们来逐一填充关键配置项。以下是一个综合性的config.yaml示例：

# Famulor-MCP 主配置 server: host: "0.0.0.0" # 监听所有网络接口，如果只本地使用可改为 127.0.0.1 port: 3000 # MCP服务器端口 # 智能家居 - Home Assistant home_assistant: enabled: true base_url: "https://your-home-assistant.local" # 你的HA地址，注意用https如果启用了SSL access_token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." # HA后台生成的长期访问令牌 # 可选：限制只同步特定域的实体，提高效率 included_domains: - light - switch - media_player - sensor # 媒体服务器 - Plex plex: enabled: true base_url: "http://192.168.1.100:32400" # Plex服务器内网地址 token: "your-plex-token-here" # 在 https://plex.tv/devices.xml 获取 # 可选：指定默认播放的客户端机器名 default_client: "Living-Room-Shield" # 媒体服务器 - Jellyfin (与Plex二选一或同时启用) jellyfin: enabled: false base_url: "http://192.168.1.101:8096" api_key: "your-jellyfin-api-key" user_id: "your-jellyfin-user-id" # 系统脚本工具 system_tools: enabled: true # 谨慎启用 allowed_directories: - "/home/pi/scripts" # 必须是绝对路径，且运行进程有读取和执行权限 # 超时设置，防止脚本卡死 timeout_ms: 30000 # 日志配置 logging: level: "info" # debug, info, warn, error file: "/var/log/famulor-mcp/server.log"

关键配置获取指南：

• Home Assistant令牌：登录HA网页 -> 点击右上角用户名 -> 拉到最下方“长期访问令牌” -> 创建令牌。
• Plex令牌：访问https://plex.tv/devices.xml，登录后，页面源代码中寻找token属性。或者使用第三方工具如plex-token获取。
• Jellyfin API密钥：登录Jellyfin网页 -> 点击右上角用户图标 -> “API密钥” -> 创建新密钥。

注意：将包含敏感令牌的config.yaml文件加入.gitignore，切勿提交到公开仓库。在生产环境中，考虑使用Docker Secrets或环境变量来管理这些秘密。

4.3 运行与测试MCP服务器

配置完成后，可以启动服务器进行测试。

开发模式运行（监听代码变化）：

npm run dev

生产模式运行：

# 如果使用了构建步骤 node dist/index.js # 或者使用进程管理工具，如PM2，保证持续运行 npm install -g pm2 pm2 start dist/index.js --name "famulor-mcp" pm2 save pm2 startup # 设置开机自启

测试服务器是否正常： MCP服务器通常使用SSE（Server-Sent Events）或WebSocket。我们可以用一个简单的cURL命令测试SSE连接（如果项目使用SSE）：

curl -N http://localhost:3000/sse

你应该看到持续的事件流输出，或者一个初始化的JSON-RPC消息。

更专业的测试是使用MCP客户端。最简便的方法是使用@modelcontextprotocol/sdk自带的测试工具，或者直接通过你打算使用的AI客户端（如Claude Desktop）来连接。

4.4 客户端连接配置（以Claude Desktop为例）

这是让一切生效的最后一步。我们需要配置你的AI客户端，让它知道Famulor-MCP服务器的存在。

1. 找到Claude Desktop配置目录：

   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json
   • Linux:~/.config/Claude/claude_desktop_config.json

2. 编辑配置文件：如果文件不存在就创建它。添加一个mcpServers配置项。

   { "mcpServers": { "famulor": { "command": "npx", "args": [ "-y", "tsx", "/absolute/path/to/Famulor-MCP/src/index.ts" ], "env": { "FAMULOR_CONFIG_PATH": "/absolute/path/to/your/config.yaml" } } } }

   解释：这里我们配置了一个名为famulor的MCP服务器。我们使用npx和tsx来直接运行TypeScript源码（假设项目支持）。你也可以指向构建后的JS文件："command": "node", "args": ["/path/to/dist/index.js"]。env部分用于传递环境变量，这里指定了配置文件路径。

3. 重启Claude Desktop：保存配置文件并完全重启Claude Desktop应用。

4. 验证连接：重启后，当你新建一个对话，Claude的输入框上方或侧边栏应该会出现一个“工具”或“连接”的图标。点击它，你应该能看到Famulor-MCP注册的工具列表，例如“列出灯光设备”、“控制开关”、“播放媒体”等。首次使用某个工具时，Claude会弹出授权请求，点击允许即可。

5. 实战场景与高级用法探讨

5.1 场景一：用自然语言管理智能家居

现在，一切就绪。你可以尝试在Claude的对话窗口中输入：

“客厅太亮了，帮我把主灯调到50%的亮度。”

Claude会理解你的意图，调用control_light工具（或类似工具），传入device_id: light.living_room_main和action: set_brightness，brightness: 50。片刻之后，你的灯就会变暗。整个过程，你不需要知道设备的具体ID，也不需要去打开任何App。

更复杂的场景：

“我准备看电影了，帮我设置一下影院模式。”

这可能需要一个组合工具或AI模型进行多步推理。理想情况下，你可以预先在Famulor-MCP中定义一个名为activate_cinema_mode的场景工具，它内部依次执行：1) 关闭所有主灯，2) 打开氛围灯带并调为暗蓝色，3) 关闭窗帘（如果有智能窗帘），4) 打开电视和音响，5) 将音响输入源切换至电视。当AI调用这个场景工具时，所有这些动作会按顺序自动完成。

5.2 场景二：语音与文本结合的媒体控制

虽然Claude是文本界面，但你可以结合系统的语音输入功能（如Mac的听写）来操作。或者，未来如果接入了支持语音的AI助手（如一些开源项目），体验会更无缝。

“播放一些放松的爵士乐。” AI可能会先调用search_music工具，查询媒体库中风格为“Jazz”且情绪标签包含“Relaxing”的歌曲，然后调用play_media工具，在默认的客厅音响上播放生成的播放列表。

“继续播放我昨天没看完的《西部世界》。” 这需要工具能查询播放记录。Famulor-MCP可以提供一个get_resume_items工具，从Plex/Jellyfin获取当前用户的“继续观看”列表，然后AI选择正确的项目并播放。

5.3 场景三：自动化脚本的智能触发

这是将个人自动化提升到新层次的玩法。假设你有一个每周日晚上运行的Python脚本weekly_cleanup.py，它会清理下载文件夹、整理桌面文件并发送一份报告到你的邮箱。

以前，你需要记住时间，或者依赖cron。现在，你可以在周日晚上对Claude说：

“嘿，是时候运行每周清理脚本了。”

Claude调用execute_script工具，运行weekly_cleanup.py。脚本执行过程中的输出（如“已清理15个临时文件”、“报告邮件已发送”）会被返回给Claude，Claude可以总结并告诉你：“已完成每周清理，删除了15个文件，整理报告已发送至你的邮箱。”

你甚至可以创造更动态的指令：

“我感觉下载文件夹有点乱，能帮我整理一下吗？” Claude可以理解“整理下载文件夹”可能对应你预先写好的organize_downloads.py脚本，然后执行它。

5.4 扩展开发：添加自定义服务

Famulor-MCP的魅力在于可扩展性。假设你想添加一个查询本地天气预报的服务。

1. 在services/目录下创建新模块：mkdir src/services/weather && touch src/services/weather/index.ts
2. 实现天气服务逻辑：

   // src/services/weather/index.ts import axios from 'axios'; export interface WeatherConfig { apiKey: string; city: string; units: 'metric' | 'imperial'; } export class WeatherService { private config: WeatherConfig; constructor(config: WeatherConfig) { this.config = config; } async getCurrentWeather(): Promise<string> { try { const url = `https://api.openweathermap.org/data/2.5/weather?q=${this.config.city}&units=${this.config.units}&appid=${this.config.apiKey}`; const response = await axios.get(url); const data = response.data; return `当前${data.name}的天气：${data.weather[0].description}，温度 ${data.main.temp}°C，湿度 ${data.main.humidity}%。`; } catch (error) { console.error('获取天气失败:', error); return '无法获取天气信息。'; } } }

3. 在主服务器文件中导入并注册为MCP工具：

   // 在 src/servers/main.ts 或类似文件中 import { WeatherService } from '../services/weather'; // ... 初始化配置 ... const weatherService = new WeatherService(config.weather); // 将服务方法包装成MCP工具 const tools: Tool[] = [ // ... 其他工具 ... { name: "get_current_weather", description: "获取指定城市的当前天气情况。", inputSchema: { type: "object", properties: {}, // 这个工具不需要参数，使用配置中的城市 required: [] }, execute: async () => { const report = await weatherService.getCurrentWeather(); return { content: [{ type: "text", text: report }] }; } } ];

4. 更新配置文件：在config.yaml中添加weather部分。
5. 重建并重启服务器：npm run build && pm2 restart famulor-mcp。

现在，你就可以问Claude：“今天天气怎么样？”了。

6. 故障排除与性能优化

6.1 常见连接问题与排查

问题1：Claude Desktop无法连接/看不到工具

• 检查点1：服务器是否在运行？pm2 list或ps aux | grep node。
• 检查点2：配置文件路径是否正确？确保Claude配置中command和args指向的路径绝对正确，特别是Windows和macOS的路径格式差异。
• 检查点3：端口冲突？确认Famulor-MCP配置的端口（如3000）没有被其他程序占用。可以临时修改端口试试。
• 检查点4：查看日志：Famulor-MCP的日志（配置中指定的文件或控制台输出）是首要排查依据。查看是否有启动错误、认证失败等信息。
• 检查点5：重启Claude Desktop：有时客户端需要完全重启才能加载新的MCP配置。

问题2：工具调用失败，提示“未授权”或“无效令牌”

• 智能家居/媒体服务器令牌失效：Home Assistant的长期令牌一般不会过期，但Plex的令牌有时会变。重新生成令牌并更新配置文件。
• 网络可达性：确保运行Famulor-MCP的服务器能访问你的Home Assistant/Plex的内网地址。如果用了域名，检查DNS解析。可以尝试在服务器上用curl命令测试连通性：curl -H "Authorization: Bearer YOUR_TOKEN" https://your-ha.local/api/。
• 权限不足：检查你在Home Assistant/Plex/Jellyfin中创建的用户或令牌是否拥有足够的权限（如控制设备、访问媒体库）。

问题3：脚本执行失败

• 权限问题：确保运行Famulor-MCP的系统用户对白名单目录和脚本文件有读取和执行权限（chmod +x /path/to/your/script.sh）。
• 环境变量：脚本可能依赖特定的环境变量（如PATH）。在child_process.spawn时，可以显式传递env参数，继承当前进程的环境并做修改。
• 脚本超时：检查配置中的timeout_ms，对于运行时间较长的脚本，需要适当调大。

6.2 性能优化建议

1. 按需加载服务：在配置文件中将不使用的服务enabled设为false，可以减少服务器启动时的资源消耗和初始化时间。
2. 缓存策略：对于不常变化的数据，如设备列表、媒体库元数据，实现内存缓存（如TTL缓存）。例如，将Home Assistant的设备列表缓存5分钟，避免每次调用list_devices工具都去请求HA API。
3. 连接池与长连接：对于Home Assistant的WebSocket连接，应维护一个持久连接，而不是为每个请求新建连接。对于Plex/Jellyfin的HTTP API，考虑使用HTTP连接池（axios或node-fetch默认支持）。
4. 工具聚合：避免暴露大量细粒度工具。如前所述，将“打开灯1”、“打开灯2”聚合成一个“控制灯”工具，通过参数区分。这能大幅提升AI客户端侧边栏的加载速度和用户体验。
5. 日志级别调整：在生产环境中，将日志级别从debug调整为info或warn，可以减少磁盘I/O和日志体积。

6.3 安全加固清单

• [ ]非root用户运行：创建专用用户mcpuser，并使用此用户运行进程：sudo -u mcpuser node dist/index.js。
• [ ]配置文件权限：chmod 600 config.yaml，确保只有所有者可读。
• [ ]网络隔离：如果服务器暴露在家庭网络中，考虑使用防火墙（如ufw）只允许来自本地客户端（如运行Claude Desktop的电脑）的IP地址访问MCP服务器端口。
• [ ]定期更新：关注项目GitHub仓库的更新，及时拉取安全补丁和功能改进。
• [ ]审计日志：定期检查脚本执行日志，确认没有异常调用。
• [ ]最小化令牌权限：定期审查并收紧Home Assistant、Plex等服务的API令牌权限。

7. 未来展望与生态融合

Famulor-MCP作为一个开源项目，其生命力在于社区。它目前可能还处于早期阶段，但已经勾勒出一个清晰的愿景：让AI成为个人数字生活的统一操作界面。

可能的演进方向：

1. 更多服务集成：社区可以贡献更多服务模块，如日历管理（Google Calendar， Outlook）、邮件客户端、RSS阅读器、智能健身设备控制等。
2. 工具发现与市场：未来或许能形成一个“MCP工具市场”，用户可以像安装插件一样，轻松添加其他人开发的服务模块到自己的Famulor-MCP实例中。
3. 更智能的上下文感知：目前的工具调用还比较“机械”。未来，服务器可以结合更多上下文（如时间、用户习惯、设备状态）来优化工具的执行。例如，晚上说“打开灯”，AI能自动理解为“打开卧室的阅读灯”而非所有灯。
4. 与语音助手深度融合：虽然现在主要通过文本与Claude交互，但其MCP服务器后端完全可以被其他前端调用，比如与开源语音助手（如Rhasspy， Home Assistant自己的语音）结合，实现真正的全屋语音控制智能化。

我个人在搭建和使用的过程中，最大的体会是“边界感”很重要。不是所有事情都适合让AI去做，尤其是涉及安全、隐私和重要数据的操作。Famulor-MCP提供的是一种“可编程”的便利，它把执行权牢牢地框定在你预先定义好的工具和白名单脚本之内。这种设计哲学让我用起来很放心。它不是一个试图接管一切的“强AI”，而是一个听话且能力强大的“数字仆人”，这正是Famulor一词的精髓所在。开始动手吧，从控制一盏灯开始，你会逐渐爱上这种用自然语言驾驭数字世界的感觉。