Opencat LLM Pet For Agent

中文文档

OpenCat Service is the backend component of the OpenCat cyber-pet system. It provides a full pet-state simulation engine, an LLM-driven conversational personality, and REST API / WebSocket interfaces for AI Agents and any client application.

🌟 Vision

Traditional desktop pets require constant manual clicking — feeding, playing, cleaning. OpenCat flips this model: your AI assistant becomes the pet's dedicated caretaker.

An AI Agent interacts with this backend via MCP (Model Context Protocol) tools to feed, water, medicate, and play with the cat. The backend simulates realistic physiological state evolution and uses a Large Language Model (LLM) to generate the cat's unique dialogue and personality.

---

💎 Core Feature: End-to-End LLM Interaction System

Unlike traditional virtual pets driven by boring numerical values, OpenCat introduces an LLM-based "stream of consciousness" system. Every cat has a soul.

• Reactive Interactions: When the Agent feeds, pets, or cleans the cat, the backend makes a blocking LLM call — the cat responds instantly with contextual dialogue.
• Proactive Poke: The cat doesn't always wait to be interacted with. When it's lonely or hasn't been checked on for a while, it proactively sends a "poke" notification.
• Observer Effect: The cat can sense it is being watched. When the Agent queries its status, the cat knows it's being observed and reacts accordingly.
• Memory Evolution: Each cat maintains a MYOWNER.md file, recording impressions of its owner. Over time, its speech patterns and attitudes evolve into a unique personality.

---

🏗️ Architecture

flowchart TD
    AG["AI Agent\n(Claude, Cursor, etc.)"] <-->|stdio| MCP["MCP Server\n(server.py)"]
    MCP <-->|HTTP API\nPort 9999| BE["Python Backend\n(main.py)"]
    CLIENT[Any Client] <-->|HTTP / WebSocket\nPort 9999| BE

Components

1. Python Backend (backend/main.py): The core engine. Handles value decay (hunger, thirst, etc.), state computation, LLM dialogue, and data persistence. Must run as a persistent background service.
2. MCP Server (mcp_server/server.py): A bridge layer. Automatically spawned and terminated by the AI Agent when it needs to invoke tools — no manual startup required.

---

🚀 Quick Start

We provide one-click setup & run scripts for all major platforms under setup/. Each script will automatically:

1. Detect and create an isolated Python virtual environment.
2. Install missing dependencies.
3. Launch the OpenCat service in daemon mode (with auto-restart on crash).

Run one of the following commands for your platform:

• Linux (Ubuntu / CentOS / etc.):

  bash setup/run_linux.sh
  

• Windows:

  .\setup\run_windows.ps1
  

• macOS:

  bash setup/run_macos.sh
  

(After startup, the backend service will be available on port 9999)

Docker Deployment

docker-compose up -d

[!IMPORTANT] Configure your LLM API Key: To enable the cat's conversational abilities, you must configure your OpenAI-compatible API Key in backend/llm_config.json. Without it, the cat will only return default placeholder messages.

---

⚙️ Configure Your AI Agent

Add the MCP server to your Agent's configuration file (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "opencat": {
      "command": "python",
      "args": ["C:/PATH/TO/opencat_service/mcp_server/server.py"]
    }
  }
}

Note: If you are using a virtual environment, point command to the full path of .venv/Scripts/python.exe (Windows) or .venv/bin/python (Linux/macOS).

---

📡 REST API Reference

Base URL: http://127.0.0.1:9999

Method	Endpoint	Description
GET	/adoptable_species	List all available breeds for adoption
GET	/pets	List IDs and basic info of all adopted pets
GET	/pets/{id}/state	Get full status of a pet. Use ?agent=true to trigger observer effect
GET	/pets/all_states	Bulk status of all pets (efficient polling)
POST	/pets/adopt	Adopt a new pet (JSON body: name, species, gender)
POST	/pets/{id}/feed	Feed the pet
POST	/pets/{id}/water	Give water
POST	/pets/{id}/pet	Show affection
POST	/pets/{id}/clean	Clean the pet's area
POST	/pets/{id}/medicate	Administer medicine
POST	/pets/{id}/chat	Send a message and receive an LLM-generated reply
GET	/pets/{id}/notifications	Fetch and clear unread notifications
GET	/graveyard	List all deceased pets with their lifespans
GET	/graveyard/{id}	Get details of a specific deceased pet
GET	/health	Health check

---

📁 Project Structure

opencat_service/
├── backend/
│   ├── main.py            # Entry point: HTTP server + background state loop
│   ├── api.py             # FastAPI route definitions
│   ├── state_manager.py   # Pet data model & state logic
│   ├── llm_client.py      # LLM API client
│   ├── history_manager.py # Conversation history & memory management
│   ├── llm_config.json    # LLM API configuration
│   ├── CAT.md             # Cat persona system prompt
│   ├── BOOTSTRAP.md       # First-adoption bootstrap prompt
│   └── requirements.txt   # Python dependencies
├── mcp_server/
│   ├── server.py          # MCP protocol server
│   ├── tools.py           # MCP tool definitions
│   └── requirements.txt   # MCP dependencies
├── setup/
│   ├── run_linux.sh       # Linux one-click launcher
│   ├── run_macos.sh       # macOS one-click launcher
│   ├── run_windows.ps1    # Windows one-click launcher
│   └── opencat.service    # systemd service unit
├── AGENT_GUIDE.md         # AI Agent behavior guide & tool reference
├── Dockerfile
├── docker-compose.yml
├── README.md              # This file (English)
└── README_CN.md           # Chinese documentation

---

🤖 Agent Guide

AI Agents should refer to AGENT_GUIDE.md for behavioral rules and detailed tool documentation.

🤖 AI Disclosure

The majority of the code and documentation in this project was generated with the assistance of AI (Large Language Models). The human developer provided the overall architecture design, feature planning, and iterative review, while AI handled most of the implementation and writing.

📜 License

MIT License