Smart Home Knowledge Graph MCP Development

A comprehensive development skill for The Goodies - a smart home knowledge graph system implementing the Model Context Protocol (MCP) with Python backend (FunkyGibbon), Swift iOS client (Blowing-off), shared protocol (Inbetweenies), and CLI tools (Oook).

What This Skill Does

This skill guides AI agents through development of a distributed MCP-based smart home system with:

Critical Rules: Concurrent Execution & File Management

ABSOLUTE REQUIREMENTS

1. **ALL operations MUST be concurrent/parallel in a single message**

2. **NEVER save working files, text/markdown, and tests to the root folder**

3. **ALWAYS organize files in appropriate subdirectories**

4. **USE CLAUDE CODE'S TASK TOOL for spawning agents concurrently**

Golden Rule: "1 MESSAGE = ALL RELATED OPERATIONS"

**Mandatory batching patterns:**

File Organization

**NEVER save to root. Use these directories:**

**Project-specific directories:**

Architecture Overview

Component Responsibilities

**FunkyGibbon (Server)**

**Blowing-off (Client)**

**Inbetweenies (Shared Protocol)**

**Oook (CLI Tool)**

Data Models

**Entity Types**: HOME, ROOM, DEVICE, ZONE, DOOR, WINDOW, PROCEDURE, MANUAL, NOTE, SCHEDULE, AUTOMATION, APP

**Relationships**: CONTAINS, CONNECTED_TO, CONTROLLED_BY, CONTROLLED_BY_APP, DOCUMENTED_BY, HAS_BLOB

**Features**: Immutable versioning, complete change history, binary blob storage

Development Workflow

Step 1: Setup and Installation

```bash

Quick setup (recommended)

Task("Setup environment", "Run ./install.sh --dev and verify PYTHONPATH configuration", "bash")

Manual setup

Task("Configure Python path", "Export PYTHONPATH=/workspaces/the-goodies:$PYTHONPATH", "bash")

```

Step 2: Start Development Server

```bash

Spawn server in background

Task("Start FunkyGibbon", "Run python -m funkygibbon with dev credentials (ADMIN_PASSWORD_HASH='', JWT_SECRET='development-secret')", "bash")

Or use installer script

Task("Launch server", "Execute ./start_funkygibbon.sh", "bash")

```

Step 3: Run Tests

```bash

Execute all test suites concurrently

[Single Message]:

Task("Run unit tests", "Execute pytest -v for all test files", "tester")

Task("Run integration tests", "Execute pytest -m integration -v", "tester")

Task("Generate coverage", "Run pytest --cov=funkygibbon --cov=blowingoff --cov=inbetweenies --cov-report=term-missing", "tester")

Task("Run security tests", "Execute pytest tests/auth/ -v", "tester")

```

Step 4: Code Quality

```bash

Batch all quality checks

[Single Message]:

Task("Format code", "Run black on all Python modules", "bash")

Task("Lint code", "Execute flake8 on all source directories", "bash")

Task("Type check", "Run mypy funkygibbon/ --ignore-missing-imports", "bash")

```

SPARC Methodology Integration

Complete TDD Workflow

```bash

Run full SPARC pipeline for new feature

Task("SPARC TDD", "Execute npx claude-flow sparc tdd 'Add device automation triggers'", "sparc-coord")

```

Individual SPARC Phases

```bash

Batch SPARC mode execution

[Single Message]:

Task("Specification", "Run sparc run spec-pseudocode for requirements", "specification")

Task("Architecture", "Execute sparc run architect for system design", "architecture")

Task("Refinement", "Run sparc tdd for TDD implementation", "refinement")

```

SPARC Commands Reference

Agent Orchestration

Claude Code Task Tool: Primary Execution Engine

Claude Code's Task tool spawns agents that perform actual work. MCP tools ONLY coordinate strategy.

**Correct pattern:**

