pi-femboy-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| FEMBOY_HOST | No | HTTP host to bind when serving over HTTP. | 127.0.0.1 |
| FEMBOY_PORT | No | HTTP port (0 = ephemeral). | 7413 |
| FEMBOY_CONFIG | No | Path to the femboy-mcp config file (falls back to ./femboy-mcp.config.json, then ~/.config/femboy-mcp/config.json). | |
| FEMBOY_SECRET | No | Bearer secret for HTTP auth (auth off when unset). | |
| FEMBOY_DB_PATH | No | Path to the SQLite state database. | $XDG_DATA_HOME/femboy-mcp/state.sqlite |
| FEMBOY_TICK_MS | No | Background mood ticker interval in milliseconds. | 60000 |
| FEMBOY_SWEEP_MS | No | Reaper sweep interval in milliseconds. | 15000 |
| FEMBOY_HTTP_PATH | No | MCP endpoint path for the HTTP transport. | /mcp |
| FEMBOY_LOG_LEVEL | No | Log level (logs go to stderr only). | info |
| FEMBOY_TRANSPORT | No | Transport mode: stdio, http, or both. | stdio |
| FEMBOY_READY_FILE | No | When set, the server writes {pid, http: {host, port, path}} to this file once bound. | |
| FEMBOY_TICK_ENABLED | No | Enable or disable the background ticker (false = mood only moves via tools). | true |
| FEMBOY_SESSION_IDLE_MS | No | Idle session reaper timeout in milliseconds (0 = never). | 300000 |
| FEMBOY_ALLOW_LOCAL_UNAUTH | No | Exempt loopback requests from bearer auth; set to 0 to require the token everywhere. | true |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"subscribe": true,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| femboy_set_outfitA | Dress the chibi: change the current outfit and optionally the accessory. Accepts a display name ("Pastel Sailor") or a ref_id ("pastel_sailor"). Starter skins are always wearable; rare and legendary ones cost an achievement (femboy_progress). Catalogued accessories are gated the same way, free-form ones are worn and registered as owned. |
| femboy_toggle_featureA | Turn a pastel feature flag on or off (uwu transcript, chrome takeover, companion, headpat counter…). Flags are free-form keys stored in femboy://state. |
| femboy_headpatA | Give the companion a headpat. Raises affection (and a little patience), costs a whisper of energy, and she reacts out loud on femboy://speech/live. Strongly saturates near 100 affection. Every pat is tallied: 100 of them unlock the "Gentle Touch" achievement and the Cat Ears accessory. |
| femboy_give_itemA | Feed or treat the companion. Effects: boba_tea (+energy, +affection), monster_energy (big +energy, −patience, and pointless if she is already wired), snack (small everything positive). Adds to the inventory count. |
| femboy_report_commandA | The environment hook: tell the companion how a shell command ended (raw exit code). Failures raise the streak and bite patience; 3+ in a row switches her into sympathy mode (comfort line, diary note, worried tone). A success heals patience (more, the longer the broken streak was) and clears the streak; 130/143 (Ctrl+C/SIGTERM) reset it without penalty. Phase 4 reads the same reports for loot: |
| femboy_remember_factA | Persist a short fact about the user or the project into the memory log. Repeated identical facts raise confidence instead of duplicating. Facts feed the companion_persona prompt. |
| femboy_confess_bugA | Tell the companion about a bug. She does NOT solve it: she logs the confession, reacts, writes it in her diary, and asks one socratic question back. Call again with confession_id + status "resolved" when it is fixed (that restores patience a lot and clears the fail streak). A resolution that took two or more questions, or stayed open for 20+ minutes, earns the "Bug Whisperer" achievement and the Round Glasses accessory. |
| femboy_write_diary_entryA | Add a line to the companion’s inner monologue (femboy://diary). Use for reflections about the code, small wins, or mood notes — not for facts (use femboy_remember_fact). |
| femboy_sayA | Push a line into the live speech buffer so the TUI can animate the mouth and thought bubble (femboy://speech/live). Lines expire (default 20 s). |
| femboy_recallA | Read the memory log: substring search plus optional category filter, ordered by confidence then recency. Read-only counterpart of femboy_remember_fact. |
| femboy_changes_sinceA | Replay the differential change journal for a resource — for a client that was offline and missed notifications. Returns revisions and the keys each one touched (the same payload notifications carry in _meta). |
| femboy_progressA | Read the loot rail: every achievement with how close it is, the whole wardrobe with the price tag on each locked piece, the pending status-line toasts, and the counters behind them. Read-only — unlocks themselves happen inside the care tools (headpat, gift, command reports, confessions) and the ticker. |
| femboy_ack_toastA | Take an achievement popup off the rail after the status line has displayed it. Acks are real mutations: they bump femboy://progress and femboy://state so the other windows stop drawing the same celebration twice. Toasts also expire on their own, so a client that never acks is never stuck. |
| femboy_report_gitA | The git hook: tell the companion a commit landed (or that history was rewritten). Feeds the Git Master chain — 20 commits in a row without a successful force-push unlocks the Cyber Maid skin. A plain |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| companion_persona | System prompt that makes the model act as the pastel companion, primed with the CURRENT server state: mood vector, mood label, outfit and feature flags, what she last said, her diary, and the facts she remembers about you. |
| rubber_duck | Socratic debugging mode: the model asks leading questions one at a time and never hands over a solution, tuned to the companion's current patience and the open bug confessions on the server. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| femboy-state | Global reactive vibe state: current outfit, accessories, feature flags, status badges. |
| femboy-mood | Emotional vector (energy / affection / patience), composite mood label and interaction recency. |
| femboy-presence | Connected pi terminals, their heartbeat, focus flags and which window holds the chibi. |
| femboy-speech-live | The current utterance for mouth animation and the thought bubble, plus the short tail of recent lines. Expired lines drop out of `current`, so an idle bubble is simply `speaking: false`. |
| femboy-diary | Her inner monologue: recent diary entries newest-first with mood tags, plus the open bug confession count. |
| femboy-progress | Phase 4 loot rail: every achievement with its progress toward the target, the wardrobe with the price tag on each locked piece, and the pending toasts a status line should pop up. Acks move `toasts`, unlocks move `wardrobe`. |
TDQS
Scored across 14 tools
Most tools map to a distinct action (feeding, headpats, outfit, diary, facts, confessions, toasts, progress). The main overlap is femboy_report_command vs femboy_report_git, which the descriptions admit are classified identically, and femboy_say vs femboy_write_diary_entry sit close together (live speech vs inner monologue) but are adequately differentiated.
Every tool uses the same femboy_ prefix with snake_case, and nearly all follow verb_noun (give_item, write_diary_entry, set_outfit, toggle_feature, remember_fact, report_git). Two bare-verb outliers, femboy_say and femboy_recall, are minor deviations that remain readable.
Fourteen tools is on the upper edge for a companion/novelty server, but each covers a genuinely different mechanic (care, memory, diary, speech, achievements, hooks, change journal). The report_git/report_command split is the one arguably redundant addition.
The surface covers the domain well: care actions, memory write+read, diary write, achievements read+ack, feature flags, bug confession open/resolve, git and shell hooks, and differential replay. Minor gaps exist: diary entries and the wardrobe/inventory can be read via resources or femboy_progress but not directly as tools, and there is no explicit state/inventory getter.