Benny The Dog

Python FastMCP Ruff uv

Benny the dog health and care monitor - water bowls, movement, loneliness detection, sausage deliveries, projector movie time, wake calls. Boomy-robot patrol integration ready.

Fleet-standard fullstack app: FastMCP 3.4 backend, React + Vite + Tailwind frontend, Bun, optional Tauri 2.0 desktop wrapper.

Quick start

uv sync
bun --prefix webapp install
.\start.ps1          # clears ports, starts backend + frontend, opens browser

• Backend API + Swagger: http://127.0.0.1:11142/docs
• Frontend: http://127.0.0.1:11143
• MCP endpoint (when enabled): http://127.0.0.1:11142/mcp

What it does

• Care events: log water refills, barks, movement, sausage deliveries, projector movie time, and wake calls via the dog_ops MCP tool.
• Loneliness detection: the 5-minute patrol job (APScheduler) flags barks with no subsequent movement and suggests a sausage delivery.
• Dog profile: 6-step onboarding wizard (bio, photos, vet & health, behaviour, walking, dogparks/fountains).
• Webapp: Dashboard, Tools, Skills, Chat (local LLM), Vet & Health, Settings, Help, Logs, ApiDocs, Jobs, Dog Partners, Shop, Cart, Onboarding.
• Robot-ready: actor="boomy" on every event for the Boomy robot patrol.

Tools

Tool	Description
dog_ops	Care portmanteau: status, water_refill, bark_event, movement, sausage_delivery, movie_time, wake
app_info	Server metadata (name, version, tool count)
server_shutdown	Graceful shutdown (confirm=True required)

Full reference: docs/TOOLS.md | llms-full.txt

Claude Desktop config

{
  "mcpServers": {
    "benny": {
      "command": "uv",
      "args": ["run", "--directory", "D:/Dev/repos/benny-the-dog-mcp", "python", "-m", "benny_the_dog_mcp.server"]
    }
  }
}

Environment

Copy .env.example to .env. See docs/CONFIGURATION.md for the full table.

Variable	Default	Purpose
WEB_PORT	11142	Backend port
OLLAMA_URL	http://127.0.0.1:11434	Chat LLM endpoint
ENABLE_SCHEDULER	1	Patrol job (5 min)

Ports

Registered in the fleet reservoir: backend 11142, frontend 11143 (see mcp-central-docs/operations/WEBAPP_PORTS.md).

Tests

uv run pytest tests/        # backend (73% coverage)
bun --prefix webapp run e2e # Playwright

Documentation

• docs/CONFIGURATION.md — env vars, ports, storage
• docs/DEVELOPMENT.md — stack, layout, commands, gates
• docs/TOOLS.md — MCP tools + REST API reference
• docs/TROUBLESHOOTING.md — common issues
• docs/ONBOARDING.md — dog onboarding wizard
• llms.txt / llms-full.txt — LLM reference
• CHANGELOG.md