Kaomoji

kaomoji-mcp

AI エージェントが重要なやり取りの場面で使える、CLI 対応の顔文字

重要な場面（思考中、成功を祝うとき、謝罪するとき）に、AI エージェントが表情豊かな顔文字（ASCII のエモーティコン）を使えるようにする Model Context Protocol（MCP） サーバーです。すべての顔文字は CLI 対応です。全角文字や装飾的な Unicode 文字を使わないため、どのターミナルでも表示が崩れる心配はありません。

Searching for auth middleware
(..)

All tests passed! (^o^)/

---

目次

• kaomoji-mcp を選ぶ理由
• ツール、プロンプト、リソース
• インストール
• クイックスタート
• クライアント別の設定
  • Claude Desktop
  • Claude Code (CLI)
  • Cursor
  • VS Code + GitHub Copilot
  • Windsurf
  • Zed
  • Continue.dev
  • Cline / Roo Cline
  • Smithery
• 開発
• テストの実行

---

kaomoji-mcp を選ぶ理由

現代の AI エージェントは、回答を提示するまでに複数のサブタスクを実行します。視覚的な表示がなければ、ユーザーには最終回答が出るまで何も見えません。kaomoji-mcp は、エージェントが次のようにすることでこの問題を解決します。

• 各サブタスクの前に思考中の顔文字を表示し、ユーザーが進捗をリアルタイムで確認できるようにします
• タスクが正常に完了したときに成功を祝う顔文字を表示します
• 結果が見つからないときやエラーが発生したときに謝罪の顔文字を表示します

すべての文字は ASCII／半角に対応しているため、どのターミナル、IDE のパネル、チャットインターフェースでも正しく表示されます。

---

ツール、プロンプト、リソース

ツール

ツール	呼び出すタイミング	主なパラメーター
thinking_kaomoji	各サブタスクまたは推論フェーズの前	phase（文字列、最大 80 文字）；省略可能な mcp_server
celebrate_kaomoji	タスクが正常に完了した後	intensity："subtle" ／ "moderate" ／ "intense"
apologize_kaomoji	結果なし、エラー、またはユーザーが不満を示したとき	reason："not_found" ／ "error" ／ "dissatisfied"

thinking_kaomoji — 進捗表示です。サブタスクごとに 1 回呼び出します。省略可能な mcp_server パラメーターを指定すると、処理を委任する外部 MCP サーバーを表示できます。

**Reading project files** [filesystem]
(._.)

celebrate_kaomoji — 完了を知らせます。状況に合わせて強度を選択します。

• subtle — 軽微な修正、フォーマルな状況 → (^-^)
• moderate — 通常のタスクが完了したとき → (^o^)/
• intense — 大きな突破口が開けたとき → \(^∀^)/

apologize_kaomoji — 失敗を知らせます。reason フィールドで状況を分類します。

• not_found — 検索結果がありませんでした
• error — 予期しないエラーが発生しました
• dissatisfied — ユーザーが不満を示しました

プロンプト

プロンプト	説明
react_with_kaomoji	動作ガイド全体です。このプロンプトを読み込むと、3 つすべてのツールをいつどのように使うかについて、エージェントに詳細なルールを設定できます

リソース

URI	MIME	説明
kaomoji://catalog	application/json	すべてのシーン、強度、状態、理由、フォールバック文字列、バイリンガルタグを含む顔文字データベース全体

---

インストール

要件

• Node.js ≥ 20

オプション A — npx（インストール不要、常に最新版）

インストールは不要です。MCP クライアントの設定でパッケージを指定するだけで（以下を参照）、エージェントのランタイムが自動的に取得します。

npx kaomoji-mcp

オプション B — グローバルインストール

npm install -g kaomoji-mcp
kaomoji-mcp   # starts the stdio server

オプション C — プロジェクトをローカルにクローン

git clone https://github.com/frankunderwood-w/kaomoji_mcp_server.git
cd kaomoji-mcp
npm install
npm run build
node build/index.js   # starts the stdio server

オプション D — npm でローカルプロジェクトとしてインストール

mkdir my-project && cd my-project
npm init -y
npm install kaomoji-mcp

---

クイックスタート

設定が完了すると、MCP 対応エージェントは接続時にサーバーの指示を自動的に受け取り、適切なタイミングでツールを呼び出すようになります。また、システムプロンプトで react_with_kaomoji プロンプトを要求して、動作ガイドを明示的に読み込むこともできます。

---

クライアントごとの設定

以下の設定はすべて、stdio トランスポートを介してサーバーを起動します。npm パッケージを直接使う場合は、node /absolute/path/to/build/index.js を npx kaomoji-mcp に置き換えてください。

---

Claude Desktop

設定ファイルの場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

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

または、リポジトリをローカルにクローンした場合：

{
  "mcpServers": {
    "kaomoji": {
      "command": "node",
      "args": ["/absolute/path/to/kaomoji-mcp/build/index.js"]
    }
  }
}

