Samuel System Public

Samuel--家庭智能MCP服务器

Samuel是一个MCP服务器和网桥，它使Claude能够实时访问示例家庭HA配置和状态。它在专用的Linux机器上运行(samuel)旁边是只读克隆 ha-config.

注： 这是一个经过净化的实时部署副本。个人标识符、设备ID和网络详细信息已被占位符替换。要使用它，请替换您自己的HA主机、令牌和实体ID。 专为 家庭助手不隶属于家庭助理项目或开放家庭基金会，也不受其认可。

与家庭助理的关系

Samuel的设计是为了操作 与现有的家庭助理部署一起.

此存储库包含Samuel MCP服务器 和 REST桥:

• MCP服务器（端口5100）——Claude的工具调用界面；实现配置、状态、文档和运行状况工具组
• REST桥（端口5101）——用于非MCP调用者和健康检查的HTTP接口

塞缪尔 不直接控制设备。所有执行都是通过家庭助理进行的，所有拟议的操作都需要明确的人工确认。

完整的部署包括：

• 集成Samuel的Home Assistant配置仓库
• 这个Samuel服务仓库与HA一起运行

请在此处查看家庭助理配置：

• ha-config-public

这种分离是有意的：

• Home Assistant仍然具有确定性和权威性
• 塞缪尔仍然是顾问、可检查和受约束的

快速开始

# On the Samuel box (Ubuntu Server):
cd ~/samuel-system
bash install.sh

安装脚本将：

1. 查找Python 3.10+（MCP SDK要求）
2. 在以下位置创建虚拟环境 .venv
3. 安装依赖项
4. 创建 ~/data/ 为了国家的持久性
5. 可选择安装systemd服务（启动时自动启动）

先决条件

1. 克隆此仓库： git clone git@github.com:your-github-user/samuel-system.git ~/samuel-system
2. 克隆ha配置（只读）： git clone git@github.com:your-github-user/ha-config.git ~/ha-config
3. 创建 .env 从示例中可以看出： cp .env.example .env 并填写数值

环境变量

手动运行

source .venv/bin/activate
python -m samuel          # MCP server (port 5100)
python -m samuel.bridge   # Bridge server (port 5101)

连接克劳德代码

claude mcp add --transport http samuel http://samuel.local:5100/mcp

连接克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "samuel": {
      "url": "http://samuel.local:5100/mcp"
    }
  }
}

可用工具

工具按域组织。每个工具都注册了风险元数据（通过 tool_metadata.py)这样Samuel就可以在没有批准的情况下自主决定打什么电话。

配置工具-- config_tools.py （从ha配置仓库读取）

状态工具-- state_tools.py （查询HA API）

文档工具-- doc_tools.py

健康工具-- health_tools.py

简报工具-- briefing_tools.py

主页基础设施工具-- home_infra_tools.py

需要 home_assistant_bridge, host_bridge，以及 event_pipeline 模块（不在公共仓库中——请参阅文件中的接口契约注释）。

通信工具-- comms_tools.py

工具元数据-- tool_metadata.py

服务管理（systemd）

sudo systemctl status samuel-mcp       # Check status
sudo systemctl status samuel-bridge
sudo systemctl restart samuel-mcp      # Restart
sudo systemctl restart samuel-bridge
journalctl -u samuel-mcp -f            # Follow logs
journalctl -u samuel-bridge -f

独立健康报告

这 diagnostics/morning_health.py 脚本可以独立运行（例如通过cron）：

source .venv/bin/activate
python diagnostics/morning_health.py --dry-run   # Preview
python diagnostics/morning_health.py              # Write to DATA_DIR

测试

# Start samuel, then in another terminal:
npx @modelcontextprotocol/inspector
# Connect to http://localhost:5100/mcp
# Try calling list_packages, search_config("quiet_hours"), etc.

# Test bridge:
curl http://localhost:5101/ping
curl http://localhost:5101/health

建筑

samuel-system (this repo)           ha-config (separate repo, read-only clone)
├── samuel/                         ├── packages/*.yaml
│   ├── server.py     (MCP :5100)  ├── scripts.yaml
│   ├── bridge.py     (REST :5101) ├── docs/system_map.md
│   ├── config_reader.py ────────→ └── ...
│   ├── ha_client.py ─────────────→ Home Assistant REST API
│   └── tools/
│       ├── config_tools.py         (reads ha-config YAML)
│       ├── state_tools.py          (queries HA /api/states)
│       ├── doc_tools.py            (reads docs/)
│       ├── health_tools.py         (HA + Samuel diagnostics)
│       ├── briefing_tools.py       (spoken home status summaries)
│       ├── home_infra_tools.py     (entity history, services, logs, host)
│       ├── comms_tools.py          (Telegram + approval request routing)
│       └── tool_metadata.py        (risk registry for all tools)
├── diagnostics/
├── systemd/
│   ├── samuel-mcp.service
│   └── samuel-bridge.service
└── .env

风险模型： 每个工具都注册了风险级别(read_only, low_risk, moderate_risk, high_risk)，是否需要明确批准，以及自主呼叫是否安全。在运行时通过以下方式查询目录 list_tool_metadata_json.

相关

• ha配置公开 --Samuel读取的家庭助理配置。模块化封装、照明标准、运动感知房间和存在检测。
• 管理层 --Samuel为审批门控执行实施的治理框架： Propose → Explain → Confirm → Execute → Learn.

需求

• Python 3.10+
• Ubuntu服务器24.04 LTS（或带有systemd的类似Linux）
• .env 随着 HA_URL, HA_TOKEN，以及 REPO_PATH
• 对HA实例的网络访问（用于状态/健康工具）
• ha-config的本地克隆（用于config/doc工具）