furry-companion-mcp

Furry Companion MCP

AI Companion MCP Runtime for agent presence events over stdio MCP plus local IPC for UI consumers.

Runtime path:

AI Agent -> MCP Tool -> Event Bus -> local IPC -> VSCode Extension -> Webview

No websocket MCP transport is used.

Tool

set_state({ state: "thinking" })

message and file are optional. Use message to describe what the agent is doing, and use file when the agent is actively editing a code file:

set_state({
  state: "coding",
  message: "Updating the webview state renderer.",
  file: "src/stateViewProvider.ts"
})

Supported states:

• idle
• thinking
• planning
• coding
• testing
• success
• error

Use testing for validation, failed-build investigation, bug isolation, and runtime behavior checks. There is no separate failure-investigation state.

Agent contract:

• If the furry_companion MCP tool is available, every user conversation or request must publish real-time progress with set_state.
• After the conversation task completes successfully, call set_state({ state: "success", message: "Implementation and verification are complete." }) or an equivalent short success message.
• If the task cannot be completed due to an unrecoverable problem, call set_state({ state: "error", message: "Blocked by an unrecoverable error." }) with a short reason.

The tool emits:

bus.emit("state", {
  type: "state",
  state,
  message,
  file
})

Install From npm

Use the package directly from npm in an MCP client:

{
  "mcpServers": {
    "furry-companion": {
      "command": "npx",
      "args": ["-y", "furry-companion-mcp"]
    }
  }
}

Or install it globally:

npm install -g furry-companion-mcp
furry-companion-mcp

Publish To GitHub Packages

The npmjs package keeps the unscoped name furry-companion-mcp so existing npx -y furry-companion-mcp installs continue to work. GitHub Packages requires scoped npm names, so the GitHub Packages copy is published as @masaominn/furry-companion-mcp.

Authenticate once with a GitHub classic personal access token that has write:packages and read:packages:

npm login --scope=@masaominn --auth-type=legacy --registry=https://npm.pkg.github.com

Publish the GitHub Packages copy:

npm run publish:github

Publish to both npmjs and GitHub Packages:

npm run publish

The publish script temporarily changes the package name to @masaominn/furry-companion-mcp, publishes to https://npm.pkg.github.com, and then restores the local package name to furry-companion-mcp. GitHub Packages links the package to https://github.com/MasaoMinn/furry-mcp.git through the repository field in package.json.

npm run publish builds once, publishes the unscoped furry-companion-mcp package to npmjs, then publishes the scoped @masaominn/furry-companion-mcp package to GitHub Packages. The internal npm publish calls use --ignore-scripts so the publish script does not recursively call itself.

VSCode Extension Bridge

The MCP server starts a local JSON Lines IPC bridge for non-MCP UI consumers. Multiple MCP processes can run at the same time: the first process owns the bridge, and later processes relay their state events into the existing bridge.

Default IPC path:

• Windows: \\.\pipe\furry-companion-mcp
• macOS/Linux: /tmp/furry-companion-mcp.sock

Override it when needed:

FURRY_COMPANION_IPC_PATH=/tmp/my-companion.sock furry-companion-mcp

Each IPC line is a state event:

{"type":"state","state":"coding","message":"Updating the webview state renderer.","file":"src/stateViewProvider.ts"}

The VSCode extension should connect to this IPC path with Node net, parse newline-delimited JSON, then call webview.postMessage({ command: "state-update", ... }).

Agent Skills

Skill documents are included in the npm package under skills/:

• skills/claude.md
• skills/codex.md
• skills/cursor.md

They are downloaded with the MCP package, but MCP clients do not automatically activate arbitrary skill files from npm packages. Copy or reference the matching file in the agent's own instruction/skill system. See skills/INSTALL.md for the available installation options.

Development

npm install
npm run build
npm run start

MCP CLI

After building, the package exposes:

{
  "bin": {
    "furry-companion-mcp": "./dist/index.js"
  }
}

Use it as a stdio MCP server. No websocket transport is used.