```javascript

// Single message spawning all agents concurrently

[Parallel Agent Execution]:

Task("Backend Developer", "Implement FastAPI endpoints with JWT auth. Use hooks for coordination.", "backend-dev")

Task("Database Architect", "Design graph schema with versioning. Store schema in memory.", "code-analyzer")

Task("Test Engineer", "Write pytest tests with 90% coverage. Check memory for API contracts.", "tester")

Task("API Documentation", "Generate OpenAPI specs. Document in /docs/api/.", "api-docs")

Task("Security Reviewer", "Audit authentication flow. Report findings via hooks.", "reviewer")

// Batch all todos together

TodoWrite { todos: [

{content: "Implement REST endpoints", status: "in_progress", activeForm: "Implementing REST endpoints"},

{content: "Design database schema", status: "pending", activeForm: "Designing database schema"},

{content: "Write integration tests", status: "pending", activeForm: "Writing integration tests"},

{content: "Generate API documentation", status: "pending", activeForm: "Generating API documentation"},

{content: "Security audit", status: "pending", activeForm: "Performing security audit"}

]}

```

Available Agents (54 Total)

**Core Development**: coder, reviewer, tester, planner, researcher

**Swarm Coordination**: hierarchical-coordinator, mesh-coordinator, adaptive-coordinator, collective-intelligence-coordinator

**Performance**: perf-analyzer, performance-benchmarker, task-orchestrator, memory-coordinator

**GitHub**: github-modes, pr-manager, code-review-swarm, issue-tracker, release-manager

**SPARC**: sparc-coord, sparc-coder, specification, pseudocode, architecture, refinement

**Specialized**: backend-dev, mobile-dev, ml-developer, cicd-engineer, api-docs, system-architect

**Testing**: tdd-london-swarm, production-validator

Agent Coordination Protocol

**Every agent spawned via Task tool MUST execute hooks:**

```bash

BEFORE work

npx claude-flow@alpha hooks pre-task --description "[task description]"

npx claude-flow@alpha hooks session-restore --session-id "swarm-[id]"

DURING work

npx claude-flow@alpha hooks post-edit --file "[filepath]" --memory-key "swarm/[agent]/[step]"

npx claude-flow@alpha hooks notify --message "[progress update]"

AFTER work

npx claude-flow@alpha hooks post-task --task-id "[task-id]"

npx claude-flow@alpha hooks session-end --export-metrics true

```

MCP Tool Integration

Setup MCP Servers

```bash

Required: Claude Flow for SPARC

claude mcp add claude-flow npx claude-flow@alpha mcp start

Optional: Enhanced coordination

claude mcp add ruv-swarm npx ruv-swarm mcp start

Optional: Cloud features (70+ tools)

claude mcp add flow-nexus npx flow-nexus@latest mcp start

```

MCP Tool Categories

**Coordination** (MCP tools): swarm_init, agent_spawn, task_orchestrate

**Execution** (Claude Code Task tool): Spawn actual working agents

**Monitoring**: swarm_status, agent_list, agent_metrics, task_status

**Memory & Neural**: memory_usage, neural_status, neural_train, neural_patterns

**GitHub Integration**: github_swarm, repo_analyze, pr_enhance, issue_triage

Claude Code vs MCP Tools

**Claude Code Handles ALL EXECUTION:**

**MCP Tools ONLY COORDINATE:**

Database Operations

Populate Test Data

```bash

Task("Seed database", "Execute cd funkygibbon && python populate_graph_db.py && cd ..", "bash")

```

Database Schema

**Main tables:**

**Database file**: `funkygibbon.db` (SQLite)

Authentication Flow

1. **Admin login**: POST to `/api/v1/auth/admin/login` with password

2. **Receive JWT**: Token valid for 7 days

3. **Authorization**: Include `Bearer <token>` in header

4. **Guest access**: QR codes for temporary read-only access

Get Auth Token

```bash

Task("Obtain token", "curl -X POST http://localhost:8000/api/v1/auth/admin/login -H 'Content-Type: application/json' -d '{\"password\": \"admin\"}' | jq -r '.access_token'", "bash")

```

CLI Tools Usage

Oook (Direct Server Access)

```bash

[Single Message - All Oook Operations]:

Task("Get stats", "oook stats", "bash")

Task("Search entities", "oook search 'smart'", "bash")

Task("List tools", "oook tools", "bash")

Task("Execute tool", "oook execute get_devices_in_room -a room_id='room-123'", "bash")

```

Blowing-off Client (Requires Auth)

```bash

[Single Message - Client Operations]:

Task("Connect client", "blowing-off connect --server-url http://localhost:8000 --auth-token <token> --client-id device-1", "bash")

Task("Sync data", "blowing-off sync", "bash")

Task("Search local", "blowing-off search 'smart'", "bash")

```

Best Practices

Code Style

Concurrent Development Pattern

