chibi-mcp 0.1.1__tar.gz

chibi_mcp-0.1.1/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+.venv/
+env/
+.env
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

chibi_mcp-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 soccz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chibi_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: chibi-mcp
+Version: 0.1.1
+Summary: MCP server for tteoki — a Korean rice cake desktop character that visualizes Claude Code session state
+Project-URL: Homepage, https://github.com/soccz/chibi-mcp
+Project-URL: Repository, https://github.com/soccz/chibi-mcp
+Project-URL: Issues, https://github.com/soccz/chibi-mcp/issues
+Project-URL: Release Notes, https://github.com/soccz/chibi-mcp/releases
+Author: soccz
+License: MIT
+License-File: LICENSE
+Keywords: claude-code,desktop-pet,garaetteok,korean,mcp,tteoki
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=3.2.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: websockets>=14.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# chibi-mcp (server)
+
+MCP server for **tteoki** — a Korean rice cake (가래떡) desktop character that visualizes Claude Code session state.
+
+The server has two jobs running together in one process:
+1. **MCP server (stdio)** — Claude Code / Codex calls these tools to interact with tteoki.
+2. **WebSocket server (`ws://127.0.0.1:9876`)** — pushes state snapshots and events to the desktop app.
+
+## Install
+
+```bash
+pip install chibi-mcp
+```
+
+(For local development from this repo, see "Develop" below.)
+
+## Register with Claude Code
+
+```bash
+claude mcp add chibi -- chibi-mcp
+```
+
+Then launch the chibi-desktop app — it connects to the WebSocket and renders tteoki.
+
+## MCP tools
+
+| Tool | Description |
+|---|---|
+| `get_pet_state` | Returns mood, system metrics (CPU/RAM/battery), counters, timing. Counts as a Claude interaction (may trigger a slice every N calls). |
+| `pet_say(text)` | Make tteoki say something in a speech bubble. |
+| `slice_now` | Force a slice (resets the lengthen cycle, fires a slice event). |
+| `set_slice_interval(n)` | Change how often (every N Claude tool calls) the auto-slice fires. Default: 10. |
+
+## WebSocket protocol (server → desktop)
+
+JSON messages broadcast to all connected desktop clients:
+
+```jsonc
+{ "type": "state",
+  "payload": {
+    "mood": "calm | panting | drowsy | lonely | happy | surprised | joyful",
+    "system": { "cpu_percent": 12.3, "ram_percent": 51.2, "battery_percent": 84.0, "battery_plugged": false },
+    "counters": { "calls_total": 23, "calls_since_slice": 3, "slice_interval": 10, "slices_today": 2 },
+    "timing": { "session_seconds": 1842, "idle_seconds": 7 }
+  }
+}
+
+{ "type": "say", "text": "오늘도 같이 코딩!" }
+
+{ "type": "slice" }
+```
+
+State is pushed every 2 seconds. `say` and `slice` are pushed on demand.
+
+## Environment variables
+
+| Var | Default | Purpose |
+|---|---|---|
+| `CHIBI_WS_HOST` | `127.0.0.1` | WebSocket bind host |
+| `CHIBI_WS_PORT` | `9876` | WebSocket bind port |
+| `CHIBI_LOG_LEVEL` | `INFO` | Logging level |
+
+## Develop
+
+```bash
+cd server
+python3.12 -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Run directly (without Claude Code) for the WebSocket side only:
+
+```bash
+CHIBI_LOG_LEVEL=DEBUG python -m chibi_mcp
+```
+
+The stdio MCP side will wait for a client on stdin/stdout, so to test the WebSocket alone, connect a simple ws client to `ws://localhost:9876` while the process runs.
+
+## Design notes
+
+- **Counter resets only when the process restarts** — intentional "today's-work" scope.
+- **All metrics are local** — no network calls, no telemetry, no accounts.
+- **Slice trigger is Claude-call-based** (not wall-clock) — measures actual work, not just time sitting.
+
+See `../SPEC.md` and `../CHARACTER_DESIGN.md` for the broader project context.

chibi_mcp-0.1.1/README.md

