Longman Dictionary MCP Server

Instructions

Implementation Reference

• src/index.ts:63-255 (handler)

  Core implementation of the get_dictionary_entry tool. Fetches HTML from Longman Dictionary Online, parses it with Cheerio to extract structured data including dictionary entries (word, pronunciation, POS, senses, examples), and verb conjugation tables (simpleForm and continuousForm). Returns FinalDictionaryJson.
  async function fetchDictionaryData(word: string): Promise<FinalDictionaryJson> { const url = `https://www.ldoceonline.com/dictionary/${encodeURIComponent(word)}`; const { data: html } = await axios.get(url, { timeout: 10000, headers: { 'User-Agent': 'Mozilla/5.0 (compatible; MCP-Server/0.1.0)', }, }); const $ = cheerio.load(html); // ========================== // 1) Extrair .dictentry (as entradas do dicionário) // ========================== const dictionaryEntries: DictionaryParsedEntry[] = []; // Para cada <span class="dictentry">... $('span.dictentry').each((_, dictentryEl) => { const dictentry = $(dictentryEl); // Dentro dele, encontramos .ldoceEntry.Entry const ldoceEntryEl = dictentry.find('.ldoceEntry.Entry').first(); if (!ldoceEntryEl || ldoceEntryEl.length === 0) { return; // pula se não achar } // Extrair "relatedTopics" const relatedTopics: string[] = []; ldoceEntryEl.find('.topics_container a.topic').each((_, topicEl) => { relatedTopics.push($(topicEl).text().trim()); }); // Extrair "head" (palavra, pronúncia, etc.) // Pode ser .frequent.Head ou .Head const headEl = ldoceEntryEl.find('.frequent.Head, .Head').first(); const extractedWord = headEl.find('.HWD').text().trim() || word; const hyphenation = headEl.find('.HYPHENATION').text().trim() || ''; const homnum = headEl.find('.HOMNUM').text().trim() || ''; const pos = headEl.find('.POS').text().trim() || ''; // Pronúncia britânica e americana const brit = headEl.find('span.brefile').attr('data-src-mp3'); const ame = headEl.find('span.amefile').attr('data-src-mp3'); // Ou extrair do .PronCodes: let textPron = ''; const pronCodes = headEl.find('.PronCodes').first(); if (pronCodes && pronCodes.length > 0) { // Montamos algo tipo "/rɒt/ (US: rɑːt)" const pronSpans = pronCodes.find('span.PRON, span.AMEVARPRON, span.neutral'); let collected = ''; pronSpans.each((i, elSpan) => { collected += $(elSpan).text(); }); textPron = collected.trim(); } // Se preferir simplificar: "/rɒt/ (US: rɑːt)" // ex: textPron = "/rɒt/ $ rɑːt/" // convert $ -> (US:) textPron = textPron.replace(/\s*\$\s*/g, '(US: ').replace(/\/\s*$/, '/)').replace(/\)\)/, ')'); if (!textPron.includes('(US:') && textPron.endsWith('/)')) { textPron = textPron.replace('/)', '/'); } // Inflections (ex. (rotted, rotting)) const inflectionsText = headEl.find('.Inflections').text().trim(); // ex. "(rotted, rotting)" let inflections: string[] = []; if (inflectionsText) { // remove parênteses const inf = inflectionsText.replace(/[()]/g, ''); // separa por vírgula inflections = inf.split(',').map(s => s.trim()).filter(Boolean); } // 2) Extrair "senses" const senses: DictionarySense[] = []; ldoceEntryEl.find('.Sense').each((_, senseEl) => { const sense = $(senseEl); const number = Number.parseInt(sense.find('.sensenum').first().text().trim(), 10) || undefined; const grammar = sense.find('.GRAM').text().trim() || undefined; const activation = sense.find('.ACTIV').text().trim() || undefined; // "Definition" pode ser um texto normal ou algo do tipo "(→ rot in hell/jail)" const definitionText = sense.find('.DEF').text().trim(); let definitionObj: string | { text: string; url: string } = definitionText; // Se a definition for algo tipo "(→ rot in hell/jail)", // transformamos em { text: "🔗 rot in hell/jail", url: ... } // Precisamos ver se há link .Crossref ou algo do tipo if (!definitionText && sense.find('.Crossref a').length > 0) { // ex: "rot in hell/jail" const crossLink = sense.find('.Crossref a').first(); const crossText = crossLink.text().trim(); const crossHref = crossLink.attr('href'); if (crossText && crossHref) { definitionObj = { text: `🔗 ${crossText}`, url: `https://www.ldoceonline.com${crossHref}` }; } } // se for algo como a .DEF vem só com → e link // ex: " → rot in hell/jail" if (definitionText.startsWith('→')) { // Tentar extrair a link const crossLink = sense.find('.Crossref a').first(); if (crossLink && crossLink.length > 0) { const crossText = crossLink.text().trim(); const crossHref = crossLink.attr('href'); definitionObj = { text: `🔗 ${crossText}`, url: `https://www.ldoceonline.com${crossHref}` }; } else { definitionObj = definitionText; } } // Se a .DEF tiver link <a>, substituímos trechos "decay" e "gradual" etc? // Faremos simples, manteremos o text. // 3) Extrair EXAMPLE const examples: DictionaryExample[] = []; sense.find('.EXAMPLE').each((_, exEl) => { const ex = $(exEl); const text = ex.text().trim(); // pegar audio se houver let audioUrl = ex.find('.speaker.exafile').attr('data-src-mp3'); if (!audioUrl) { // ou exafile audioUrl = ex.find('.speaker').attr('data-src-mp3') || undefined; } examples.push({ text, audioUrl }); }); senses.push({ number, grammar: grammar || undefined, activation: activation || undefined, definition: definitionObj, examples }); }); dictionaryEntries.push({ word, pronunciation: textPron || '', partOfSpeech: pos || '', inflections, relatedTopics, senses }); }); // ========================== // 3) Extrair a Tabela (Verb table) -> simpleForm e continuousForm // ========================== // A tabela fica dentro de <div class="verbTable"> no snippet. // Precisamos de .simpleForm e .continuousForm const simpleForm: ConjugationTable = {}; const continuousForm: ConjugationTable = {}; // Achar <div class="verbTable"> const verbTableEl = $('.verbTable').first(); if (verbTableEl && verbTableEl.length > 0) { // ============ SIMPLE FORM ============ const simpleFormEl = verbTableEl.find('table.simpleForm').first(); if (simpleFormEl && simpleFormEl.length > 0) { parseConjugationTable(simpleFormEl, simpleForm); } // ============ CONTINUOUS FORM ============ const continuousFormEl = verbTableEl.find('table.continuousForm').first(); if (continuousFormEl && continuousFormEl.length > 0) { parseConjugationTable(continuousFormEl, continuousForm); } } // Montamos o objeto final const finalJson: FinalDictionaryJson = { dictionaryEntries, simpleForm, continuousForm }; return finalJson; }
• src/index.ts:361-394 (handler)

  MCP CallToolRequestSchema handler specifically for 'get_dictionary_entry'. Validates arguments, calls fetchDictionaryData, stringifies the result to JSON, and returns it as tool response content.
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => { try { if (request.params.name !== 'get_dictionary_entry') { throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`); } const args = request.params.arguments as { word: string }; if (!args.word) { throw new McpError(ErrorCode.InvalidParams, '"word" parameter is required.'); } console.error(`[API] Searching dictionary data for word: ${args.word}`); // Busca o JSON extraído const finalJson = await fetchDictionaryData(args.word); // Retorna no "content" do MCP // Observação: finalJson é objeto, precisamos serializar para string return { content: [ { type: 'text', text: JSON.stringify(finalJson, null, 2), }, ], }; } catch (error: unknown) { if (error instanceof Error) { console.error('[Error] Failed to fetch entry:', error.message); throw new McpError(ErrorCode.InternalError, `Falha ao buscar a entrada: ${error.message}`); } console.error('[Error] Unknown error occurred'); throw new McpError(ErrorCode.InternalError, 'Falha ao buscar a entrada: Unknown error'); } });
• src/index.ts:341-358 (registration)

  Registration of the tool via ListToolsRequestSchema handler. Defines the tool name, description, and input schema.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: 'get_dictionary_entry', description: 'Busca o HTML do Longman para uma palavra e retorna JSON parseado (dictionaryEntries, simpleForm, continuousForm)', inputSchema: { type: 'object', properties: { word: { type: 'string', description: 'A palavra a ser consultada (ex: rot)', }, }, required: ['word'], }, }, ], }));
• src/index.ts:265-307 (helper)

  Helper function used by fetchDictionaryData to parse HTML conjugation tables into structured ConjugationTable objects for simpleForm and continuousForm.
  function parseConjugationTable( tableEl: cheerio.Cheerio, tableObj: ConjugationTable ) { const $table = cheerio.load(tableEl.html() || ''); let currentTense = ''; // Ex.: "Present", "Past", etc. $table('tr').each((_, trEl) => { const tr = $table(trEl); // Verifica se é um header const header = tr.find('td.header').text().trim(); if (header) { return; } if (tr.find('td.view_more, td.view_less').length > 0) { return; } // Se tiver <td class="col1">, assumimos que é um Tense const col1Value = tr.find('td.col1').text().trim(); if (col1Value) { currentTense = col1Value; if (!tableObj[currentTense]) { tableObj[currentTense] = {}; } return; } // senão, pegamos as colunas .col2 e interpretamos "subject" e "verbForm" const col2First = tr.find('td.firsts.col2, td.col2').first(); const subject = col2First.text().trim(); const col2Second = tr.find('td.col2').last(); const verbForm = col2Second.text().trim(); // Armazenamos no objeto if (currentTense && subject) { tableObj[currentTense][subject] = verbForm; } }); }
• src/index.ts:25-57 (schema)

  TypeScript interfaces defining the structure of the parsed dictionary data (input/output schema for the tool response).
  interface DictionaryExample { text: string; audioUrl?: string; } interface DictionarySense { number?: number; grammar?: string; activation?: string; definition?: string | { text: string; url: string }; examples?: DictionaryExample[]; } interface DictionaryParsedEntry { word: string; // ex.: "rot" pronunciation: string; // ex.: "/rɒt/ (US: rɑːt)" partOfSpeech: string; // ex.: "verb", "noun", etc. inflections: string[]; // ex.: ["rotted", "rotting"] relatedTopics: string[]; // ex.: ["Biology"] senses: DictionarySense[]; } interface ConjugationTable { [tense: string]: { [subject: string]: string; }; } interface FinalDictionaryJson { dictionaryEntries: DictionaryParsedEntry[]; simpleForm: ConjugationTable; continuousForm: ConjugationTable; }