```javascript

// ✅ CORRECT: Full-stack feature in single message

[Single Message - Complete Feature]:

// Spawn all agents

Task("Backend API", "Implement /api/v1/devices endpoint with JWT auth", "backend-dev")

Task("Database Schema", "Add device_metadata table with versioning", "code-analyzer")

Task("Client Sync", "Update blowing-off sync protocol for devices", "coder")

Task("Integration Tests", "Write pytest tests for device CRUD operations", "tester")

Task("CLI Commands", "Add oook device commands", "coder")

// Batch all file operations

Write "/funkygibbon/api/devices.py"

Write "/funkygibbon/models/device.py"

Write "/blowing-off/sync/devices.py"

Write "/tests/test_devices.py"

Write "/oook/commands/device.py"

// Batch all todos

TodoWrite { todos: [...7-10 todos...] }

```

Anti-Patterns to Avoid

❌ **WRONG**: Sequential agent spawning

```javascript

Task("Backend", "...") // Message 1

// Wait for completion

Task("Frontend", "...") // Message 2

```

❌ **WRONG**: Saving to root folder

```javascript

Write "/test.py" // Should be /tests/test_feature.py

Write "/README.md" // Should be /docs/feature.md

```

❌ **WRONG**: Individual todo updates

```javascript

TodoWrite { todos: [{...}] } // Message 1

TodoWrite { todos: [{...}] } // Message 2

```

Example Workflows

Adding New MCP Tool

```javascript

[Single Message - New MCP Tool]:

// Spawn agents

Task("Define tool", "Add tool definition to inbetweenies/mcp/tools.py", "coder")

Task("Implement server", "Add implementation to funkygibbon/mcp_server.py", "backend-dev")

Task("Implement client", "Add to blowing-off/mcp_client.py", "coder")

Task("Add CLI command", "Create oook command wrapper", "coder")

Task("Write tests", "Create pytest tests for all implementations", "tester")

Task("Update docs", "Document tool in /docs/mcp-tools.md", "api-docs")

// File operations

Edit "inbetweenies/mcp/tools.py"

Edit "funkygibbon/mcp_server.py"

Edit "blowing-off/mcp_client.py"

Write "/oook/commands/new_tool.py"

Write "/tests/test_new_tool.py"

Write "/docs/mcp-tools/new-tool.md"

// Todos

TodoWrite { todos: [

{content: "Define MCP tool schema", status: "in_progress", activeForm: "Defining MCP tool schema"},

{content: "Implement server endpoint", status: "pending", activeForm: "Implementing server endpoint"},

{content: "Implement client handler", status: "pending", activeForm: "Implementing client handler"},

{content: "Create CLI wrapper", status: "pending", activeForm: "Creating CLI wrapper"},

{content: "Write integration tests", status: "pending", activeForm: "Writing integration tests"},

{content: "Update documentation", status: "pending", activeForm: "Updating documentation"}

]}

```

Running SPARC TDD Workflow

```javascript

[Single Message - SPARC TDD]:

// Initialize SPARC pipeline

Task("SPARC Coordinator", "Execute npx claude-flow sparc tdd 'Add room-to-room automation triggers with conflict detection'", "sparc-coord")

// Setup todos for tracking

TodoWrite { todos: [

{content: "Specification phase", status: "in_progress", activeForm: "Running specification phase"},

{content: "Pseudocode design", status: "pending", activeForm: "Designing pseudocode"},

{content: "Architecture planning", status: "pending", activeForm: "Planning architecture"},

{content: "TDD implementation", status: "pending", activeForm: "Implementing with TDD"},

{content: "Integration completion", status: "pending", activeForm: "Completing integration"}

]}

```

Constraints and Important Notes

1. **Python Path**: Always ensure `PYTHONPATH` includes project root

2. **Development Mode**: Use empty `ADMIN_PASSWORD_HASH` for "admin" password

3. **Database**: SQLite file at `funkygibbon.db` in project root

4. **Ports**: FunkyGibbon runs on port 8000 by default

5. **JWT Secret**: Use `development-secret` for local development

6. **File Organization**: Strictly enforce subdirectory structure

7. **Concurrency**: Always batch related operations in single messages

8. **Agent Hooks**: Every spawned agent must execute coordination hooks

9. **Testing**: Minimum 90% code coverage for new features

10. **Documentation**: Update `/docs` for all architectural changes