add_collaborator

Instructions

Implementation Reference

• src/tools/collaborators.ts:37-72 (handler)

  The add_collaborator tool handler: accepts email (required), role, space_role_id, space_role_ids, permissions, and allow_multiple_roles_creation. Builds a payload and POSTs to /collaborators/ via the API utility.

  server.tool(
    'add_collaborator',
    'Adds a collaborator to a space in Storyblok. Use either role (string) OR space_role_id (int) OR space_role_ids (list).',
    {
      email: z.string().describe('Email of the collaborator to add'),
      role: z.string().optional().describe('Role string'),
      space_role_id: z.number().optional().describe('Single space role ID'),
      space_role_ids: z.array(z.number()).optional().describe('List of space role IDs'),
      permissions: z.array(z.string()).optional().describe('List of permissions'),
      allow_multiple_roles_creation: z
        .boolean()
        .optional()
        .describe('Allow multiple roles creation'),
    },
    async ({ email, role, space_role_id, space_role_ids, permissions, allow_multiple_roles_creation }) => {
      try {
        const collaborator: Record<string, unknown> = { email };
        if (role) collaborator.role = role;
        if (space_role_id) collaborator.space_role_id = space_role_id;
        if (space_role_ids) collaborator.space_role_ids = space_role_ids;
        if (permissions) collaborator.permissions = permissions;
        if (allow_multiple_roles_creation !== undefined) {
          collaborator.allow_multiple_roles_creation = allow_multiple_roles_creation;
        }
  
        const payload = { collaborator };
        const data = await apiPost('/collaborators/', payload);
        return createJsonResponse(data);
      } catch (error) {
        if (error instanceof APIError) {
          return createErrorResponse(error);
        }
        throw error;
      }
    }
  );

• src/tools/collaborators.ts:40-50 (schema)

  Zod schema defining the input parameters for add_collaborator: email (required string), role (optional string), space_role_id (optional number), space_role_ids (optional array of numbers), permissions (optional array of strings), allow_multiple_roles_creation (optional boolean).

  {
    email: z.string().describe('Email of the collaborator to add'),
    role: z.string().optional().describe('Role string'),
    space_role_id: z.number().optional().describe('Single space role ID'),
    space_role_ids: z.array(z.number()).optional().describe('List of space role IDs'),
    permissions: z.array(z.string()).optional().describe('List of permissions'),
    allow_multiple_roles_creation: z
      .boolean()
      .optional()
      .describe('Allow multiple roles creation'),
  },

• src/tools/index.ts:68-68 (registration)

  Registration call in the main tool aggregator that registers all collaborator tools (including add_collaborator) with the MCP server.

  registerCollaborators(server);

• src/tools/collaborators.ts:10-10 (registration)

  The registerCollaborators function that registers the add_collaborator tool (and others) by calling server.tool().

  export function registerCollaborators(server: McpServer): void {

• src/utils/api.ts:195-206 (helper)

  The apiPost helper used by the add_collaborator handler to POST the collaborator payload to the Storyblok Management API.

  export async function apiPost<T = unknown>(
    path: string,
    body: unknown
  ): Promise<T> {
    const url = buildManagementUrl(path);
    const response = await fetch(url, {
      method: 'POST',
      headers: getManagementHeaders(),
      body: JSON.stringify(body),
    });
    return handleResponse<T>(response, url);
  }