Omnisend MCP Server

Instructions

Implementation Reference

• src/tools/contacts/index.ts:104-125 (handler)

  The handler function that executes the logic for the 'getContact' MCP tool. It calls the API helper, filters the contact data, formats it as JSON, and handles errors by returning text content.

  async (args) => {
    try {
      const response = await getContact(args.contactId);
      
      // Filter contact data to include only defined fields
      const filteredContact = filterContactFields(response);
      
      return {
        content: [
          { 
            type: "text", 
            text: JSON.stringify(filteredContact, null, 2) 
          }
        ]
      };
    } catch (error) {
      if (error instanceof Error) {
        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
      }
      return { content: [{ type: "text", text: "An unknown error occurred" }] };
    }
  }

• src/tools/contacts/index.ts:96-102 (schema)

  JSON Schema defining the input parameters for the getContact tool, which requires a single 'contactId' string.

  {
    additionalProperties: false,
    properties: {
      contactId: { description: "Contact ID", type: "string" }
    },
    required: ["contactId"],
    type: "object"

• src/tools/contacts/index.ts:93-126 (registration)

  The server.tool call that registers the 'getContact' tool on the MCP server, including the tool name, description, input schema, and handler function.

  server.tool(
    "getContact",
    "Retrieve detailed information about a specific contact by their unique identifier.",
    {
      additionalProperties: false,
      properties: {
        contactId: { description: "Contact ID", type: "string" }
      },
      required: ["contactId"],
      type: "object"
    },
    async (args) => {
      try {
        const response = await getContact(args.contactId);
        
        // Filter contact data to include only defined fields
        const filteredContact = filterContactFields(response);
        
        return {
          content: [
            { 
              type: "text", 
              text: JSON.stringify(filteredContact, null, 2) 
            }
          ]
        };
      } catch (error) {
        if (error instanceof Error) {
          return { content: [{ type: "text", text: `Error: ${error.message}` }] };
        }
        return { content: [{ type: "text", text: "An unknown error occurred" }] };
      }
    }
  );

• src/api-resources/contacts/index.ts:35-46 (helper)

  Helper function from api-resources that performs the actual Omnisend API GET request to fetch a contact by ID and returns the Contact object.

  export const getContact = async (contactId: string): Promise<Contact> => {
    try {
      const response = await omnisendApi.get<Contact>(`/contacts/${contactId}`);
      return response.data;
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Error getting contact information: ${error.message}`);
      } else {
        throw new Error('Unknown error occurred when getting contact');
      }
    }
  };

• src/filters/contacts/index.ts:2-21 (helper)

  Helper utility function that filters and selects specific fields from the raw contact data for safe exposure in tool responses.

  export const filterContactFields = (contact: any) => {
    return {
      contactID: contact.contactID,
      email: contact.email,
      phone: contact.phone,
      firstName: contact.firstName,
      lastName: contact.lastName,
      status: contact.status,
      tags: contact.tags,
      identifiers: contact.identifiers,
      createdAt: contact.createdAt,
      updatedAt: contact.updatedAt,
      // Include added fields
      country: contact.country,
      state: contact.state,
      city: contact.city,
      gender: contact.gender,
      birthdate: contact.birthdate
    };
  };