kaomoji-mcp

CLI-safe kaomoji for AI Agents at key interaction points

A Model Context Protocol (MCP) server that gives AI agents expressive kaomoji (ASCII emoticons) at key moments — thinking, celebrating, and apologizing. All kaomoji are CLI-safe: no full-width characters, no decorative Unicode, no rendering surprises in any terminal.

Searching for auth middleware
(..)

All tests passed! (^o^)/

---

Table of Contents

• Why kaomoji-mcp?
• Tools, Prompts & Resources
• Installation
• Quickstart
• Configuration by Client
  • Claude Desktop
  • Claude Code (CLI)
  • Cursor
  • VS Code + GitHub Copilot
  • Windsurf
  • Zed
  • Continue.dev
  • Cline / Roo Cline
  • Smithery
• Development
• Running Tests

---

Why kaomoji-mcp?

Modern AI agents work through multiple sub-tasks before delivering an answer. Without visual indicators, the user sees nothing until the final response. kaomoji-mcp solves this by asking the agent to:

• Show a thinking kaomoji before each sub-task so the user can follow progress in real time
• Show a celebration kaomoji when a task completes successfully
• Show an apology kaomoji when results are not found or an error occurs

Because all characters are ASCII / half-width compatible, they render correctly in every terminal, IDE panel, and chat interface.

---

Tools, Prompts & Resources

Tools

Tool	When to call	Key parameter
thinking_kaomoji	Before each sub-task or reasoning phase	phase (string, max 80 chars); optional mcp_server
celebrate_kaomoji	After a task completes successfully	intensity: "subtle" / "moderate" / "intense"
apologize_kaomoji	On no-results, error, or user dissatisfaction	reason: "not_found" / "error" / "dissatisfied"

thinking_kaomoji — Progress indicator. Call once per sub-task. Accepts an optional mcp_server parameter to show which external MCP server is being delegated to:

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

celebrate_kaomoji — Completion signal. Choose intensity to match the moment:

• subtle — gentle fix, formal context → (^-^)
• moderate — regular task done → (^o^)/
• intense — major breakthrough → \(^∀^)/

apologize_kaomoji — Failure signal. The reason field classifies the situation:

• not_found — search returned no results
• error — unexpected error occurred
• dissatisfied — user expressed unhappiness

Prompt

Prompt	Description
react_with_kaomoji	Full behavior guide — load this prompt to give the agent detailed rules about when and how to use all three tools

Resource

URI	MIME	Description
kaomoji://catalog	application/json	Full kaomoji database with all scenes, intensities, states, reasons, fallback strings, and bilingual tags

---

Installation

Requirements

• Node.js ≥ 20

Option A — npx (no install, always latest)

No installation needed. Just reference the package in your MCP client config (see below) and the agent runtime will fetch it automatically.

npx kaomoji-mcp

Option B — Global install

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

Option C — Local project clone

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

Option D — Local project by npm

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

---

Quickstart

Once configured, your MCP-compatible agent will automatically receive the server instructions on connection and will know to call the tools at the right moments. You can also explicitly load the behavior guide by requesting the react_with_kaomoji prompt in your system prompt.

---

Configuration by Client

All configurations below launch the server over stdio transport. Replace node /absolute/path/to/build/index.js with npx kaomoji-mcp if you prefer to use the npm package directly.

---

Claude Desktop

Config file location:

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

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

Or, if you cloned the repo locally:

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

Restart Claude Desktop after saving. The server should appear under Settings → Developer → MCP Servers.

---

Claude Code (CLI)

Add the server to your project or user configuration:

# 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

Or edit .claude/mcp.json manually:

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

---

Cursor

Config file location (global): ~/.cursor/mcp.json
Config file location (project): <project-root>/.cursor/mcp.json

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

Or via the Cursor UI: Settings → Cursor Settings → MCP → click + Add new MCP server and enter the command above.

---

VS Code + GitHub Copilot

VS Code 1.99+ supports MCP servers natively when the GitHub Copilot extension is active.

Option 1 — Workspace config (.vscode/mcp.json):

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

Option 2 — User settings (settings.json):

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

Open the Copilot Chat panel in Agent mode and the server will be available automatically.

---

Windsurf

Config file location: ~/.codeium/windsurf/mcp_config.json

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

Or via the Windsurf UI: Windsurf Settings → Cascade → MCP Servers → click the + button.

---

Zed

Config file location: ~/.config/zed/settings.json

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

---

Continue.dev

Config file location: ~/.continue/config.json (global) or .continue/config.json (project)

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

---

Cline / Roo Cline

In VS Code, open the Cline extension sidebar → click the MCP Servers icon → Edit MCP Settings.

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

---

Smithery

This server is deployable on Smithery. The smithery.ts entry point exposes a configSchema (empty — no configuration required) and a createServer factory.

To deploy or install via Smithery CLI:

npx @smithery/cli install kaomoji-mcp

---

Development

# 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

Project Structure

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)

---

Running Tests

# Run all tests once
npm test

# Watch mode
npm run test:watch

The test suite covers:

Suite	File	What it tests
Data loader	tests/data/loader.test.ts	JSON loading, schema shape, caching
CLI-safe validation	tests/data/cli-safe.test.ts	No full-width / decorative Unicode in database
celebrate_kaomoji	tests/tools/celebrate.test.ts	Randomness, intensity, fallback, _instruction field
thinking_kaomoji	tests/tools/thinking.test.ts	Phase names, mcp_server param, length limits
apologize_kaomoji	tests/tools/apologize.test.ts	Reason codes, fallback, _instruction field
Integration	tests/integration/server.test.ts	Full server: tool list, prompt, resource, end-to-end calls

All tests use in-memory MCP transport — no network or stdio required.

---

License

This project is licensed under the GNU General Public License v3.0.