DeepL MCP Server

Instructions

Implementation Reference

• workshops/deepl-simple-js/deepl-simple.js:88-99 (handler)

  The handler function for the 'translate-text' tool. It translates the input text to the target language using the DeepL API client, returns the translated text and detected source language, or handles errors.

  async function translateText({text, targetLang, formality}) {
    try {
      const result = await deeplClient.translateText( text, null, targetLang, { formality });
      return mcpTextContentify([
        result.text,
        'Detected source language: ' + result.detectedSourceLang
      ]);
  
    } catch (error) {
      return handleError(error);
    }
  }

• workshops/deepl-simple-js/deepl-simple.js:53-63 (registration)

  Registration of the 'translate-text' tool on the MCP server, including name, description, input schema, and handler reference.

  server.tool(
    "translate-text",
    "Translate text to a target language using the DeepL API",
    {
      text: z.string().describe("Text to translate"),
      targetLang: z.string().describe("Target language ISO-639 code (e.g. 'en-US', 'de', 'fr')"),
      formality: z.enum(formalityTypes).optional()
                  .describe("Controls whether translations should lean toward informal or formal language"),
    },
    translateText
  );

• workshops/deepl-simple-js/deepl-simple.js:56-61 (schema)

  Input schema definition using Zod for validating tool parameters: text (string), targetLang (string), and optional formality (enum).

  {
    text: z.string().describe("Text to translate"),
    targetLang: z.string().describe("Target language ISO-639 code (e.g. 'en-US', 'de', 'fr')"),
    formality: z.enum(formalityTypes).optional()
                .describe("Controls whether translations should lean toward informal or formal language"),
  },

• workshops/deepl-simple-js/deepl-simple.js:102-120 (helper)

  Helper function to format strings into MCP-compatible text content objects, used in the handler to return results.

  // Accept either a string or an array of strings, with partial error checking
  function mcpTextContentify(param) {
    if (typeof(param) != 'string' && !Array.isArray(param)) {
      throw new Error('mcpTextContentify() expects a string or an array of strings');
    }
  
    const strings = typeof(param) == 'string' ? [param] : param;
  
    const contentObjects = strings.map(
      str => ({
          type: "text",
          text: str
        })
    );
  
    return {
      content: contentObjects
    };
  }

• workshops/deepl-simple-js/deepl-simple.js:122-130 (helper)

  Helper function to handle and format errors for return in MCP format, called from the handler.

  // Finally, a helper function to pass errors back to the AI surface
  function handleError(error) {
    console.error("Error in the DeepL MCP server: ", error);
  
    const errorContentObject = mcpTextContentify([error.message]);
    errorContentObject.isError = true;
  
    return errorContentObject;
  }