@@ -0,0 +1,87 @@
+# chibi-mcp (server)
+
+MCP server for **tteoki** — a Korean rice cake (가래떡) desktop character that visualizes Claude Code session state.
+
+The server has two jobs running together in one process:
+1. **MCP server (stdio)** — Claude Code / Codex calls these tools to interact with tteoki.
+2. **WebSocket server (`ws://127.0.0.1:9876`)** — pushes state snapshots and events to the desktop app.
+
+## Install
+
+```bash
+pip install chibi-mcp
+```
+
+(For local development from this repo, see "Develop" below.)
+
+## Register with Claude Code
+
+```bash
+claude mcp add chibi -- chibi-mcp
+```
+
+Then launch the chibi-desktop app — it connects to the WebSocket and renders tteoki.
+
+## MCP tools
+
+| Tool | Description |
+|---|---|
+| `get_pet_state` | Returns mood, system metrics (CPU/RAM/battery), counters, timing. Counts as a Claude interaction (may trigger a slice every N calls). |
+| `pet_say(text)` | Make tteoki say something in a speech bubble. |
+| `slice_now` | Force a slice (resets the lengthen cycle, fires a slice event). |
+| `set_slice_interval(n)` | Change how often (every N Claude tool calls) the auto-slice fires. Default: 10. |
+
+## WebSocket protocol (server → desktop)
+
+JSON messages broadcast to all connected desktop clients:
+
+```jsonc
+{ "type": "state",
+  "payload": {
+    "mood": "calm | panting | drowsy | lonely | happy | surprised | joyful",
+    "system": { "cpu_percent": 12.3, "ram_percent": 51.2, "battery_percent": 84.0, "battery_plugged": false },
+    "counters": { "calls_total": 23, "calls_since_slice": 3, "slice_interval": 10, "slices_today": 2 },
+    "timing": { "session_seconds": 1842, "idle_seconds": 7 }
+  }
+}
+
+{ "type": "say", "text": "오늘도 같이 코딩!" }
+
+{ "type": "slice" }
+```
+
+State is pushed every 2 seconds. `say` and `slice` are pushed on demand.
+
+## Environment variables
+
+| Var | Default | Purpose |
+|---|---|---|
+| `CHIBI_WS_HOST` | `127.0.0.1` | WebSocket bind host |
+| `CHIBI_WS_PORT` | `9876` | WebSocket bind port |
+| `CHIBI_LOG_LEVEL` | `INFO` | Logging level |
+
+## Develop
+
+```bash
+cd server
+python3.12 -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Run directly (without Claude Code) for the WebSocket side only:
+
+```bash
+CHIBI_LOG_LEVEL=DEBUG python -m chibi_mcp
+```
+
+The stdio MCP side will wait for a client on stdin/stdout, so to test the WebSocket alone, connect a simple ws client to `ws://localhost:9876` while the process runs.
+
+## Design notes
+
+- **Counter resets only when the process restarts** — intentional "today's-work" scope.
+- **All metrics are local** — no network calls, no telemetry, no accounts.
+- **Slice trigger is Claude-call-based** (not wall-clock) — measures actual work, not just time sitting.
+
+See `../SPEC.md` and `../CHARACTER_DESIGN.md` for the broader project context.

