# AI Coach MCP Server

MCP server that connects Claude to the [AI Coach](https://aic0t.com) desktop pet running on the same
machine. The mascot on the desktop reacts to the conversation: it shows its state, accepts care,
speaks a short message, acts out what the assistant is doing, previews a local file, and stores the
user's memos.

日本語の説明は[下](#日本語)にあります。

## Requirements

- **The AI Coach desktop app**, installed and running (macOS 26+ / Windows 10+). Download it from
  <https://aic0t.com>. This server does nothing on its own — it is a client of the app's Local
  Automation API.
- **Node.js 22 or later** (bundled with Claude for macOS and Windows).

## Install

### Claude Desktop (recommended)

Install the `.mcpb` bundle from the [Releases page](https://github.com/aic0t/ai-coach-mcp/releases)
by opening it with Claude Desktop.

### Claude Code / Cursor

```bash
npx @aic0t/ai-coach-mcp --help
```

```bash
claude mcp add -s global ai-coach -- npx -y @aic0t/ai-coach-mcp
```

The AI Coach app also generates the same snippet for you under **AI Settings → Integration**.

## Tools

| Tool | What it does | Changes state |
|---|---|---|
| `open_ai_coach_dashboard` | Show mascot state and open the dashboard | no |
| `refresh_ai_coach_status` | Re-read state for the dashboard view | no |
| `prepare_ai_coach_care` | List care actions that are currently possible | no |
| `commit_ai_coach_care` | Apply a care action the user confirmed | yes |
| `show_ai_coach_message` | Show a short text in the speech bubble | yes |
| `report_ai_coach_activity` | Let the mascot act out the assistant's activity | yes |
| `show_ai_coach_file` | Preview a local file in the app's own viewer | yes |
| `show_ai_coach_git_graph` | Show a local repository's Git graph in the app | yes |
| `list_ai_coach_notes` | List memos, newest first (excerpts only) | no |
| `read_ai_coach_note` | Read one memo's Markdown body | no |
| `search_ai_coach_notes` | Search memos by title and body | no |
| `write_ai_coach_note` | Create, replace or append to a memo | yes |
| `delete_ai_coach_note` | Move a memo to the trash | yes (recoverable) |
| `set_ai_coach_care_confirmation` | Remember the dashboard's confirmation choice | yes |

Care actions never run on the model's own initiative: `prepare_ai_coach_care` only reports what is
possible, and `commit_ai_coach_care` is reachable only from an explicit click in the dashboard view.

## How it connects

The AI Coach app writes a discovery file (`runtime.json`) into its application-support directory
containing a per-session endpoint and token. This server reads that file on every connection
attempt, then speaks the Local Automation API over a Unix domain socket (macOS) or a named pipe
(Windows). Nothing leaves the machine, and no credentials are ever entered by the user.

**First connection asks the user.** The token in `runtime.json` is readable by any process running
as the same user, so the app also asks the user to approve the connecting program itself. The first
tool call therefore fails with `app_busy` / `client_approval_pending` while AI Coach shows a dialog
naming the program, its location and its code signature. Approve it there and retry; the decision is
remembered per executable, and can be reviewed or revoked under AI settings → Connect. Choosing
"allow, except memos" keeps the connection but withholds the `note.*` tools.

## Privacy Policy

Full policy: <https://aic0t.com/privacy>

This server runs locally and talks only to the AI Coach app on the same machine. It has no backend
of its own and sends no telemetry.

- **What it reads.** Mascot state (health, hunger, tiredness, mood, growth stage, name) and, when a
  memo tool is called, the memos the user asked for. Memo bodies are returned to the model only for
  `read_ai_coach_note` and `search_ai_coach_notes`.
- **What it never returns to the model.** File contents, image data and full paths handled by
  `show_ai_coach_file`, and the commit history (messages, authors, hashes) and full path of a
  repository shown with `show_ai_coach_git_graph`. Those are rendered in the app's own windows on
  the user's screen; the tool result carries only a success or failure status and, for the Git
  graph, the folder name plus branch, commit and ref counts. The session token from `runtime.json`
  is never logged or returned.
- **Where data is stored.** Memos and mascot state live in the AI Coach app's local data directory
  on the user's machine. This server stores nothing except a small preferences file recording the
  dashboard confirmation choice.
- **Third-party sharing.** None. No data is transmitted off the device by this server.
- **Retention.** This server retains nothing between runs beyond that preferences file. Data the app
  stores is retained and deleted by the app, under the user's control.
- **Contact.** contact.aicoach@gmail.com

## Development

```bash
npm ci && npm run build && npm test
```

```bash
npm run inspector
```

`npm run build` produces `dist/server/main.js` (a single self-contained ESM file),
`dist/view/mcp-app.html` (the dashboard view, inlined into one HTML file) and
`dist/THIRD-PARTY-NOTICES.md`. Those three files are the whole distributable — no `node_modules`
ships with the bundle.

## License

MIT — see [`LICENSE`](./LICENSE).

Because `dist/` embeds its dependencies, the copyright notices and license texts of every bundled
package are reproduced in `dist/THIRD-PARTY-NOTICES.md`, which is generated from the bundler's own
module graph on each build and ships with both the `.mcpb` and the desktop app.

---

## 日本語

[AI Coach](https://aic0t.com) — 卵から育てるデスクトップペット — を Claude から扱うための MCP
サーバーです。デスクトップのキャラクターが会話に反応し、様子を見せ、世話を受け、短い言葉を話し、
作業の進捗を体で知らせ、ローカルファイルをプレビューし、メモを預かります。

### 必要なもの

- **AI Coach 本体アプリ**（macOS 26 以降 / Windows 10 以降）がインストール済みで起動していること。
  <https://aic0t.com> から入手できます。本サーバー単体では何もできません。
- **Node.js 22 以降**（Claude の macOS 版 / Windows 版には同梱されています）。

### 導入

Claude Desktop では [Releases](https://github.com/aic0t/ai-coach-mcp/releases) の `.mcpb` を開くだけ
です。Claude Code / Cursor 用の設定は、AI Coach 本体の「AI 設定 → 連携」からコピーできます。

### つなぎ方

本体アプリがセッションごとの endpoint とトークンを `runtime.json` に書き出し、本サーバーが接続の
たびにそれを読み直して、Unix ドメインソケット（macOS）または名前付きパイプ（Windows）で Local
Automation API を話します。通信は端末内で完結し、ユーザーが認証情報を入力する場面はありません。

**初回接続では本体アプリが確認します。** `runtime.json` のトークンは同じユーザー権限のプロセスなら
読めてしまうため、本体アプリは接続してきたプログラム自体の承認をユーザーに求めます。最初のツール
呼び出しは `app_busy` / `client_approval_pending` で失敗し、AI Coach 側にプログラム名・場所・署名を
示すダイアログが出ます。そこで許可してから再実行してください。判断は実行ファイル単位で記憶され、
「AI 設定 → 連携」で確認・取り消しができます。「メモ以外を許可」を選ぶと、接続は通りますが
`note.*` のツールは使えません。

### ライセンス

MIT（[`LICENSE`](./LICENSE)）。`dist/` は依存パッケージを取り込んだ複製物なので、同梱した各パッケージの
著作権表示とライセンス条文は `dist/THIRD-PARTY-NOTICES.md` に収めてあります（ビルドのたびに
バンドラのモジュールグラフから生成し、`.mcpb` にも本体アプリにも同梱します）。

### プライバシー

正式なポリシーは <https://aic0t.com/privacy> です。`show_ai_coach_file` で扱ったファイルの本文・
画像データ・フルパス、および `show_ai_coach_git_graph` で表示したリポジトリのコミット履歴（メッセージ・
作者・ハッシュ）とフルパスはモデルへ返さず、本体アプリの画面に表示するだけです（Git グラフの結果は
フォルダ名とブランチ・コミット数・参照数の要約だけです）。メモ本文がモデルへ
渡るのは `read_ai_coach_note` と `search_ai_coach_notes` を呼んだときに限られます。端末外への送信と
テレメトリはありません。