The Goodies is a modern smart home knowledge graph data store layer built around the Model Context Protocol (MCP) architecture. The system provides a unified interface for managing smart home devices, relationships, and automations through a graph-based data model.
Current Status: ✅ Production Ready - All tests passing (225/225), comprehensive MCP functionality, full client-server synchronization, and enterprise-grade security features.
Related Projects: adrianco/consciousness is an early prototype of the backend server that will be rewritten from scratch later. adrianco/c11s-house-ios is a native Swift iOS app that is the front end for the system. This repo is the knowledge graph protocol that will interface the app to the backend, and includes a command line client in Python that acts as a prototype implementation for the next phase, adrianco/the-goodies-swift, which will be integrated with adrianco/c11s-house-ios.
-
🚀 FunkyGibbon (Server) - Python-based backend server
- FastAPI REST API with graph operations
- 12 MCP tools for smart home management
- Entity-relationship knowledge graph
- SQLite database with immutable versioning
- Security: JWT authentication, rate limiting, audit logging
- Access Control: Admin and guest roles with QR code access
-
📱 Blowing-Off (Client) - Python synchronization client
- Real-time sync with server
- Local graph operations and caching
- CLI interface matching server functionality
- Conflict resolution and offline queue
-
🛠️ Oook (CLI) - Development and testing CLI
- Direct server MCP tool access
- Graph exploration and debugging
- Database population and management
-
🔗 Inbetweenies (Protocol) - Shared synchronization protocol
- Entity and relationship models
- MCP tool implementations
- Conflict resolution strategies
- Graph operations abstraction
- Python 3.11 or higher
- pip package manager
- curl (for testing authentication)
# Navigate to project root
cd /workspaces/the-goodies
# Run installer for development mode
./install.sh --dev
# Or run installer for production mode (will prompt for password)
./install.sh# Navigate to project root
cd /workspaces/the-goodies
# Set Python path (required)
export PYTHONPATH=/workspaces/the-goodies:$PYTHONPATH
# Install dependencies
cd funkygibbon && pip install -r requirements.txt && cd ..
cd inbetweenies && pip install -e . && cd ..
cd oook && pip install -e . && cd ..
cd blowing-off && pip install -e . && cd ..
# Configure security
export ADMIN_PASSWORD_HASH="" # For dev mode with "admin" password
export JWT_SECRET="development-secret"
# Populate database
cd funkygibbon && python populate_graph_db.py && cd ..# If you used the installer:
./start_funkygibbon.sh
# If you did manual setup:
python -m funkygibbon
# In another terminal, test with Oook CLI
oook stats
oook search "smart"
oook tools# Login as admin (password is "admin" in dev mode)
curl -X POST http://localhost:8000/api/v1/auth/admin/login \
-H "Content-Type: application/json" \
-d '{"password": "admin"}'
# Response will include an access token:
# {
# "access_token": "eyJhbGciOiJIUzI1NiIs...",
# "token_type": "bearer",
# "expires_in": 604800,
# "role": "admin"
# }
# Save the token for API requests
export AUTH_TOKEN="<your-access-token>"
# Test authenticated access
curl http://localhost:8000/api/v1/auth/me \
-H "Authorization: Bearer $AUTH_TOKEN"The system provides 12 Model Context Protocol tools for smart home management:
| Tool | Description | Parameters |
|---|---|---|
get_devices_in_room |
Find all devices in a specific room | room_id |
find_device_controls |
Get controls for a device | device_id |
get_room_connections |
Find connections between rooms | room_id |
search_entities |
Search entities by name/content | query, entity_types, limit |
create_entity |
Create new entity | entity_type, name, content |
create_relationship |
Link entities | from_entity_id, to_entity_id, relationship_type |
find_path |
Find path between entities | from_entity_id, to_entity_id |
get_entity_details |
Get detailed entity info | entity_id |
find_similar_entities |
Find similar entities | entity_id, threshold |
get_procedures_for_device |
Get device procedures | device_id |
get_automations_in_room |
Get room automations | room_id |
update_entity |
Update entity (versioned) | entity_id, changes, user_id |
The knowledge graph supports these entity types:
- HOME - Top-level container
- ROOM - Physical spaces
- DEVICE - Smart devices and appliances
- ZONE - Logical groupings
- DOOR/WINDOW - Connections
- PROCEDURE - Instructions
- MANUAL - Documentation
- NOTE - User annotations (including photo documentation)
- SCHEDULE - Time-based rules
- AUTOMATION - Event-based rules
- APP - Mobile/web applications that control devices
# First, ensure Python path is set (required for finding inbetweenies)
export PYTHONPATH=/workspaces/the-goodies:$PYTHONPATH
# Get an auth token by logging in as admin
curl -X POST http://localhost:8000/api/v1/auth/admin/login \
-H "Content-Type: application/json" \
-d '{"password": "admin"}' | jq -r '.access_token'
# Connect to server with the token
blowing-off connect --server-url http://localhost:8000 --auth-token <your-token> --client-id device-1
# Check status
blowing-off status
# Synchronize with server
blowing-off sync
# Use MCP tools locally
blowing-off tools
blowing-off search "smart"
blowing-off execute get_devices_in_room -a room_id="room-123"The system has comprehensive test coverage:
- Unit Tests: 150+ passing
- Integration Tests: 40+ passing
- Security Tests: 21 passing
- Performance Tests: 10 passing
- E2E Tests: 10 passing
- UGC Tests: 14 passing
- Total: 225 tests passing (60% coverage)
# Run all tests
python -m pytest -v
# Run with coverage
python -m pytest --cov=funkygibbon --cov=blowingoff --cov=inbetweenies --cov-report=term-missing
# Run security tests only
python -m pytest tests/auth/ -vthe-goodies/
├── funkygibbon/ # Server (Python FastAPI)
│ ├── api/ # REST API routes
│ ├── mcp/ # MCP server implementation
│ ├── graph/ # Graph operations
│ ├── repositories/ # Data access layer
│ └── tests/ # Comprehensive test suite
├── blowing-off/ # Client (Python)
│ ├── cli/ # Command line interface
│ ├── sync/ # Synchronization engine
│ ├── graph/ # Local graph operations
│ └── tests/ # Unit and integration tests
├── oook/ # CLI tool (Python)
│ ├── oook/ # CLI implementation
│ └── examples/ # Usage examples
├── inbetweenies/ # Shared protocol (Python)
│ ├── models/ # Entity and relationship models
│ ├── mcp/ # MCP tool implementations
│ └── sync/ # Synchronization protocol
└── plans/ # Documentation and plans
└── archive/ # Archived documentation
- ✅ MCP Protocol Support - 12 standardized tools
- ✅ Graph-based Data Model - Flexible entity relationships
- ✅ Real-time Synchronization - Client-server sync
- ✅ Immutable Versioning - Complete change history
- ✅ Conflict Resolution - Multiple strategies available
- ✅ Search & Discovery - Full-text entity search
- ✅ CLI Interface - Both server and client CLIs
- ✅ Production Ready - 225 tests passing (including 14 UGC tests), 60% coverage
- ✅ User Generated Content - Support for PDFs, photos, and user notes
- ✅ BLOB Storage - Binary data storage with sync capabilities
- ✅ Device-App Integration - Link devices to their control apps
The system supports comprehensive User Generated Content functionality for storing and managing device documentation, photos, and user notes:
- Store mobile/web applications that control smart devices
- Link apps to devices using
CONTROLLED_BY_APPrelationship - Track app metadata (platform, URL scheme, icon, description)
- Binary large object storage for PDFs and photos
- Support for multiple blob types: PDF, JPEG, PNG, and generic binary
- Automatic checksum generation (SHA-256)
- Sync status tracking (pending upload, uploaded, downloaded)
- Metadata storage for structured information
- Free-form text notes with categorization
- Link notes to devices using
DOCUMENTED_BYrelationship - Support for device references within notes
- Photo documentation with blob references
- Store device manuals and instruction books
- Automatic summary generation from PDF content
- Model number extraction from filenames
- Link manuals to specific devices
- Full-text searchable content
- Store installation photos and serial numbers
- Extract metadata from photo files
- Categorize photos by type (serial_number, installation, etc.)
- Link photos to devices with
HAS_BLOBrelationship - Support for JPEG and PNG formats
- Specialized support for Mitsubishi PAR-42MAA thermostats
- Store thermostat capabilities and configuration
- Link to Mitsubishi Comfort mobile app
- Track integration details (WiFi adapter, features)
# Create an APP entity
app = Entity(
entity_type=EntityType.APP,
name="Mitsubishi Comfort",
content={
"platform": "iOS",
"url_scheme": "mitsubishicomfort://",
"description": "Control Mitsubishi HVAC systems"
}
)
# Create a BLOB for PDF storage
pdf_blob = Blob(
name="PAR-42MAAUB_Manual.pdf",
blob_type=BlobType.PDF,
mime_type="application/pdf",
data=pdf_bytes,
blob_metadata={"pages": 50, "model": "PAR-42MAAUB"}
)
# Create a user NOTE with photo references
photo_note = Entity(
entity_type=EntityType.NOTE,
name="Installation Photos",
content={
"content": "Photos from HVAC installation",
"category": "photo_documentation",
"has_blob": True,
"blob_references": ["blob_id_1", "blob_id_2"]
}
)
# Link device to app
relationship = EntityRelationship(
from_entity_id=device.id,
to_entity_id=app.id,
relationship_type=RelationshipType.CONTROLLED_BY_APP,
properties={"integration": "wifi_adapter"}
)- CONTROLLED_BY_APP - Device controlled by mobile/web app
- DOCUMENTED_BY - Entity documented by note or manual
- HAS_BLOB - Entity has associated binary data
The system includes enterprise-grade security features that have been fully implemented and tested:
- ✅ Authentication System - Admin password login with Argon2id hashing
- ✅ JWT Tokens - Secure token-based API access with configurable expiration
- ✅ Rate Limiting - Brute force protection (5 attempts/5 min window)
- ✅ Audit Logging - Comprehensive security event tracking with 15 event types
- ✅ Guest Access - QR code-based temporary read-only access
- ✅ Progressive Delays - Increasing lockout periods (up to 5x) for repeated failures
- ✅ Permission System - Role-based access control (admin/guest)
# For development/testing - uses "admin" as the default password
export ADMIN_PASSWORD_HASH=""
export JWT_SECRET="development-secret"
# Start the server
python -m funkygibbon# Option A: Use the installer (recommended)
./install.sh
# The installer will:
# - Prompt for a secure admin password
# - Generate password hash automatically
# - Create a secure JWT secret
# - Set up start_funkygibbon.sh with your configuration
# Option B: Manual setup
# Step 1: Generate a secure password hash
python -c "from funkygibbon.auth import PasswordManager; pm = PasswordManager(); print(pm.hash_password('YourSecurePassword123!'))"
# Step 2: Set environment variables with generated values
export ADMIN_PASSWORD_HASH="$argon2id$v=19$m=65536,t=2,p=1$..." # Use output from step 1
export JWT_SECRET="$(openssl rand -hex 32)" # Generate secure random string
# Step 3: Start the server
python -m funkygibbon| Variable | Description | Default | Production Recommendation |
|---|---|---|---|
ADMIN_PASSWORD_HASH |
Argon2id hash of admin password | Empty (dev mode) | Required - use strong password |
JWT_SECRET |
Secret key for signing JWT tokens | "development-secret" | Required - use random 32+ chars |
RATE_LIMIT_ATTEMPTS |
Max login attempts per window | 5 | 3-5 recommended |
RATE_LIMIT_WINDOW |
Time window in seconds | 300 (5 min) | 300-900 recommended |
AUDIT_LOG_FILE |
Path to security audit log | "security_audit.log" | Secure location with rotation |
# Login with admin password
curl -X POST http://localhost:8000/api/v1/auth/admin/login \
-H "Content-Type: application/json" \
-d '{"password": "admin"}'
# Save the access token from response
export AUTH_TOKEN="<access-token-from-response>"
# Use token for authenticated requests
curl http://localhost:8000/api/v1/auth/me \
-H "Authorization: Bearer $AUTH_TOKEN"# Generate guest QR code (requires admin token)
curl -X POST http://localhost:8000/api/v1/auth/guest/generate-qr \
-H "Authorization: Bearer $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"duration_hours": 24}'
# Response includes QR code image and guest token- Protection: Prevents brute force attacks on authentication endpoints
- Configuration: 5 attempts allowed per 5-minute window per IP address
- Progressive Delays: Failed attempts result in increasing lockout periods (up to 5x)
- Response: HTTP 429 (Too Many Requests) with Retry-After header
- Automatic Cleanup: Old rate limit entries cleaned up hourly
- Coverage: All authentication attempts, token operations, and permission checks
- Event Types: 15 different security events tracked including:
- Authentication success/failure/lockout
- Token creation/verification/expiration
- Permission grants/denials
- Guest access generation
- Suspicious pattern detection
- Format: Structured JSON logs for easy analysis
- Pattern Detection: Automatic detection of credential stuffing and repeated failures
- Location: Logs written to
security_audit.log(configurable)
- Human Testing Guide - Step-by-step testing
- Architecture Documentation - System design
- API Documentation - REST endpoints
- Phase Summaries - Implementation history
The system is fully functional with:
- 225/225 tests passing (including UGC features)
- Complete MCP tool suite working
- Client-server synchronization operational
- Full human testing scenarios verified
- User Generated Content support (PDFs, photos, notes)
- BLOB storage with sync capabilities
- Zero remaining issues
Ready for deployment and use! 🚀