kaomoji

Servidor MCP que fornece kaomoji entre conversas para Agentes de IA

Documentação

kaomoji-mcp

Kaomojis seguros para CLI, para Agentes de IA em pontos-chave de interação

Um servidor Model Context Protocol (MCP) que dá aos agentes de IA kaomojis expressivos (emoticons ASCII) em momentos-chave — pensando, celebrando e se desculpando. Todos os kaomojis são seguros para CLI: sem caracteres de largura total, sem Unicode decorativo, sem surpresas de renderização em qualquer terminal.

Searching for auth middleware
(..)

All tests passed! (^o^)/

Por que kaomoji-mcp?

Agentes de IA modernos trabalham em várias sub-tarefas antes de entregar uma resposta. Sem indicadores visuais, o usuário não vê nada até a resposta final. kaomoji-mcp resolve isso pedindo ao agente para:

Mostrar um kaomoji de pensamento antes de cada sub-tarefa, para que o usuário possa acompanhar o progresso em tempo real
Mostrar um kaomoji de celebração quando uma tarefa é concluída com sucesso
Mostrar um kaomoji de desculpas quando resultados não são encontrados ou ocorre um erro

Como todos os caracteres são compatíveis com ASCII / meia largura, eles são renderizados corretamente em qualquer terminal, painel de IDE e interface de chat.

Ferramentas, Prompts e Recursos

Ferramentas

Ferramenta	Quando chamar	Parâmetro-chave
`thinking_kaomoji`	Antes de cada sub-tarefa ou fase de raciocínio	`phase` (string, máx. 80 caracteres); opcional `mcp_server`
`celebrate_kaomoji`	Após uma tarefa ser concluída com sucesso	`intensity`: `"subtle"` / `"moderate"` / `"intense"`
`apologize_kaomoji`	Em caso de ausência de resultados, erro ou insatisfação do usuário	`reason`: `"not_found"` / `"error"` / `"dissatisfied"`

thinking_kaomoji — Indicador de progresso. Chame uma vez por sub-tarefa. Aceita um parâmetro opcional mcp_server para mostrar qual servidor MCP externo está sendo delegado:

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

celebrate_kaomoji — Sinal de conclusão. Escolha a intensidade para combinar com o momento:

subtle — correção sutil, contexto formal → (^-^)
moderate — tarefa regular concluída → (^o^)/
intense — grande avanço → \(^∀^)/

apologize_kaomoji — Sinal de falha. O campo reason classifica a situação:

not_found — a busca não retornou resultados
error — ocorreu um erro inesperado
dissatisfied — o usuário expressou insatisfação

Prompt

Prompt	Descrição
`react_with_kaomoji`	Guia completo de comportamento — carregue este prompt para dar ao agente regras detalhadas sobre quando e como usar as três ferramentas

Recurso

URI	MIME	Descrição
`kaomoji://catalog`	`application/json`	Banco de dados completo de kaomojis com todas as cenas, intensidades, estados, motivos, strings de fallback e tags bilíngues

Instalação

Requisitos

Node.js ≥ 20

Opção A — npx (sem instalação, sempre a versão mais recente)

Nenhuma instalação necessária. Basta referenciar o pacote na configuração do seu cliente MCP (veja abaixo) e o runtime do agente o buscará automaticamente.

npx kaomoji-mcp

Opção B — Instalação global

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

Opção C — Clone do projeto local

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

Opção D — Projeto local via npm

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

Início Rápido

Uma vez configurado, seu agente compatível com MCP receberá automaticamente as instruções do servidor na conexão e saberá chamar as ferramentas nos momentos certos. Você também pode carregar explicitamente o guia de comportamento solicitando o prompt react_with_kaomoji no seu prompt de sistema.

Configuração por Cliente

Todas as configurações abaixo iniciam o servidor via transporte stdio. Substitua node /absolute/path/to/build/index.js por npx kaomoji-mcp se preferir usar o pacote npm diretamente.

Claude Desktop

Localização do arquivo de configuração:

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

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

Ou, se você clonou o repositório localmente:

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

Reinicie o Claude Desktop após salvar. O servidor deve aparecer em Settings → Developer → MCP Servers.

Claude Code (CLI)

Adicione o servidor à configuração do seu projeto ou do usuário:

# 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

Ou edite .claude/mcp.json manualmente:

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

Cursor

Localização do arquivo de configuração (global): ~/.cursor/mcp.json
Localização do arquivo de configuração (projeto): <project-root>/.cursor/mcp.json

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

Ou pela interface do Cursor: Settings → Cursor Settings → MCP → clique em + Add new MCP server e insira o comando acima.

VS Code + GitHub Copilot

O VS Code 1.99+ suporta servidores MCP nativamente quando a extensão GitHub Copilot está ativa.

Opção 1 — Configuração do workspace (.vscode/mcp.json):

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

Opção 2 — Configurações do usuário (settings.json):

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

Abra o painel do Copilot Chat no modo Agente e o servidor estará disponível automaticamente.

Windsurf

Localização do arquivo de configuração: ~/.codeium/windsurf/mcp_config.json

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

Ou pela interface do Windsurf: Windsurf Settings → Cascade → MCP Servers → clique no botão +.

Zed

Localização do arquivo de configuração: ~/.config/zed/settings.json

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

Continue.dev

Localização do arquivo de configuração: ~/.continue/config.json (global) ou .continue/config.json (projeto)

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

Cline / Roo Cline

No VS Code, abra a barra lateral da extensão Cline → clique no ícone MCP Servers → Edit MCP Settings.

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

Smithery

Este servidor pode ser implantado no Smithery. O ponto de entrada smithery.ts expõe um configSchema (vazio — nenhuma configuração necessária) e uma fábrica createServer.

Para implantar ou instalar via CLI do Smithery:

npx @smithery/cli install kaomoji-mcp

Desenvolvimento

# 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

Estrutura do Projeto

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)

Executando Testes

# Run all tests once
npm test

# Watch mode
npm run test:watch

A suíte de testes cobre:

Suíte	Arquivo	O que testa
Carregador de dados	`tests/data/loader.test.ts`	Carregamento de JSON, formato do schema, cache
Validação de segurança para CLI	`tests/data/cli-safe.test.ts`	Sem Unicode de largura total / decorativo no banco de dados
`celebrate_kaomoji`	`tests/tools/celebrate.test.ts`	Aleatoriedade, intensidade, fallback, campo `_instruction`
`thinking_kaomoji`	`tests/tools/thinking.test.ts`	Nomes de fases, parâmetro `mcp_server`, limites de comprimento
`apologize_kaomoji`	`tests/tools/apologize.test.ts`	Códigos de motivo, fallback, campo `_instruction`
Integração	`tests/integration/server.test.ts`	Servidor completo: lista de ferramentas, prompt, recurso, chamadas de ponta a ponta

Todos os testes usam transporte MCP em memória — sem rede ou stdio necessários.

Licença

Este projeto está licenciado sob a GNU General Public License v3.0.