MCP Character Tools

Instructions

Implementation Reference

• src/tools/analysis.ts:38-94 (handler)

  The core handler function `compareTexts` that executes the tool's logic: computes letter frequencies for both texts using `letterFrequency`, determines common/unique characters, frequency differences, Jaccard similarity score, and generates a summary.

  export function compareTexts(input: CompareTextsInput): CompareTextsOutput {
    const { text1, text2, case_sensitive } = input;
    
    const freq1 = letterFrequency({
      text: text1,
      case_sensitive,
      include_spaces: false,
      include_punctuation: false,
      letters_only: true,
    });
    
    const freq2 = letterFrequency({
      text: text2,
      case_sensitive,
      include_spaces: false,
      include_punctuation: false,
      letters_only: true,
    });
  
    const chars1 = new Set(Object.keys(freq1.frequency));
    const chars2 = new Set(Object.keys(freq2.frequency));
    
    const common_characters = [...chars1].filter(c => chars2.has(c)).sort();
    const unique_to_text1 = [...chars1].filter(c => !chars2.has(c)).sort();
    const unique_to_text2 = [...chars2].filter(c => !chars1.has(c)).sort();
    
    const allChars = new Set([...chars1, ...chars2]);
    const frequency_comparison: FrequencyComparison[] = [...allChars]
      .sort()
      .map(char => ({
        char,
        count_in_text1: freq1.frequency[char] || 0,
        count_in_text2: freq2.frequency[char] || 0,
        difference: (freq1.frequency[char] || 0) - (freq2.frequency[char] || 0),
      }));
  
    // Calculate Jaccard similarity
    const intersection = common_characters.length;
    const union = allChars.size;
    const similarity_score = union > 0 ? Math.round((intersection / union) * 100) : 0;
  
    const summary = `Text1 (${text1.length} chars) and Text2 (${text2.length} chars) share ${common_characters.length} common characters. Similarity: ${similarity_score}%.`;
  
    return {
      text1,
      text2,
      text1_length: text1.length,
      text2_length: text2.length,
      case_sensitive,
      common_characters,
      unique_to_text1,
      unique_to_text2,
      frequency_comparison,
      similarity_score,
      summary,
    };
  }

• src/tools/analysis.ts:11-36 (schema)

  TypeScript interfaces defining the input (CompareTextsInput), supporting types (FrequencyComparison), and output (CompareTextsOutput) for the compare_texts tool.

  export interface CompareTextsInput {
    text1: string;
    text2: string;
    case_sensitive: boolean;
  }
  
  export interface FrequencyComparison {
    char: string;
    count_in_text1: number;
    count_in_text2: number;
    difference: number;
  }
  
  export interface CompareTextsOutput {
    text1: string;
    text2: string;
    text1_length: number;
    text2_length: number;
    case_sensitive: boolean;
    common_characters: string[];
    unique_to_text1: string[];
    unique_to_text2: string[];
    frequency_comparison: FrequencyComparison[];
    similarity_score: number;
    summary: string;
  }

• src/index.ts:377-410 (registration)

  Registration of the "compare_texts" tool using McpServer.registerTool, including Zod inputSchema validation, description, and the async handler that calls the compareTexts function and formats the MCP response.

  server.registerTool(
    "compare_texts",
    {
      title: "Compare Texts",
      description: `Compare letter frequencies between two texts.
  
  Useful for analyzing similarity or differences.
  
  Args:
    - text1 (string): First text
    - text2 (string): Second text
    - case_sensitive (boolean): Distinguish case (default: false)
  
  Returns: Common characters, unique to each, frequency comparison, similarity score.
  
  Example: compare_texts("hello", "world") → common: ['l', 'o'], unique_to_text1: ['h', 'e'], etc.`,
      inputSchema: z.object({
        text1: z.string().min(1).describe("First text"),
        text2: z.string().min(1).describe("Second text"),
        case_sensitive: z.boolean().default(false).describe("Distinguish case"),
      }).strict(),
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
    },
    async (params) => {
      const result = compareTexts({
        text1: params.text1,
        text2: params.text2,
        case_sensitive: params.case_sensitive,
      });
      return {
        content: [{ type: "text" as const, text: `${result.summary}\n\nCommon: [${result.common_characters.join(', ')}]\nOnly in text1: [${result.unique_to_text1.join(', ')}]\nOnly in text2: [${result.unique_to_text2.join(', ')}]` }],
      };
    }
  );