BoldSign MCP Server

Instructions

Implementation Reference

• src/tools/contactsTools/listContacts.ts:38-55 (handler)

  The main handler function that instantiates the BoldSign ContactsApi, calls the contactUserList method with paginated and filtered parameters, and returns the response or handles errors using utility functions.

  async function listContactsHandler(payload: ListContactsSchemaType): Promise<McpResponse> {
    try {
      const contactsApi = new ContactsApi();
      contactsApi.basePath = configuration.getBasePath();
      contactsApi.setApiKey(configuration.getApiKey());
      const contactsList: ContactsList = await contactsApi.contactUserList(
        payload.page,
        payload.pageSize ?? undefined,
        payload.searchKey ?? undefined,
        payload.contactType ?? undefined,
      );
      return handleMcpResponse({
        data: contactsList,
      });
    } catch (error: any) {
      return handleMcpError(error);
    }
  }

• src/tools/contactsTools/listContacts.ts:9-23 (schema)

  Zod input schema for the list_contacts tool, defining parameters: pageSize (1-100), page (default 1), optional searchKey, and contactType (MyContacts or AllContacts, default AllContacts).

  const ListContactsSchema = z.object({
    pageSize: z.number().int().min(1).max(100),
    page: z.number().int().min(1).default(1),
    searchKey: commonSchema.OptionalStringSchema.describe(
      'Optional. A string used to filter the contact list. The API will return contacts whose details contain this search term.',
    ),
    contactType: z
      .enum(['MyContacts', 'AllContacts'])
      .optional()
      .nullable()
      .default('AllContacts')
      .describe(
        "Optional. Filters the list of contacts based on their type. 'MyContacts' retrieves contacts specifically associated with your account, while 'AllContacts' (default) retrieves all accessible contacts within your organization.",
      ),
  });

• src/tools/contactsTools/listContacts.ts:27-36 (registration)

  Tool definition object that registers the list_contacts tool with MCP, specifying the method name, description, input schema, and a wrapper handler that delegates to the main handler.

  export const listContactsToolDefinition: BoldSignTool = {
    method: ToolNames.ListContacts.toString(),
    name: 'List contacts',
    description:
      'This tool allows you to retrieve a paginated list of contacts from your BoldSign organization. You can specify the page number to navigate through the results, the number of contacts to display per page, an optional search term to filter contacts, and the type of contacts to retrieve (your personal contacts or all organizational contacts). Contacts are primarily used to store signer details, identified by their unique email address, for use when creating and sending documents for signature within the BoldSign application.',
    inputSchema: ListContactsSchema,
    async handler(args: unknown): Promise<McpResponse> {
      return await listContactsHandler(args as ListContactsSchemaType);
    },
  };

• src/tools/contactsTools/index.ts:5-8 (registration)

  Exports an array of contacts API tool definitions, including the list_contacts tool, which is then included in higher-level tool registries.

  export const contactsApiToolsDefinitions: BoldSignTool[] = [
    getContactToolDefinition,
    listContactsToolDefinition,
  ];

• src/tools/toolNames.ts:10-17 (helper)

  Enum definition providing the string identifier 'list_contacts' used as the tool method name.

  /**
   * This tool allows you to retrieve a paginated list of contacts from your BoldSign organization.
   * You can specify the page number to navigate through the results, the number of contacts to display per page,
   * an optional search term to filter contacts, and the type of contacts to retrieve (your personal contacts or all organizational contacts).
   * Contacts are primarily used to store signer details, identified by their unique email address,
   * for use when creating and sending documents for signature within the BoldSign application.
   */
  ListContacts = 'list_contacts',