使用说明

Childermass-私人家居助理代理

一款基于模型上下文协议（MCP）的复杂个人助理和家庭自动化代理，灵感来自《乔纳森·斯特兰奇和诺雷尔先生》中的约翰·柴尔德马斯。

概述

Childermass是一个基于MCP的模块化代理系统，集成了各种智能家居服务、通信工具和信息源。该系统由一个主代理（Childermass）和不同领域的专用子代理组成。

项目结构

.
├── .opencode/
│   ├── agents/          # Agent configuration files
│   └── opencode.json    # MCP server configuration (DO NOT COMMIT)
├── src/
│   └── childermass/     # MCP server implementations
│       ├── calendar_mcp/    # Google Calendar integration
│       ├── contacts_mcp/    # Google Contacts integration
│       ├── gmail_mcp/       # Gmail integration
│       ├── keep_mcp/        # Google Keep notes
│       ├── mapy_mcp/        # Mapy.com mapping service
│       ├── memory_mcp/      # Persistent memory storage
│       ├── network_mcp/     # UniFi Network management
│       ├── places_mcp/      # Places/location services
│       ├── protect_mcp/     # UniFi Protect camera system
│       ├── tasks_mcp/       # Google Tasks integration
│       └── weather_mcp/     # Weather information
└── venv/                # Python virtual environment (DO NOT COMMIT)

快速开始

1.克隆和设置

git clone <repository-url>
cd Home
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2.安装依赖项

每个MCP服务器都有自己的设置脚本：

# Install specific MCP server
./src/childermass/<mcp-name>/setup.sh

或者一次性安装：

