RaspberryPiOS MCP

A. Raspberry Pi MCP服务器 它使AI助手能够通过模型上下文协议（MCP）管理和观察Raspberry Pi OS设备，并通过Cloudflare+OAuth进行安全的设备控制、系统监控和安全的互联网暴露。

🚀 快速安装

# Clone the repository
git clone https://github.com/grammy-jiang/RaspberryPiOS-MCP.git
cd RaspberryPiOS-MCP

# Run the installer (requires sudo)
sudo ./deployment/install.sh

# Check service status
sudo systemctl status mcp-raspi-server

有关详细说明，请参阅入门指南.

特性

系统监控：CPU、内存、磁盘、温度指标
GPIO控制：读/写电子项目的GPIO引脚
I2C通信：与I2C设备（传感器、显示器）的接口
相机拍摄：使用Raspberry Pi相机拍照
服务管理：启动/停止/重新启动systemd服务
流程管理：列出并管理系统流程
安全访问：Cloudflare隧道+OAuth身份验证
自我更新：具有自动回滚功能的远程更新

建筑

┌─────────────────────────────────────────────────────────────────┐
│                      AI Assistant (Claude, etc.)                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                    MCP Protocol (JSON-RPC 2.0)
                                │
                    [Cloudflare Tunnel + Access]
                                │
┌─────────────────────────────────────────────────────────────────┐
│                    mcp-raspi-server                              │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │   JWT/Auth  │  │  MCP Router  │  │     Tool Handlers      │  │
│  │  Validator  │  │   & RBAC     │  │  (system, metrics, ...) │  │
│  └─────────────┘  └──────────────┘  └────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                │
                    Unix Socket IPC (restricted)
                                │
┌─────────────────────────────────────────────────────────────────┐
│                     raspi-ops-agent (privileged)                 │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │    GPIO     │  │     I2C      │  │   System Control       │  │
│  │   Control   │  │  Interface   │  │  (reboot, services)    │  │
│  └─────────────┘  └──────────────┘  └────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

文档

🚀 快速入门（选择你的道路）

项目新手？

📖 docs/00-executive-summary.md –整个系统的5分钟概述
🗺️ docs/quick-start-guide.md –10分钟指导以适应（所有角色）
🧭 docs/document-navigator.md –为您的角色找到合适的医生

AI助手实现功能？

🤖 从这里开始: docs/phase-1-scope-matrix.md –您的完整实施指南

- ✅ 构建什么（必须/应该/第2+阶段） - 📅 逐日实施顺序（42天计划） - 📏 人工智能优化的工作量估计（共4-6周） - 📖 设计文件快速参考 - ✨ 代码质量标准和迭代指南

人类开发者加入？

📖 阅读：执行摘要→ 导航员→ 基础文件（01-03）
💻 设置：遵循Doc13（Python标准）开发环境
🔨 构建：使用文档导航器选择您的模块

完整的设计文件

完整的设计记录在以下编号的规格中 docs/ （推荐阅读顺序）：