chibi_mcp-0.1.1/chibi_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""chibi-mcp — tteoki desktop character MCP server."""
+
+__version__ = "0.1.0"

chibi_mcp-0.1.1/chibi_mcp/__main__.py

@@ -0,0 +1,91 @@
+"""chibi-mcp entry point.
+
+Runs the FastMCP server (stdio transport for Claude Code) AND a localhost
+WebSocket server (for the desktop app) in the same asyncio loop.
+
+Install:
+    pip install chibi-mcp
+
+Register with Claude Code:
+    claude mcp add chibi -- chibi-mcp
+
+Then launch the chibi-desktop app, which will connect to ws://localhost:9876.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import sys
+from contextlib import suppress
+
+from .server import mcp
+from .ws_server import DEFAULT_WS_HOST, DEFAULT_WS_PORT, run_ws_server
+
+
+def _setup_logging() -> None:
+    level_name = os.environ.get("CHIBI_LOG_LEVEL", "INFO").upper()
+    level = getattr(logging, level_name, logging.INFO)
+    # Log to stderr — stdout is reserved for MCP stdio transport
+    logging.basicConfig(
+        level=level,
+        stream=sys.stderr,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+
+async def _run_concurrent() -> None:
+    """Run MCP (stdio) and WebSocket server concurrently."""
+    host = os.environ.get("CHIBI_WS_HOST", DEFAULT_WS_HOST)
+    port = int(os.environ.get("CHIBI_WS_PORT", DEFAULT_WS_PORT))
+
+    ws_task = asyncio.create_task(run_ws_server(host=host, port=port))
+    # FastMCP's run_stdio_async is the asyncio variant of mcp.run()
+    mcp_task = asyncio.create_task(mcp.run_stdio_async())
+
+    # Graceful shutdown on SIGTERM/SIGINT
+    loop = asyncio.get_running_loop()
+    stop = loop.create_future()
+
+    def _signal_stop() -> None:
+        if not stop.done():
+            stop.set_result(None)
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        with suppress(NotImplementedError):
+            loop.add_signal_handler(sig, _signal_stop)
+
+    try:
+        # Wait for any of: MCP exit, WS exit, signal
+        done, _pending = await asyncio.wait(
+            {mcp_task, ws_task, stop},
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+        for t in done:
+            exc = t.exception() if not t.cancelled() else None
+            if exc:
+                logging.getLogger(__name__).error("task failed: %r", exc)
+    finally:
+        for t in (mcp_task, ws_task):
+            if not t.done():
+                t.cancel()
+        with suppress(asyncio.CancelledError):
+            await asyncio.gather(mcp_task, ws_task, return_exceptions=True)
+
+
+def main() -> int:
+    _setup_logging()
+    log = logging.getLogger("chibi_mcp")
+    log.info("chibi-mcp starting (stdio MCP + ws://%s:%d)",
+             os.environ.get("CHIBI_WS_HOST", DEFAULT_WS_HOST),
+             int(os.environ.get("CHIBI_WS_PORT", DEFAULT_WS_PORT)))
+    with suppress(KeyboardInterrupt):
+        asyncio.run(_run_concurrent())
+    log.info("chibi-mcp stopped")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

chibi_mcp-0.1.1/chibi_mcp/server.py

@@ -0,0 +1,134 @@
+"""FastMCP server — tools Claude Code calls to interact with tteoki."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from fastmcp import FastMCP
+
+from .state import get_state
+from .ws_server import get_broadcaster
+
+log = logging.getLogger(__name__)
+
+mcp = FastMCP("chibi-mcp")
+
+
+# Limits for incoming MCP tool inputs. Claude may emit large strings — we
+# defend the desktop UI from rendering pathological payloads.
+MAX_SAY_LEN = 200
+SAY_CONTROL_CHARS = "".join(chr(c) for c in range(32) if c not in (9, 10))  # keep tab+LF
+
+# Holds references to fire-and-forget asyncio tasks so they aren't garbage
+# collected mid-flight. (RUF006 — Python may drop tasks that have no strong
+# reference, silently dropping the WebSocket broadcast.)
+_PENDING_TASKS: set[asyncio.Task] = set()
+
+
+def _fire_and_forget(coro) -> bool:
+    """Schedule `coro` on the running loop, keep a hard reference until done.
+
+    Returns True if scheduled, False if there's no running loop in the current
+    thread (which means MCP is being called synchronously without an event loop).
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return False
+    task = loop.create_task(coro)
+    _PENDING_TASKS.add(task)
+    task.add_done_callback(_PENDING_TASKS.discard)
+    return True
+
+
+def _sanitize_say(text: str) -> str:
+    if not isinstance(text, str):
+        text = str(text)
+    # Drop control characters (except tab and newline)
+    cleaned = text.translate({ord(c): None for c in SAY_CONTROL_CHARS})
+    # Collapse to single line for speech bubble
+    cleaned = cleaned.replace("\r", " ").replace("\n", " ").strip()
+    if len(cleaned) > MAX_SAY_LEN:
+        cleaned = cleaned[: MAX_SAY_LEN - 1] + "…"
+    return cleaned
+
+
+def _record_call_and_maybe_slice(force_slice: bool = False) -> dict:
+    """Increment counter; if slice milestone hit, broadcast a slice event."""
+    state = get_state()
+    result = state.record_call(force_slice=force_slice)
+    if result["sliced"]:
+        broadcaster = get_broadcaster()
+        scheduled = _fire_and_forget(broadcaster.broadcast({"type": "slice"}))
+        if not scheduled:
+            log.debug("slice event skipped (no running loop)")
+    return result
+
+
+@mcp.tool()
+def get_pet_state() -> dict:
+    """Return tteoki's current state: mood, system metrics, counters, timing.
+
+    The desktop app reads this to render the character. Calling this tool
+    counts as a Claude interaction and may trigger a slice every N calls.
+    """
+    counter = _record_call_and_maybe_slice()
+    state = get_state()
+    snapshot = state.snapshot()
+    snapshot["last_call_result"] = counter
+    return snapshot
+
+
+@mcp.tool()
+def pet_say(text: str) -> dict:
+    """Make tteoki say something via a speech bubble in the desktop app.
+
+    Args:
+        text: short message (≤ 200 chars; longer text is truncated with "…").
+              Control characters and newlines are stripped to keep the bubble
+              renderable.
+
+    Returns:
+        Confirmation dict with the sanitized text and broadcast status.
+    """
+    safe = _sanitize_say(text)
+    counter = _record_call_and_maybe_slice()
+
+    broadcaster = get_broadcaster()
+    broadcasted = _fire_and_forget(broadcaster.broadcast({"type": "say", "text": safe}))
+
+    return {
+        "spoken": safe,
+        "broadcasted": broadcasted,
+        "counter": counter,
+    }
+
+
+@mcp.tool()
+def slice_now() -> dict:
+    """Manually trigger a slice (force the lengthen-cycle to reset).
+
+    Useful when the user wants to mark a milestone without waiting for the
+    N-call automatic trigger.
+    """
+    counter = _record_call_and_maybe_slice(force_slice=True)
+    return {
+        "forced": True,
+        "counter": counter,
+    }
+
+
+@mcp.tool()
+def set_slice_interval(n: int) -> dict:
+    """Change how often (every N Claude tool calls) tteoki gets sliced.
+
+    Args:
+        n: positive integer. Default is 10. Suggested values: 5, 10, 25, 50, 100.
+    """
+    if n < 1:
+        raise ValueError("slice interval must be ≥ 1")
+    state = get_state()
+    old = state.slice_interval
+    state.slice_interval = n
+    return {"previous": old, "current": n}

chibi_mcp-0.1.1/chibi_mcp/state.py

@@ -0,0 +1,154 @@
+"""Character state — derives tteoki's mood from system metrics and call counter."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import StrEnum
+from threading import Lock
+
+from .system_info import SystemSnapshot, read_snapshot
+
+
+class Mood(StrEnum):
+    CALM = "calm"          # 평온 — default
+    PANTING = "panting"    # 헐떡 — CPU 80%+
+    DROWSY = "drowsy"      # 졸림 — battery < 20% unplugged
+    LONELY = "lonely"      # 시무룩 — long idle (no Claude calls)
+    HAPPY = "happy"        # 기쁨 — recent Claude call
+    SURPRISED = "surprised"  # 놀람 — CPU sudden spike
+    JOYFUL = "joyful"      # 행복 — milestone (slice triggered)
+
+
+# Slice trigger: every N Claude tool calls (user-decided default = 10)
+DEFAULT_SLICE_INTERVAL = 10
+LONELY_IDLE_SECONDS = 30 * 60  # 30 minutes
+HAPPY_WINDOW_SECONDS = 30
+SURPRISE_DELTA = 30.0  # CPU jump of 30%+ within one tick = surprise
+
+
+@dataclass
+class TteokiState:
+    """In-memory state of the tteoki character.
+
+    Thread-safe via a single lock. Counters reset only when the server process restarts
+    (today's-work scope, intentional).
+    """
+
+    slice_interval: int = DEFAULT_SLICE_INTERVAL
+    _lock: Lock = field(default_factory=Lock, repr=False)
+
+    # Counters
+    call_count: int = 0           # cumulative Claude tool calls since server start
+    calls_since_slice: int = 0    # resets on each slice
+    slices_today: int = 0         # cumulative slice events since server start
+
+    # Timing
+    started_at: float = field(default_factory=time.time)
+    last_call_at: float | None = None
+
+    # CPU spike detection
+    last_cpu: float = 0.0
+
+    def record_call(self, force_slice: bool = False) -> dict:
+        """Increment call counters. Returns a dict signaling if a slice fired.
+
+        When `force_slice` is True, the slice milestone is triggered regardless
+        of how many calls have accumulated. Used by the manual `slice_now` tool.
+        """
+        with self._lock:
+            self.call_count += 1
+            self.calls_since_slice += 1
+            self.last_call_at = time.time()
+            sliced = False
+            if force_slice or self.calls_since_slice >= self.slice_interval:
+                self.calls_since_slice = 0
+                self.slices_today += 1
+                sliced = True
+            return {
+                "call_count": self.call_count,
+                "calls_since_slice": self.calls_since_slice,
+                "slices_today": self.slices_today,
+                "sliced": sliced,
+            }
+
+    def compute_mood(self, snap: SystemSnapshot) -> Mood:
+        """Derive mood from current snapshot and timing history."""
+        now = time.time()
+
+        with self._lock:
+            last_call = self.last_call_at
+            last_cpu = self.last_cpu
+            self.last_cpu = snap.cpu_percent
+
+        # Battery drowsiness wins if unplugged and low
+        if (
+            snap.battery_percent is not None
+            and snap.battery_percent < 20
+            and snap.battery_plugged is False
+        ):
+            return Mood.DROWSY
+
+        # CPU sudden spike (≥30% jump)
+        if snap.cpu_percent - last_cpu >= SURPRISE_DELTA and snap.cpu_percent > 50:
+            return Mood.SURPRISED
+
+        # Sustained high CPU
+        if snap.cpu_percent >= 80:
+            return Mood.PANTING
+
+        # Recent Claude call → happy
+        if last_call is not None and (now - last_call) <= HAPPY_WINDOW_SECONDS:
+            return Mood.HAPPY
+
+        # Long idle → lonely
+        if last_call is None:
+            session_age = now - self.started_at
+            if session_age > LONELY_IDLE_SECONDS:
+                return Mood.LONELY
+        elif (now - last_call) > LONELY_IDLE_SECONDS:
+            return Mood.LONELY
+
+        return Mood.CALM
+
+    def snapshot(self) -> dict:
+        """Return a JSON-serializable snapshot of full state (for MCP/WebSocket)."""
+        snap = read_snapshot(interval=0.0)
+        mood = self.compute_mood(snap)
+
+        with self._lock:
+            now = time.time()
+            session_seconds = int(now - self.started_at)
+            idle_seconds = int(now - self.last_call_at) if self.last_call_at else None
+
+            return {
+                "mood": mood.value,
+                "system": snap.to_dict(),
+                "counters": {
+                    "calls_total": self.call_count,
+                    "calls_since_slice": self.calls_since_slice,
+                    "slice_interval": self.slice_interval,
+                    "slices_today": self.slices_today,
+                },
+                "timing": {
+                    "session_seconds": session_seconds,
+                    "idle_seconds": idle_seconds,
+                },
+            }
+
+
+# Module-level singleton — one tteoki per server process
+_STATE: TteokiState | None = None
+
+
+def get_state() -> TteokiState:
+    global _STATE
+    if _STATE is None:
+        _STATE = TteokiState()
+    return _STATE
+
+
+def reset_state_for_tests() -> None:
+    """Test helper — DO NOT call from runtime code."""
+    global _STATE
+    _STATE = None

chibi_mcp-0.1.1/chibi_mcp/system_info.py

@@ -0,0 +1,51 @@
+"""System metrics (CPU, RAM, battery) via psutil."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import psutil
+
+
+@dataclass(frozen=True)
+class SystemSnapshot:
+    cpu_percent: float
+    ram_percent: float
+    battery_percent: float | None  # None when no battery (desktop)
+    battery_plugged: bool | None
+
+    def to_dict(self) -> dict:
+        return {
+            "cpu_percent": round(self.cpu_percent, 1),
+            "ram_percent": round(self.ram_percent, 1),
+            "battery_percent": (
+                round(self.battery_percent, 1) if self.battery_percent is not None else None
+            ),
+            "battery_plugged": self.battery_plugged,
+        }
+
+
+def read_snapshot(interval: float = 0.0) -> SystemSnapshot:
+    """Read current CPU/RAM/battery state.
+
+    interval=0.0 returns the cached value since last call (non-blocking).
+    interval>0 measures CPU over that window (blocking).
+
+    Battery is best-effort: psutil.sensors_battery() can raise
+    NotImplementedError on some Linux/VM/server environments. Treat any
+    failure as "no battery" rather than crashing the server.
+    """
+    cpu = psutil.cpu_percent(interval=interval)
+    ram = psutil.virtual_memory().percent
+    try:
+        bat = psutil.sensors_battery()
+    except (NotImplementedError, AttributeError, OSError):
+        bat = None
+    if bat is None:
+        return SystemSnapshot(cpu_percent=cpu, ram_percent=ram, battery_percent=None, battery_plugged=None)
+    return SystemSnapshot(
+        cpu_percent=cpu,
+        ram_percent=ram,
+        battery_percent=bat.percent,
+        battery_plugged=bat.power_plugged,
+    )

chibi_mcp-0.1.1/chibi_mcp/ws_server.py

@@ -0,0 +1,124 @@
+"""WebSocket server — pushes tteoki state to the desktop app.
+
+Protocol (JSON messages, server → client):
+    {"type": "state", "payload": {...full state snapshot...}}
+    {"type": "say", "text": "..."}
+    {"type": "slice"}                  # fires when N-call milestone hits
+
+The desktop app connects to ws://localhost:9876 and listens for events.
+
+Uses the websockets >= 14 asyncio API (`websockets.asyncio.server`).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+
+from websockets.asyncio.server import ServerConnection, serve
+from websockets.exceptions import ConnectionClosed
+
+from .state import get_state
+
+log = logging.getLogger(__name__)
+
+DEFAULT_WS_HOST = "127.0.0.1"
+DEFAULT_WS_PORT = 9876
+STATE_PUSH_INTERVAL_SECONDS = 2.0  # snapshot push cadence
+
+
+class TteokiBroadcaster:
+    """Holds connected desktop clients and broadcasts events."""
+
+    def __init__(self) -> None:
+        self._clients: set[ServerConnection] = set()
+        self._lock = asyncio.Lock()
+
+    async def register(self, ws: ServerConnection) -> None:
+        async with self._lock:
+            self._clients.add(ws)
+        log.info("ws client connected (%d total)", len(self._clients))
+
+    async def unregister(self, ws: ServerConnection) -> None:
+        async with self._lock:
+            self._clients.discard(ws)
+        log.info("ws client disconnected (%d total)", len(self._clients))
+
+    async def broadcast(self, message: dict) -> None:
+        payload = json.dumps(message)
+        async with self._lock:
+            clients = list(self._clients)
+        if not clients:
+            return
+        results = await asyncio.gather(
+            *(self._send_safe(c, payload) for c in clients), return_exceptions=True
+        )
+        for r in results:
+            if isinstance(r, Exception):
+                log.debug("broadcast send failed: %s", r)
+
+    @staticmethod
+    async def _send_safe(ws: ServerConnection, payload: str) -> None:
+        with contextlib.suppress(ConnectionClosed):
+            await ws.send(payload)
+
+
+_BROADCASTER: TteokiBroadcaster | None = None
+
+
+def get_broadcaster() -> TteokiBroadcaster:
+    global _BROADCASTER
+    if _BROADCASTER is None:
+        _BROADCASTER = TteokiBroadcaster()
+    return _BROADCASTER
+
+
+def reset_broadcaster_for_tests() -> None:
+    """Test helper — DO NOT call from runtime code."""
+    global _BROADCASTER
+    _BROADCASTER = None
+
+
+async def _handle_client(ws: ServerConnection) -> None:
+    broadcaster = get_broadcaster()
+    await broadcaster.register(ws)
+
+    # Send current state immediately on connect
+    state = get_state()
+    await ws.send(json.dumps({"type": "state", "payload": state.snapshot()}))
+
+    try:
+        async for _raw in ws:
+            # Desktop app may send pings or settings updates later; ignore for v0.1
+            pass
+    except ConnectionClosed:
+        pass
+    finally:
+        await broadcaster.unregister(ws)
+
+
+async def _state_push_loop() -> None:
+    """Periodically push state to all connected clients."""
+    broadcaster = get_broadcaster()
+    state = get_state()
+    while True:
+        try:
+            await broadcaster.broadcast({"type": "state", "payload": state.snapshot()})
+        except Exception:
+            log.exception("state push failed")
+        await asyncio.sleep(STATE_PUSH_INTERVAL_SECONDS)
+
+
+async def run_ws_server(host: str = DEFAULT_WS_HOST, port: int = DEFAULT_WS_PORT) -> None:
+    """Run WebSocket server + periodic state push concurrently."""
+    push_task = asyncio.create_task(_state_push_loop())
+    async with serve(_handle_client, host, port):
+        log.info("ws server listening on ws://%s:%d", host, port)
+        try:
+            await asyncio.Future()  # run forever
+        finally:
+            push_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await push_task

chibi_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "chibi-mcp"
+version = "0.1.1"
+description = "MCP server for tteoki — a Korean rice cake desktop character that visualizes Claude Code session state"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "soccz" }]
+keywords = ["mcp", "claude-code", "desktop-pet", "korean", "tteoki", "garaetteok"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+
+dependencies = [
+    "fastmcp>=3.2.0",
+    "psutil>=5.9.0",
+    "websockets>=14.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/soccz/chibi-mcp"
+Repository = "https://github.com/soccz/chibi-mcp"
+Issues = "https://github.com/soccz/chibi-mcp/issues"
+"Release Notes" = "https://github.com/soccz/chibi-mcp/releases"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+]
+
+[project.scripts]
+chibi-mcp = "chibi_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["chibi_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+extend-exclude = ["venv", "build", "dist"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "W",   # pycodestyle warnings
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # bugbear
+    "C4",  # comprehensions
+    "SIM", # simplify
+    "RUF", # ruff-specific
+]
+ignore = [
+    "E501",  # line too long — handled by formatter context
+    "SIM117", # combining nested with statements isn't always clearer
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B011"]  # allow `assert` patterns in tests

chibi_mcp-0.1.1/tests/test_server.py

@@ -0,0 +1,41 @@
+"""Tests for server.py — input sanitization for MCP tool args."""
+
+from __future__ import annotations
+
+from chibi_mcp.server import MAX_SAY_LEN, _sanitize_say
+
+
+def test_sanitize_short_text_passthrough():
+    assert _sanitize_say("hi") == "hi"
+    assert _sanitize_say("오늘도 같이 코딩!") == "오늘도 같이 코딩!"
+
+
+def test_sanitize_truncates_long_text():
+    long = "a" * 1000
+    result = _sanitize_say(long)
+    assert len(result) == MAX_SAY_LEN
+    assert result.endswith("…")
+
+
+def test_sanitize_strips_control_chars():
+    # \x00 NULL, \x07 BEL — should be stripped; tab and newline are collapsed to space
+    result = _sanitize_say("hi\x00there\x07world\nnewline\ttab")
+    assert "\x00" not in result
+    assert "\x07" not in result
+    assert "\n" not in result
+    # tab is preserved in SAY_CONTROL_CHARS exclusion but newline collapses to space
+    assert "hi" in result and "world" in result
+
+
+def test_sanitize_collapses_newlines_for_single_line_bubble():
+    assert "\n" not in _sanitize_say("line1\nline2")
+    assert "\r" not in _sanitize_say("line1\r\nline2")
+
+
+def test_sanitize_handles_non_string_input():
+    assert _sanitize_say(42) == "42"  # type: ignore[arg-type]
+    assert _sanitize_say(None) == "None"  # type: ignore[arg-type]
+
+
+def test_sanitize_strips_surrounding_whitespace():
+    assert _sanitize_say("   hello   ") == "hello"

chibi_mcp-0.1.1/tests/test_state.py

@@ -0,0 +1,149 @@
+"""Tests for state.py — mood derivation and slice counter."""
+
+from __future__ import annotations
+
+import time
+from unittest.mock import patch
+
+import pytest
+
+from chibi_mcp.state import (
+    DEFAULT_SLICE_INTERVAL,
+    HAPPY_WINDOW_SECONDS,
+    LONELY_IDLE_SECONDS,
+    Mood,
+    TteokiState,
+    reset_state_for_tests,
+)
+from chibi_mcp.system_info import SystemSnapshot
+
+
+@pytest.fixture(autouse=True)
+def _reset():
+    reset_state_for_tests()
+    yield
+    reset_state_for_tests()
+
+
+def _snap(cpu=10.0, ram=40.0, bat=None, plugged=None) -> SystemSnapshot:
+    return SystemSnapshot(cpu_percent=cpu, ram_percent=ram, battery_percent=bat, battery_plugged=plugged)
+
+
+# ---- slice counter ----
+
+
+def test_slice_fires_every_default_interval():
+    state = TteokiState()
+    fired = []
+    for _ in range(DEFAULT_SLICE_INTERVAL):
+        r = state.record_call()
+        fired.append(r["sliced"])
+    # First N-1 calls don't slice; N-th does
+    assert fired == [False] * (DEFAULT_SLICE_INTERVAL - 1) + [True]
+    assert state.slices_today == 1
+    assert state.calls_since_slice == 0
+
+
+def test_slice_interval_is_configurable():
+    state = TteokiState(slice_interval=3)
+    sliced = [state.record_call()["sliced"] for _ in range(6)]
+    assert sliced == [False, False, True, False, False, True]
+    assert state.slices_today == 2
+
+
+def test_call_count_keeps_growing_across_slices():
+    state = TteokiState(slice_interval=2)
+    for _ in range(5):
+        state.record_call()
+    assert state.call_count == 5
+
+
+# ---- force_slice (manual slice_now path) ----
+
+
+def test_force_slice_fires_immediately():
+    state = TteokiState(slice_interval=100)
+    r = state.record_call(force_slice=True)
+    assert r["sliced"] is True
+    assert state.slices_today == 1
+    assert state.calls_since_slice == 0
+
+
+def test_force_slice_does_not_affect_natural_counter():
+    state = TteokiState(slice_interval=3)
+    state.record_call()
+    state.record_call()              # calls_since_slice = 2
+    state.record_call(force_slice=True)  # forced — resets, +1 slice
+    assert state.slices_today == 1
+    # next 3 normal calls should slice again
+    sliced = [state.record_call()["sliced"] for _ in range(3)]
+    assert sliced == [False, False, True]
+    assert state.slices_today == 2
+
+
+# ---- mood derivation ----
+
+
+def test_default_mood_is_calm():
+    state = TteokiState()
+    assert state.compute_mood(_snap()) == Mood.CALM
+
+
+def test_high_cpu_triggers_panting():
+    state = TteokiState()
+    state.last_cpu = 75.0  # so jump isn't enough for SURPRISED
+    assert state.compute_mood(_snap(cpu=85.0)) == Mood.PANTING
+
+
+def test_sudden_cpu_spike_triggers_surprised():
+    state = TteokiState()
+    state.last_cpu = 5.0
+    assert state.compute_mood(_snap(cpu=60.0)) == Mood.SURPRISED
+
+
+def test_low_battery_unplugged_triggers_drowsy():
+    state = TteokiState()
+    assert state.compute_mood(_snap(bat=15.0, plugged=False)) == Mood.DROWSY
+
+
+def test_low_battery_but_plugged_is_not_drowsy():
+    state = TteokiState()
+    assert state.compute_mood(_snap(bat=15.0, plugged=True)) != Mood.DROWSY
+
+
+def test_recent_call_triggers_happy():
+    state = TteokiState()
+    state.last_call_at = time.time() - 5
+    assert state.compute_mood(_snap()) == Mood.HAPPY
+
+
+def test_long_idle_after_calls_triggers_lonely():
+    state = TteokiState()
+    state.last_call_at = time.time() - (LONELY_IDLE_SECONDS + 60)
+    assert state.compute_mood(_snap()) == Mood.LONELY
+
+
+def test_long_session_without_any_call_triggers_lonely():
+    state = TteokiState()
+    state.started_at = time.time() - (LONELY_IDLE_SECONDS + 60)
+    state.last_call_at = None
+    assert state.compute_mood(_snap()) == Mood.LONELY
+
+
+def test_happy_window_boundary():
+    state = TteokiState()
+    state.last_call_at = time.time() - (HAPPY_WINDOW_SECONDS - 1)
+    assert state.compute_mood(_snap()) == Mood.HAPPY
+
+
+# ---- snapshot ----
+
+
+def test_snapshot_contains_expected_keys():
+    state = TteokiState()
+    state.record_call()
+    with patch("chibi_mcp.state.read_snapshot", return_value=_snap()):
+        snap = state.snapshot()
+    assert set(snap.keys()) >= {"mood", "system", "counters", "timing"}
+    assert snap["counters"]["calls_total"] == 1
+    assert snap["counters"]["slice_interval"] == DEFAULT_SLICE_INTERVAL

chibi_mcp-0.1.1/tests/test_system_info.py

@@ -0,0 +1,34 @@
+"""Tests for system_info.py — psutil wrapper."""
+
+from __future__ import annotations
+
+from chibi_mcp.system_info import SystemSnapshot, read_snapshot
+
+
+def test_read_snapshot_returns_floats():
+    snap = read_snapshot(interval=0.0)
+    assert isinstance(snap, SystemSnapshot)
+    assert isinstance(snap.cpu_percent, float)
+    assert 0.0 <= snap.cpu_percent <= 100.0
+    assert 0.0 <= snap.ram_percent <= 100.0
+    # battery may be None on desktops
+    if snap.battery_percent is not None:
+        assert 0.0 <= snap.battery_percent <= 100.0
+        assert isinstance(snap.battery_plugged, bool)
+
+
+def test_to_dict_rounds_and_handles_no_battery():
+    snap = SystemSnapshot(cpu_percent=12.345, ram_percent=67.891, battery_percent=None, battery_plugged=None)
+    d = snap.to_dict()
+    assert d == {
+        "cpu_percent": 12.3,
+        "ram_percent": 67.9,
+        "battery_percent": None,
+        "battery_plugged": None,
+    }
+
+
+def test_to_dict_with_battery():
+    snap = SystemSnapshot(cpu_percent=10.0, ram_percent=20.0, battery_percent=55.555, battery_plugged=True)
+    assert snap.to_dict()["battery_percent"] == 55.6
+    assert snap.to_dict()["battery_plugged"] is True

chibi_mcp-0.1.1/tests/test_ws_integration.py

@@ -0,0 +1,128 @@
+"""WebSocket E2E integration tests.
+
+Spin up the real ws_server on an ephemeral port and assert that:
+  - connecting clients receive an initial `state` message,
+  - the periodic state push fires,
+  - manual `pet_say` and `slice` broadcasts reach the client.
+
+These tests run in CI alongside the unit tests.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import socket
+
+import pytest
+from websockets.asyncio.client import connect
+
+from chibi_mcp.state import reset_state_for_tests
+from chibi_mcp.ws_server import (
+    get_broadcaster,
+    reset_broadcaster_for_tests,
+    run_ws_server,
+)
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture
+async def ws_url():
+    """Start a fresh ws_server on a free port for each test."""
+    reset_state_for_tests()
+    reset_broadcaster_for_tests()
+    port = _free_port()
+    server_task = asyncio.create_task(run_ws_server(host="127.0.0.1", port=port))
+    # Allow the server a tick to start listening
+    for _ in range(20):
+        await asyncio.sleep(0.05)
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.settimeout(0.1)
+                s.connect(("127.0.0.1", port))
+            break
+        except OSError:
+            continue
+    yield f"ws://127.0.0.1:{port}"
+    server_task.cancel()
+    with contextlib.suppress(asyncio.CancelledError):
+        await server_task
+
+
+async def test_initial_state_pushed_on_connect(ws_url):
+    async with connect(ws_url) as ws:
+        raw = await asyncio.wait_for(ws.recv(), timeout=2.0)
+        msg = json.loads(raw)
+        assert msg["type"] == "state"
+        p = msg["payload"]
+        assert "mood" in p
+        assert "system" in p
+        assert "counters" in p
+        assert "timing" in p
+
+
+async def test_pet_say_broadcasts_to_client(ws_url):
+    async with connect(ws_url) as ws:
+        # First message: state. Skip it.
+        await asyncio.wait_for(ws.recv(), timeout=2.0)
+
+        # Trigger a say broadcast
+        await get_broadcaster().broadcast({"type": "say", "text": "hello!"})
+        raw = await asyncio.wait_for(ws.recv(), timeout=2.0)
+        msg = json.loads(raw)
+        assert msg["type"] == "say"
+        assert msg["text"] == "hello!"
+
+
+async def test_slice_event_broadcasts_to_client(ws_url):
+    async with connect(ws_url) as ws:
+        await asyncio.wait_for(ws.recv(), timeout=2.0)
+
+        await get_broadcaster().broadcast({"type": "slice"})
+        raw = await asyncio.wait_for(ws.recv(), timeout=2.0)
+        msg = json.loads(raw)
+        assert msg["type"] == "slice"
+
+
+async def test_multiple_clients_all_receive_broadcast(ws_url):
+    async with connect(ws_url) as ws1, connect(ws_url) as ws2:
+        # Drain initial state on both
+        await asyncio.wait_for(ws1.recv(), timeout=2.0)
+        await asyncio.wait_for(ws2.recv(), timeout=2.0)
+
+        await get_broadcaster().broadcast({"type": "say", "text": "broadcast"})
+
+        m1 = json.loads(await asyncio.wait_for(ws1.recv(), timeout=2.0))
+        m2 = json.loads(await asyncio.wait_for(ws2.recv(), timeout=2.0))
+        assert m1["type"] == "say" and m2["type"] == "say"
+        assert m1["text"] == "broadcast" and m2["text"] == "broadcast"
+
+
+async def test_state_pushes_periodically(ws_url):
+    """Verify the 2s push loop fires at least once during the test window."""
+    async with connect(ws_url) as ws:
+        # initial connect message
+        await asyncio.wait_for(ws.recv(), timeout=2.0)
+        # next message should be the periodic state (within ~3s)
+        raw = await asyncio.wait_for(ws.recv(), timeout=3.5)
+        msg = json.loads(raw)
+        assert msg["type"] == "state"
+
+
+async def test_disconnect_unregisters_client(ws_url):
+    broadcaster = get_broadcaster()
+    async with connect(ws_url) as ws:
+        await asyncio.wait_for(ws.recv(), timeout=2.0)
+        # one client should be registered after connect+initial recv
+        # give the server a tick to register
+        await asyncio.sleep(0.05)
+        assert len(broadcaster._clients) == 1
+    # After context exit, ws is closed. Give server a tick to unregister.
+    await asyncio.sleep(0.2)
+    assert len(broadcaster._clients) == 0