kaomoji

Servidor MCP que proporciona kaomoji entre conversaciones para Agentes de IA

GitHub
1

Documentación

kaomoji-mcp

Kaomoji seguros para CLI, para Agentes de IA en puntos clave de interacción

npm version License: GPL v3

Un servidor de Protocolo de Contexto de Modelo (MCP) que brinda a los agentes de IA kaomoji expresivos (emoticonos ASCII) en momentos clave: pensar, celebrar y disculparse. Todos los kaomoji son seguros para CLI: sin caracteres de ancho completo, sin Unicode decorativo, sin sorpresas de renderizado en ninguna terminal.

Searching for auth middleware
(..)

All tests passed! (^o^)/

Tabla de Contenidos

¿Por qué kaomoji-mcp?

Los agentes de IA modernos trabajan a través de múltiples sub-tareas antes de entregar una respuesta. Sin indicadores visuales, el usuario no ve nada hasta la respuesta final. kaomoji-mcp resuelve esto pidiendo al agente que:

  • Muestre un kaomoji de pensamiento antes de cada sub-tarea para que el usuario pueda seguir el progreso en tiempo real
  • Muestre un kaomoji de celebración cuando una tarea se completa con éxito
  • Muestre un kaomoji de disculpa cuando no se encuentran resultados o ocurre un error

Debido a que todos los caracteres son compatibles con ASCII / ancho medio, se renderizan correctamente en cada terminal, panel de IDE e interfaz de chat.

Herramientas, Prompts y Recursos

Herramientas

HerramientaCuándo llamarlaParámetro clave
thinking_kaomojiAntes de cada sub-tarea o fase de razonamientophase (cadena, máx. 80 caracteres); opcional mcp_server
celebrate_kaomojiDespués de que una tarea se complete con éxitointensity: "subtle" / "moderate" / "intense"
apologize_kaomojiEn ausencia de resultados, error o insatisfacción del usuarioreason: "not_found" / "error" / "dissatisfied"

thinking_kaomoji — Indicador de progreso. Llámelo una vez por sub-tarea. Acepta un parámetro opcional mcp_server para mostrar a qué servidor MCP externo se está delegando:

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

celebrate_kaomoji — Señal de finalización. Elija la intensidad para que coincida con el momento:

  • subtle — corrección suave, contexto formal → (^-^)
  • moderate — tarea regular completada → (^o^)/
  • intense — avance importante → \(^∀^)/

apologize_kaomoji — Señal de fallo. El campo reason clasifica la situación:

  • not_found — la búsqueda no devolvió resultados
  • error — ocurrió un error inesperado
  • dissatisfied — el usuario expresó descontento

Prompt

PromptDescripción
react_with_kaomojiGuía de comportamiento completa: cargue este prompt para darle al agente reglas detalladas sobre cuándo y cómo usar las tres herramientas

Recurso

URIMIMEDescripción
kaomoji://catalogapplication/jsonBase de datos completa de kaomoji con todas las escenas, intensidades, estados, razones, cadenas de respaldo y etiquetas bilingües

Instalación

Requisitos

  • Node.js ≥ 20

Opción A — npx (sin instalación, siempre la última versión)

No se necesita instalación. Simplemente haga referencia al paquete en la configuración de su cliente MCP (ver más abajo) y el tiempo de ejecución del agente lo obtendrá automáticamente.

npx kaomoji-mcp

Opción B — Instalación global

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

Opción C — Clonación local del proyecto

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

Opción D — Proyecto local mediante npm

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

Inicio Rápido

Una vez configurado, su agente compatible con MCP recibirá automáticamente las instrucciones del servidor al conectarse y sabrá llamar a las herramientas en los momentos adecuados. También puede cargar explícitamente la guía de comportamiento solicitando el prompt react_with_kaomoji en su prompt de sistema.

Configuración por Cliente

Todas las configuraciones a continuación lanzan el servidor a través del transporte stdio. Reemplace node /absolute/path/to/build/index.js con npx kaomoji-mcp si prefiere usar el paquete npm directamente.

Claude Desktop

Ubicación del archivo de configuración:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "kaomoji": {
      "command": "npx",
      "args": ["-y", "kaomoji-mcp"]
    }
  }
}

O, si clonó el repositorio localmente:

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

Reinicie Claude Desktop después de guardar. El servidor debería aparecer en Configuración → Desarrollador → Servidores MCP.

Claude Code (CLI)

Agregue el servidor a la configuración de su proyecto o usuario:

# 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

O edite .claude/mcp.json manualmente:

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

Cursor

Ubicación del archivo de configuración (global): ~/.cursor/mcp.json
Ubicación del archivo de configuración (proyecto): <project-root>/.cursor/mcp.json

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

O a través de la interfaz de Cursor: Configuración → Configuración de Cursor → MCP → haga clic en + Agregar nuevo servidor MCP e ingrese el comando anterior.

VS Code + GitHub Copilot

VS Code 1.99+ admite servidores MCP de forma nativa cuando la extensión GitHub Copilot está activa.

Opción 1 — Configuración del espacio de trabajo (.vscode/mcp.json):

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

Opción 2 — Configuración de usuario (settings.json):

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

Abra el panel de Chat de Copilot en modo Agente y el servidor estará disponible automáticamente.

Windsurf

Ubicación del archivo de configuración: ~/.codeium/windsurf/mcp_config.json

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

O a través de la interfaz de Windsurf: Configuración de Windsurf → Cascade → Servidores MCP → haga clic en el botón +.

Zed

Ubicación del archivo de configuración: ~/.config/zed/settings.json

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

Continue.dev

Ubicación del archivo de configuración: ~/.continue/config.json (global) o .continue/config.json (proyecto)

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

Cline / Roo Cline

En VS Code, abra la barra lateral de la extensión Cline → haga clic en el ícono Servidores MCP → Editar configuración de MCP.

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

Smithery

Este servidor se puede implementar en Smithery. El punto de entrada smithery.ts expone un configSchema (vacío — no se requiere configuración) y una fábrica createServer.

Para implementar o instalar a través de la CLI de Smithery:

npx @smithery/cli install kaomoji-mcp

Desarrollo

# 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

Estructura del Proyecto

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)

Ejecución de Pruebas

# Run all tests once
npm test

# Watch mode
npm run test:watch

El conjunto de pruebas cubre:

SuiteArchivoQué prueba
Cargador de datostests/data/loader.test.tsCarga de JSON, forma del esquema, almacenamiento en caché
Validación segura para CLItests/data/cli-safe.test.tsSin Unicode de ancho completo / decorativo en la base de datos
celebrate_kaomojitests/tools/celebrate.test.tsAleatoriedad, intensidad, respaldo, campo _instruction
thinking_kaomojitests/tools/thinking.test.tsNombres de fases, parámetro mcp_server, límites de longitud
apologize_kaomojitests/tools/apologize.test.tsCódigos de razón, respaldo, campo _instruction
Integracióntests/integration/server.test.tsServidor completo: lista de herramientas, prompt, recurso, llamadas de extremo a extremo

Todas las pruebas utilizan transporte MCP en memoria — no se requiere red ni stdio.

Licencia

Este proyecto está licenciado bajo la Licencia Pública General de GNU v3.0.