BoldSign MCP Server

Instructions

Implementation Reference

• src/tools/templatesTools/listTemplates.ts:64-88 (handler)

  The primary handler function implementing the 'list_templates' tool. It initializes the TemplateApi, calls listTemplates with the provided parameters, transforms the result, and returns the MCP response or handles errors.

  async function listTemplatesHandler(payload: ListTemplatesSchemaType): Promise<McpResponse> {
    try {
      const templateApi = new TemplateApi();
      templateApi.basePath = configuration.getBasePath();
      templateApi.setApiKey(configuration.getApiKey());
      const templateRecords: TemplateRecords = await templateApi.listTemplates(
        payload.page,
        payload.templateType ?? undefined,
        payload.pageSize ?? undefined,
        payload.searchKey ?? undefined,
        undefined,
        payload.createdBy ?? undefined,
        payload.templateLabels ?? undefined,
        payload.startDate ?? undefined,
        payload.endDate ?? undefined,
        payload.brandIds ?? undefined,
      );
      setAsTemplate(templateRecords.result);
      return handleMcpResponse({
        data: templateRecords,
      });
    } catch (error: any) {
      return handleMcpError(error);
    }
  }

• src/tools/templatesTools/listTemplates.ts:10-49 (schema)

  Zod schema defining the input validation for the 'list_templates' tool parameters including pagination, search, filters by type, creator, labels, dates, and brands.

  const ListTemplatesSchema = z.object({
    pageSize: z.number().int().min(1).max(100),
    page: z.number().int().min(1).default(1),
    searchKey: commonSchema.OptionalStringSchema.describe(
      'Optional. A search key to filter templates by properties such as name and email address. Provides a way to refine results based on specific criteria.',
    ),
    templateType: z
      .enum(['all', 'mytemplates', 'sharedtemplate'])
      .optional()
      .nullable()
      .default('all')
      .describe(
        "Optional. Filters templates based on their type (all, mytemplates, sharedtemplate). Defaults to 'all'.",
      ),
    createdBy: z
      .array(commonSchema.EmailSchema.describe('Email address of the template creator.'))
      .optional()
      .nullable()
      .describe('Optional. Filters templates based on the email address(es) of their creators.'),
    templateLabels: z
      .array(z.string().describe('Label of the template.'))
      .optional()
      .nullable()
      .describe('Optional. Filters templates based on associated labels (tags).'),
    startDate: commonSchema.OptionalDateSchema.describe(
      'Optional. Filters templates created on or after this date (in YYYY-MM-DD format).',
    ),
    endDate: commonSchema.OptionalDateSchema.describe(
      'Optional. Filters templates created on or before this date (in YYYY-MM-DD format).',
    ),
    brandIds: z
      .array(
        commonSchema.InputIdSchema.describe(
          'The unique identifier (ID) of the brand to be used for depicting a brand.',
        ),
      )
      .optional()
      .nullable()
      .describe('Optional. Filters templates associated with the specified brand IDs.'),
  });

• src/tools/templatesTools/listTemplates.ts:53-62 (registration)

  Tool definition object that registers the 'list_templates' tool, specifying its method name ('list_templates'), description, input schema, and wrapper handler.

  export const listTemplatesToolDefinition: BoldSignTool = {
    method: ToolNames.ListTemplates.toString(),
    name: 'List templates',
    description:
      'Retrieves a paginated list of BoldSign templates with options to filter by page number, page size, search key, template type, creator, labels, creation date range, and brand IDs.',
    inputSchema: ListTemplatesSchema,
    async handler(args: unknown): Promise<McpResponse> {
      return await listTemplatesHandler(args as ListTemplatesSchemaType);
    },
  };

• src/tools/templatesTools/index.ts:6-10 (registration)

  Registration of the listTemplatesToolDefinition in the templates API tools definitions array, likely used for overall tool registration.

  export const templatesApiToolsDefinitions: BoldSignTool[] = [
    sendDocumentFromTemplateDynamicToolDefinition,
    listTemplatesToolDefinition,
    getTemplatePropertiesToolDefinition,
  ];

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

  Enum definition providing the string identifier 'list_templates' for the tool name, used in the tool method.

  ListTemplates = 'list_templates',