Kaomoji

kaomoji-mcp

面向 AI Agent 的 CLI 安全颜文字，用于关键交互节点

一个 Model Context Protocol (MCP) 服务，为 AI Agent 在关键时刻提供生动的颜文字（ASCII 表情符号），例如思考、庆祝和道歉。所有颜文字均可安全用于 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 Agent 在给出答案之前会处理多个子任务。如果没有视觉提示，用户只能等到最终回复才能看到任何内容。kaomoji-mcp 通过要求 Agent 执行以下操作来解决这一问题：

• 在每个子任务开始前显示思考颜文字，让用户实时了解进度
• 任务成功完成时显示庆祝颜文字
• 未找到结果或发生错误时显示道歉颜文字

由于所有字符均为 ASCII / 兼容半角字符，因此在任何终端、IDE 面板和聊天界面中都能正确显示。

---

工具、提示词与资源

工具

工具	调用时机	关键参数
thinking_kaomoji	每个子任务或推理阶段之前	phase（字符串，最多 80 个字符）；可选的 mcp_server
celebrate_kaomoji	任务成功完成之后	intensity："subtle" / "moderate" / "intense"
apologize_kaomoji	没有结果、发生错误或用户不满意时	reason："not_found" / "error" / "dissatisfied"

thinking_kaomoji — 进度提示。每个子任务调用一次。可选的 mcp_server 参数用于显示正在委派任务的外部 MCP 服务：

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

celebrate_kaomoji — 完成信号。选择与当前情境相符的强度：

• subtle — 轻微修复、正式场合 → (^-^)
• moderate — 常规任务完成 → (^o^)/
• intense — 重大突破 → \(^∀^)/

apologize_kaomoji — 失败信号。reason 字段用于对情况进行分类：

• not_found — 搜索未返回任何结果
• error — 发生意外错误
• dissatisfied — 用户表示不满

提示词

提示词	说明
react_with_kaomoji	完整行为指南 — 加载此提示词，为 Agent 提供关于何时以及如何使用这三个工具的详细规则

资源

URI	MIME	说明
kaomoji://catalog	application/json	完整的颜文字数据库，包含所有场景、强度、状态、原因、后备字符串和双语标签

---

安装

要求

• Node.js ≥ 20

选项 A — npx（无需安装，始终获取最新版本）

无需安装。只需在 MCP 客户端配置中引用此软件包（见下文），Agent 运行时便会自动获取它。

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 的 Agent 会在连接时自动接收服务说明，并知道何时调用工具。你也可以在系统提示词中请求 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 界面操作：Settings → Cursor Settings → MCP → 点击 + Add new MCP server，并输入上面的命令。

---

VS Code + GitHub Copilot

启用 GitHub Copilot 扩展后，VS Code 1.99+ 原生支持 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"]
      }
    }
  }
}

在 Agent mode 下打开 Copilot Chat 面板，即可自动使用该服务。

---

Windsurf

配置文件位置： ~/.codeium/windsurf/mcp_config.json

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

或者通过 Windsurf 界面操作：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 许可。