MCP Character Tools

Instructions

Implementation Reference

• src/tools/counting.ts:79-109 (handler)

  Core handler function implementing the count_letters tool logic: counts occurrences of multiple specified letters in text, returns per-letter counts, positions, and total matches.

  export function countLetters(input: CountLettersInput): CountLettersOutput {
    const { text, letters, case_sensitive } = input;
    
    const results: LetterCount[] = letters.map(letter => {
      const searchLetter = case_sensitive ? letter : letter.toLowerCase();
      const searchText = case_sensitive ? text : text.toLowerCase();
      
      const positions: number[] = [];
      for (let i = 0; i < searchText.length; i++) {
        if (searchText[i] === searchLetter) {
          positions.push(i);
        }
      }
      
      return {
        letter,
        count: positions.length,
        positions,
      };
    });
  
    const total_matches = results.reduce((sum, r) => sum + r.count, 0);
  
    return {
      text,
      letters_searched: letters,
      case_sensitive,
      results,
      total_matches,
    };
  }

• src/index.ts:90-126 (registration)

  MCP tool registration for 'count_letters', defining title, description, input schema (Zod validation), annotations, and async handler wrapper that invokes the core countLetters function and formats response.

  server.registerTool(
    "count_letters",
    {
      title: "Count Multiple Letters",
      description: `Count occurrences of multiple letters at once.
  
  Efficiently counts several letters in a single call.
  
  Args:
    - text (string): The text to analyze
    - letters (string[]): Array of letters to count
    - case_sensitive (boolean): Match case exactly (default: false)
  
  Returns: Results for each letter with counts and positions.
  
  Example: count_letters("strawberry", ["r", "s", "e"]) → r: 3, s: 1, e: 1`,
      inputSchema: z.object({
        text: z.string().min(1).describe("The text to analyze"),
        letters: z.array(z.string().length(1)).min(1).describe("Letters to count"),
        case_sensitive: z.boolean().default(false).describe("Match case exactly"),
      }).strict(),
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
    },
    async (params) => {
      const result = countLetters({
        text: params.text,
        letters: params.letters,
        case_sensitive: params.case_sensitive,
      });
      const summary = result.results
        .map(r => `'${r.letter}': ${r.count} at [${r.positions.join(', ')}]`)
        .join('\n');
      return {
        content: [{ type: "text" as const, text: `Letter counts in "${result.text}":\n${summary}\n\nTotal: ${result.total_matches}` }],
      };
    }
  );

• src/index.ts:106-110 (schema)

  Zod input schema for validating tool parameters: text, array of single letters, optional case_sensitive flag.

  inputSchema: z.object({
    text: z.string().min(1).describe("The text to analyze"),
    letters: z.array(z.string().length(1)).min(1).describe("Letters to count"),
    case_sensitive: z.boolean().default(false).describe("Match case exactly"),
  }).strict(),

• src/tools/counting.ts:59-77 (schema)

  TypeScript interfaces defining input (CountLettersInput), intermediate (LetterCount), and output (CountLettersOutput) structures for the countLetters function.

  export interface CountLettersInput {
    text: string;
    letters: string[];
    case_sensitive: boolean;
  }
  
  export interface LetterCount {
    letter: string;
    count: number;
    positions: number[];
  }
  
  export interface CountLettersOutput {
    text: string;
    letters_searched: string[];
    case_sensitive: boolean;
    results: LetterCount[];
    total_matches: number;
  }