kaomoji

Instructions

Implementation Reference

• src/mcp.ts:132-160 (registration)

  Registration of the 'kaomoji' MCP tool with name, description, Zod input schema, and handler function.

  server.tool(
    'kaomoji',
    'Get a kaomoji (Japanese text emoticon) by emotion or keyword. Perfect for inline text expressions.',
    {
      query: z.string().optional().describe('Emotion or keyword (e.g. "happy", "sad", "cat", "shrug"). Omit for random.'),
      category: z.string().optional().describe('Filter by category (e.g. "happy", "animals", "table-flip")'),
    },
    async ({ query, category }) => {
      if (!query && !category) {
        const k = getRandomKaomoji();
        return { content: [{ type: 'text', text: `${k.text}  — ${k.name}` }] };
      }
  
      let results = query ? searchKaomoji(query) : [];
      if (category) {
        const byCategory = getKaomojiByCategory(category);
        results = results.length > 0
          ? results.filter((r) => r.category === category)
          : byCategory;
      }
  
      if (results.length === 0) {
        return { content: [{ type: 'text', text: `No kaomoji found. Categories: ${listKaomojiCategories().join(', ')}` }] };
      }
  
      const text = results.map((k) => `${k.text}  — ${k.name} [${k.category}]`).join('\n');
      return { content: [{ type: 'text', text }] };
    }
  );

• src/mcp.ts:139-159 (handler)

  Handler logic for the 'kaomoji' tool: returns random kaomoji if no args, searches by query, filters by category, and formats results.

  async ({ query, category }) => {
    if (!query && !category) {
      const k = getRandomKaomoji();
      return { content: [{ type: 'text', text: `${k.text}  — ${k.name}` }] };
    }
  
    let results = query ? searchKaomoji(query) : [];
    if (category) {
      const byCategory = getKaomojiByCategory(category);
      results = results.length > 0
        ? results.filter((r) => r.category === category)
        : byCategory;
    }
  
    if (results.length === 0) {
      return { content: [{ type: 'text', text: `No kaomoji found. Categories: ${listKaomojiCategories().join(', ')}` }] };
    }
  
    const text = results.map((k) => `${k.text}  — ${k.name} [${k.category}]`).join('\n');
    return { content: [{ type: 'text', text }] };
  }

• src/kaomoji.ts:13-52 (helper)

  Helper functions for kaomoji data: loading from JSON, searching, filtering by category, random selection, listing categories/entries, and converting to result format.

  export async function loadKaomoji(): Promise<void> {
    const raw = await fs.readFile(KAOMOJI_PATH, 'utf-8');
    const parsed: Omit<KaomojiEntry, 'type'>[] = JSON.parse(raw);
    entries = parsed.map((e) => ({ ...e, type: 'kaomoji' as const }));
  }
  
  export function searchKaomoji(query: string): KaomojiEntry[] {
    return matchQuery(entries, query);
  }
  
  export function getKaomojiById(id: string): KaomojiEntry | undefined {
    return findById(entries, id);
  }
  
  export function getKaomojiByCategory(category: string): KaomojiEntry[] {
    return filterByCategory(entries, category);
  }
  
  export function getRandomKaomoji(): KaomojiEntry {
    return pickRandom(entries);
  }
  
  export function listKaomojiCategories(): string[] {
    return uniqueCategories(entries);
  }
  
  export function listAllKaomoji(): KaomojiEntry[] {
    return entries;
  }
  
  export function toKaomojiResult(entry: KaomojiEntry): KaomojiResult {
    return {
      id: entry.id,
      type: 'kaomoji',
      name: entry.name,
      category: entry.category,
      tags: entry.tags,
      text: entry.text,
    };
  }

• src/types.ts:17-24 (schema)

  KaomojiEntry interface: defines the structure of a kaomoji entry with id, type, name, category, tags, and text fields.

  export interface KaomojiEntry {
    id: string;
    type: 'kaomoji';
    name: string;
    category: string;
    tags: string[];
    text: string;
  }

• src/types.ts:39-46 (schema)

  KaomojiResult interface: output shape for kaomoji results, identical to KaomojiEntry minus internal details.

  export interface KaomojiResult {
    id: string;
    type: 'kaomoji';
    name: string;
    category: string;
    tags: string[];
    text: string;
  }