保存後、Claude Desktop を再起動してください。サーバーは Settings → Developer → MCP Servers に表示されます。

---

Claude Code（CLI）

サーバーをプロジェクトまたはユーザーの設定に追加します。

# Project-scoped (adds to .claude/mcp.json)
claude mcp add kaomoji -- npx -y kaomoji-mcp

# Or global
claude mcp add --global kaomoji -- npx -y kaomoji-mcp

または、.claude/mcp.json を手動で編集します。

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

---

Cursor

設定ファイルの場所（グローバル）： ~/.cursor/mcp.json
設定ファイルの場所（プロジェクト）： <project-root>/.cursor/mcp.json

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

または、Cursor の UI で Settings → Cursor Settings → MCP に移動し、+ Add new MCP server をクリックして上記のコマンドを入力します。

---

VS Code + GitHub Copilot

VS Code 1.99+ は、GitHub Copilot 拡張機能が有効な場合、MCP サーバーをネイティブでサポートします。

オプション 1 — ワークスペース設定（.vscode/mcp.json）：

{
  "servers": {
    "kaomoji": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kaomoji-mcp"]
    }
  }
}

オプション 2 — ユーザー設定（settings.json）：

{
  "mcp": {
    "servers": {
      "kaomoji": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "kaomoji-mcp"]
      }
    }
  }
}

Copilot Chat パネルを Agent mode で開くと、サーバーが自動的に利用可能になります。

---

Windsurf

設定ファイルの場所： ~/.codeium/windsurf/mcp_config.json

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

または、Windsurf の UI で Windsurf Settings → Cascade → MCP Servers に移動し、+ ボタンをクリックします。

---

Zed

設定ファイルの場所： ~/.config/zed/settings.json

{
  "context_servers": {
    "kaomoji": {
      "command": {
        "path": "npx",
        "args": ["-y", "kaomoji-mcp"]
      }
    }
  }
}

---

Continue.dev

設定ファイルの場所： ~/.continue/config.json（グローバル）または .continue/config.json（プロジェクト）

{
  "mcpServers": [
    {
      "name": "kaomoji",
      "command": "npx",
      "args": ["-y", "kaomoji-mcp"]
    }
  ]
}

---

Cline / Roo Cline

VS Code で Cline 拡張機能のサイドバーを開き、MCP Servers アイコンをクリックして、Edit MCP Settings を選択します。

{
  "mcpServers": {
    "kaomoji": {
      "command": "npx",
      "args": ["-y", "kaomoji-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

---

Smithery

このサーバーは Smithery にデプロイできます。smithery.ts エントリポイントは configSchema（空 — 設定不要）と createServer ファクトリーを公開します。

Smithery CLI でデプロイまたはインストールするには：

npx @smithery/cli install kaomoji-mcp

---

開発

# Clone and install
git clone https://github.com/frankunderwood-w/kaomoji_mcp_server.git
cd kaomoji-mcp
npm install

# Compile TypeScript → build/
npm run build

# Watch mode (recompiles on save)
npm run dev

# Type-check without emitting
npm run type:check

プロジェクト構成

src/
├── index.ts              # stdio entry point (CLI / npx)
├── smithery.ts           # Smithery deployment entry point
├── create-server.ts      # Server factory + SERVER_INSTRUCTIONS
├── tools/
│   ├── celebrate-kaomoji.ts
│   ├── thinking-kaomoji.ts
│   └── apologize-kaomoji.ts
├── prompts/
│   └── react-with.ts     # react_with_kaomoji prompt
├── resources/
│   └── catalog.ts        # kaomoji://catalog resource
└── data/
    ├── loader.ts          # cached JSON loader
    └── kaomoji.json       # CLI-safe kaomoji database (75+ entries)

---

テストの実行

# Run all tests once
npm test

# Watch mode
npm run test:watch

テストスイートの対象：

スイート	ファイル	テスト内容
データローダー	tests/data/loader.test.ts	JSON の読み込み、スキーマの形状、キャッシュ
CLI セーフ検証	tests/data/cli-safe.test.ts	データベースに全角文字や装飾的な Unicode が含まれていないこと
celebrate_kaomoji	tests/tools/celebrate.test.ts	ランダム性、強度、フォールバック、_instruction フィールド
thinking_kaomoji	tests/tools/thinking.test.ts	フェーズ名、mcp_server パラメーター、長さ制限
apologize_kaomoji	tests/tools/apologize.test.ts	理由コード、フォールバック、_instruction フィールド
統合テスト	tests/integration/server.test.ts	サーバー全体：ツール一覧、プロンプト、リソース、エンドツーエンドの呼び出し

すべてのテストで メモリー内 MCP トランスポートを使用するため、ネットワークも stdio も必要ありません。

---

ライセンス

このプロジェクトは GNU General Public License v3.0 のもとでライセンスされています。