for mcp in src/childermass/*/setup.sh; do
    bash "$mcp"
done

3.配置凭据

⚠️ 重要：永远不要将凭据提交给git！

复制示例配置：

cp .opencode/opencode.example.json .opencode/opencode.json

编辑 .opencode/opencode.json 使用您的实际凭据和路径

根据需要配置单个MCP服务器：

# Google Services (Gmail, Calendar, Tasks, Contacts)
source venv/bin/activate
PYTHONPATH=src python -m childermass.gmail_mcp.auth --setup

# UniFi Protect (cameras)
PYTHONPATH=src python -m childermass.protect_mcp.auth --setup

# UniFi Network
PYTHONPATH=src python -m childermass.network_mcp.auth --setup

# Mapy.com API
PYTHONPATH=src python -m childermass.mapy_mcp.auth --set-api-key YOUR_KEY

4.测试安装

# Test a specific MCP server
PYTHONPATH=src python -m childermass.<mcp-name>.auth --test

# Run tests
PYTHONPATH=src pytest src/childermass/<mcp-name>/tests/ -v

可用的MCP服务器

沟通与生产力

gmail_mcp：电子邮件管理和搜索
日历_mcp：日历事件和日程安排
联系人_mcp：联系信息管理
任务_mcp：任务和待办事项列表管理
keep_mcp：记笔记（当前已禁用）

智能家居

protect_mcp：UniFi Protect相机系统（10个工具）
网络_mcp：UniFi网络管理（17个工具）

位置和信息

地图_mcp：捷克地图、路线、地理编码（9个工具）
地点_mcp：地点查找和信息
天气_mcp：天气预报和情况

基础设施

memory_mcp：代理的持久内存

安全

⚠️ 有关全面的安全信息，请阅读安全.md

此项目处理敏感凭据和个人数据。 永远不要承诺:

.opencode/opencode.json （您的实际配置）
任何 *-credentials.json 或 *-tokens*.json 文件
文件在 ~/.childermass/ 目录
SQLite数据库文件(*.sqlite*)
虚拟环境文件

凭据被安全地存储：

谷歌服务：系统密钥环中的OAuth令牌
UniFi服务：macOS钥匙链/Linux特勤局中的凭据
Mapy.com 网站：密钥环或加密文件中的API密钥
绿色：环境变量中的凭据（不是git）

所有MCP服务器包括：

输入验证与净化
速率限制（令牌桶算法）
结构化审计日志记录
错误消息清理

报告安全问题：参见安全.md 负责披露过程。

发展

运行测试

# All tests
PYTHONPATH=src pytest src/childermass/ -v

# Specific MCP server
PYTHONPATH=src pytest src/childermass/<mcp-name>/tests/ -v

# With coverage
PYTHONPATH=src pytest --cov=src/childermass --cov-report=html

添加新的MCP服务器

创建目录： src/childermass/<name>_mcp/
执行所需文件：
- __init__.py -包元数据
- server.py -MCP服务器实现
- client.py -服务API客户端
- auth.py -身份验证管理
- security.py -验证和安全
- requirements.txt -依赖关系
- setup.sh -安装脚本
- README.md -文件
- tests/ -测试套件
将配置添加到 .opencode/opencode.json
更新此自述文件

代理配置

代理行为定义见 .opencode/agents/:

childermass.md -主要协调代理
radar.md -通信专家（计划）
Krátura.md -安全专家（计划）
jorge.md -信息策展人（计划中）

开发与CI/CD

测试和代码质量

所有MCP服务器都包括全面的测试和代码质量检查：

# Using Make (recommended)
make help              # Show all available commands
make install           # Install development dependencies
make test              # Run all tests
make test-cov          # Run tests with coverage
make lint              # Check code quality
make format            # Auto-format code
make security          # Run security scans
make ci                # Run full CI pipeline locally

# Or manually
pytest src/ -v                                    # Run tests
ruff check src/                                   # Lint code
mypy src/ --ignore-missing-imports               # Type check
bandit -r src/                                    # Security scan

GitHub操作工作流

自动化的CI/CD管道在每次推送和PR上运行：

CI管道 (.github/workflows/ci.yml)
- 使用Ruff编写代码
- 使用MyPy进行类型检查
- 安全审计（pip审计、Bandit、安全）
- 适用于所有MCP服务器的全面测试套件
- 覆盖率报告
CodeQL分析 (.github/workflows/codeql.yml)
- 高级安全漏洞检测
- 每周自动扫描
OSSF记分卡 (.github/workflows/scorecard.yml)
- 开源安全最佳实践评分
- 供应链安全评估
秘密扫描 (.github/workflows/secrets-scan.yml)
- TruffleLog和GitLeaks用于凭证检测
- 每日自动扫描

依赖机器人

为以下对象配置了自动依赖关系更新：

所有11个MCP服务器（Python依赖项）
GitHub 操作
带有自动PR的每周时间表

看 docs/CI_CD.md 详细文档。

预提交钩子

可选，但建议用于当地开发：

pip install pre-commit
pre-commit install
pre-commit run --all-files

配置： .pre-commit-config.yaml

故障排除

模块导入错误

确保 PYTHONPATH 已设置：

export PYTHONPATH=/path/to/Home/src

钥匙扣/凭证问题

# Check keyring availability
python -c "import keyring; keyring.get_keyring()"

# Reset credentials
PYTHONPATH=src python -m childermass.<mcp-name>.auth --setup

连接问题

验证服务的网络连接
检查UniFi设备是否在本地网络上
确保API密钥有效且未过期

贡献

欢迎拉取请求。对于重大变更：

先打开一个问题进行讨论
确保所有测试通过
为新功能添加测试
更新文档
切勿提交凭据或个人数据

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

第三方许可证

这个项目使用了几个开源库。所有依赖项都使用与项目的MIT许可证兼容的许可证（MIT、Apache 2.0、BSD）。有关第三方依赖关系的详细许可证信息，请参阅第三阶段_许可.md.

积分

灵感来源：

约翰·奇尔德马斯选自苏珊娜·克拉克的《乔纳森·斯特兰奇与诺雷尔先生》
Zdeněk Jirotka小说中的Saturnin
DC漫画公司的阿尔弗雷德·彭尼沃斯

内置：

模型上下文协议（MCP）
FastMCP
各种谷歌、UniFi和捷克服务API