docs/01-raspberry-pi-mcp-server-requirements-specification.md 总体目标、范围、功能和非功能要求。
docs/02-raspberry-pi-mcp-server-high-level-architecture-design.md 顶层架构、组件和数据流。
docs/03-raspberry-pi-platform-and-resource-constraints-design-note.md Raspberry Pi平台目标和资源限制。
docs/04-security-oauth-integration-and-access-control-design.md –安全模型、OAuth/Cloudflare集成、访问控制。
docs/05-mcp-tools-interface-and-json-schema-specification.md –MCP工具名称空间、操作和JSON模式。
docs/06-system-information-and-metrics-module-design.md –系统信息和指标收集模块。
docs/07-service-and-process-management-module-design.md –服务和流程管理设计。
docs/08-device-control-and-reboot-shutdown-safeguards-design.md –GPIO/I2C/摄像头控制和重启/关机保护。
docs/09-logging-observability-and-diagnostics-design.md –日志记录、可观察性和诊断。
docs/10-self-update-mechanism-and-rollback-strategy-design.md –自我更新工作流程和回滚策略。
docs/11-testing-validation-and-sandbox-strategy.md –测试、验证和沙箱/安全策略。
docs/12-deployment-systemd-integration-and-operations-runbook.md –部署方法、系统集成和操作手册。
docs/13-python-development-standards-and-tools.md Python编码标准、工具(uv, ruff, pytest, tox、覆盖范围， mypy)以及dev命令。
docs/14-configuration-reference-and-examples.md –中央配置参考(AppConfig 结构、层和示例）。

导航和规划文件

docs/getting-started.md –安装和快速入门指南
docs/operations-runbook.md –日常操作程序
docs/troubleshooting.md –常见问题和解决方案
docs/cloudflare-tunnel-setup.md –安全的互联网接入设置
docs/00-executive-summary.md –2页高管概述（阅读5-7分钟）
docs/quick-start-guide.md –10分钟后开始（所有角色）
docs/document-navigator.md –读取路径、依赖关系、参考矩阵
docs/phase-1-scope-matrix.md –完成第一阶段实施计划（人工智能优化）
**** –GitHub Copilot Agent问题细分（12个完整的问题，包括标题、描述和自定义提示，针对6小时的会话进行了优化）
**** –快速参考：所有12个问题标题和依赖关系
docs/test-matrix.md –设备/环境/功能测试覆盖矩阵
docs/acceptance-checklist.md –预发布验证检查表

文档结构

📚 Documentation Layer Structure
├── 🎯 Entry Points (Start Here!)
│   ├── 00-executive-summary.md      ← Overview for everyone (5 min)
│   ├── quick-start-guide.md         ← Get oriented fast (10 min)
│   └── document-navigator.md        ← Find what you need
│
├── 📋 Planning & Scope
│   └── phase-1-scope-matrix.md      ← AI implementation guide (PRIMARY for builders)
│
├── 🏗️ Foundation (Read First)
│   ├── 01-requirements-specification.md
│   ├── 02-architecture-design.md
│   └── 03-platform-constraints.md
│
├── 🔐 Core Design
│   ├── 04-security-oauth-access-control.md
│   └── 05-tools-interface-json-schema.md
│
├── 🔧 Module Designs (Implementation Details)
│   ├── 06-system-information-metrics.md
│   ├── 07-service-process-management.md
│   ├── 08-device-control-safeguards.md
│   ├── 09-logging-observability-diagnostics.md
│   └── 10-self-update-rollback-strategy.md
│
├── 🚀 Implementation & Operations
│   ├── 11-testing-validation-sandbox.md
│   ├── 12-deployment-systemd-operations.md
│   ├── 13-python-development-standards.md
│   └── 14-configuration-reference-examples.md
│
└── ✅ Validation
    ├── test-matrix.md
    └── acceptance-checklist.md

总计：24个文档文件，250多页，10-12小时的综合研究，实施就绪的规范。

文档的质量：专业级，综合规格，质量等级9.6/10。所有内容都经过整合，便于导航，术语一致，交叉引用准确，细节易于实施。

部署文件

这 deployment/ 目录包含生产就绪部署工件：

deployment/
├── systemd/
│   ├── mcp-raspi-server.service    # MCP server systemd unit
│   └── raspi-ops-agent.service     # Privileged agent systemd unit
├── install.sh                       # Automated installation script
├── uninstall.sh                     # Clean uninstallation script
└── config.example.yml               # Configuration template

系统化服务

两种服务协同工作：

mcp raspi服务器：处理客户端请求的非特权MCP服务器
raspi行动特工：硬件/OS操作的特权代理

安装脚本

# Preview installation (dry run)
sudo ./deployment/install.sh --dry-run

# Install with defaults
sudo ./deployment/install.sh

# Install specific version
sudo ./deployment/install.sh --version 1.0.0

卸载

# Standard uninstall
sudo ./deployment/uninstall.sh

# Keep configuration
sudo ./deployment/uninstall.sh --keep-config

# Complete removal
sudo ./deployment/uninstall.sh --purge

此存储库包含 文件编制和实施；所有核心MCP服务器功能、特权代理、systemd单元和部署脚本都已准备就绪。

人工智能辅助开发

该项目旨在 AI优先的开发工作流程 人工智能助手（如Claude、GitHub Copilot、GPT-4等）在人工监督下基于全面的设计文档实现功能。

与传统发展的主要区别:

工作量估算 针对AI编码速度进行了校准（总共4-6周，而传统为3-4个月）
文档是人工智能优化的 有明确的参考、模式和指导方针
范围矩阵 帮助人工智能理解边界和依赖关系
人的角色：审查代码，测试硬件，提供反馈，批准设计

AI助手：从以下内容开始 docs/phase-1-scope-matrix.md 其中包含如何有效使用这些设计文档的具体说明。

对于GitHub Copilot代理：参见将第1阶段完全分解为12个GitHub Issues，针对6小时的Copilot Agent会话进行了优化。每个问题都包括验收标准、设计文档参考、实施说明和时间细分。

高层设计总结

根据文档集，MCP服务器的设计如下：

非特权MCP服务器进程(mcp-raspi-server)在Raspberry Pi操作系统上运行，通过JSON-RPC 2.0公开MCP工具。
单独的特权代理人(raspi-ops-agent)其通过Unix域套接字上的受限IPC协议执行硬件和操作系统操作。
分层配置模型(AppConfig)从默认值加载→ YAML → 环境变量(MCP_RASPI_*) → CLI标志，包括服务器、安全、工具、设备控制、日志记录、更新、IPC和测试/沙盒部分。
基于Cloudflare Tunnel+Cloudflare Access/OIDC的安全模型，角色(viewer, operator, admin)，安全级别(read_only, safe_control, admin)，以及每个工具的政策和费率限制。
丰富的工具表面(system.*, metrics.*, service.*, process.*, gpio.*, i2c.*, camera.*, logs.*, manage.*)为参数和结果定义了JSON模式和Pydantic模型。
一个自我更新子系统，管理以下版本的发布 /opt/mcp-raspi/releases/ 带着一个 current 符号链接， version.json 元数据、自动/手动回滚以及与操作系统级APT更新的明确分离。
一种强调TDD、高覆盖率（总体≥85%，关键模块约90%）、危险操作沙箱模式的测试策略(testing.sandbox_mode)，跨设备/环境的测试矩阵，以及发布的验收清单。

计划实施栈和开发流程

实现语言： Python 3.11+ 在Raspberry Pi操作系统上。
核心运行时库（在编码过程中需要改进）：

- 服务器/核心： fastapi, uvicorn, pydantic, pyyaml, pyjwt. - 系统和指标： psutil. - 设备控制： gpiozero, smbus2，可选 spidev, pyserial, picamera2. - 服务/流程管理： dbus-next + systemctl 包装纸。

推荐的开发工具和运行程序： uv （env+run）， pytest, pytest-asyncio, pytest-cov, tox, ruff, mypy.

添加代码和打包文件后，典型的本地流预计为（详见文档13）：

创建virtualenv并安装依赖项：

- uv venv .venv - source .venv/bin/activate - uv pip install -e ".[dev]"

运行测试和检查：

- uv run pytest - uv run pytest --cov=mcp_raspi --cov=mcp_raspi_ops --cov-report=term-missing - uv run ruff check src tests / uv run ruff format src tests

运行开发实例：

- uv run mcp-raspi-server --config ./dev-config.yml - sudo uv run raspi-ops-agent --config ./dev-config.yml

这些命令是设计的一部分，可以在创建初始实现时进行改进，但是 uv + ruff + pytest + tox 是首选的工具链。文档10和12中详细描述了部署、自更新和回滚流程；文档11和13中的测试和CI策略；doc14中的配置结构和示例。

实施准备就绪

该系统的所有主要方面都在实施层面进行了规定：

需求和架构：文件01–03。
安全、工具和模块：文件04-09。
自我更新、测试、部署和Python标准：文档10-13。
配置模型和示例：文档14。
测试计划和验收： docs/test-matrix.md, docs/acceptance-checklist.md.

你现在可以使用脚手架了 pyproject.toml, src/mcp_raspi/, src/mcp_raspi_ops/，并开始实施 AppConfig、日志/审计、JSON-RPC服务器、IPC客户端/代理以及遵循这些规范的每个模块。

Raspberry Pi Os MCP

快速接入

详细介绍