update_collaborator

Instructions

Implementation Reference

• src/tools/collaborators.ts:74-118 (handler)

  The 'update_collaborator' tool handler registration. Defines schema (collaborator_id, role, user_id, permissions, space_role_id, space_role_ids, allowed_paths, field_permissions), builds a payload object, and sends a PUT request to /collaborators/{collaborator_id} via apiPut().

  // Tool: update_collaborator
  server.tool(
    'update_collaborator',
    'Updates roles, permissions, or access paths for an existing collaborator.',
    {
      collaborator_id: z.number().describe('ID of the collaborator to update'),
      role: z.string().optional().describe('New role string'),
      user_id: z.number().optional().describe('User ID'),
      permissions: z.array(z.string()).optional().describe('List of permissions'),
      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'),
      allowed_paths: z.array(z.number()).optional().describe('List of allowed path IDs'),
      field_permissions: z.array(z.string()).optional().describe('List of field permissions'),
    },
    async ({
      collaborator_id,
      role,
      user_id,
      permissions,
      space_role_id,
      space_role_ids,
      allowed_paths,
      field_permissions,
    }) => {
      try {
        const collaborator: Record<string, unknown> = {};
        if (role !== undefined) collaborator.role = role;
        if (user_id !== undefined) collaborator.user_id = user_id;
        if (permissions !== undefined) collaborator.permissions = permissions;
        if (space_role_id !== undefined) collaborator.space_role_id = space_role_id;
        if (space_role_ids !== undefined) collaborator.space_role_ids = space_role_ids;
        if (allowed_paths !== undefined) collaborator.allowed_paths = allowed_paths;
        if (field_permissions !== undefined) collaborator.field_permissions = field_permissions;
  
        const payload = { collaborator };
        const data = await apiPut(`/collaborators/${collaborator_id}`, payload);
        return createJsonResponse(data);
      } catch (error) {
        if (error instanceof APIError) {
          return createErrorResponse(error);
        }
        throw error;
      }
    }
  );

• src/tools/collaborators.ts:78-87 (schema)

  Zod schema definitions for the 'update_collaborator' tool input parameters: collaborator_id (required number), role (optional string), user_id (optional number), permissions (optional string array), space_role_id (optional number), space_role_ids (optional number array), allowed_paths (optional number array), field_permissions (optional string array).

  {
    collaborator_id: z.number().describe('ID of the collaborator to update'),
    role: z.string().optional().describe('New role string'),
    user_id: z.number().optional().describe('User ID'),
    permissions: z.array(z.string()).optional().describe('List of permissions'),
    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'),
    allowed_paths: z.array(z.number()).optional().describe('List of allowed path IDs'),
    field_permissions: z.array(z.string()).optional().describe('List of field permissions'),
  },

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

  Registration call: registerCollaborators(server) in the registerAllTools function which registers all collaborators tools including 'update_collaborator'.

  // User management
  registerCollaborators(server);
  registerSpaceRoles(server);
  
  // Data sources
  registerDatasources(server);

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

  The registerCollaborators export function that registers all collaborator tools (retrieve_multiple_collaborators, add_collaborator, update_collaborator, delete_collaborator) with the MCP server.

  export function registerCollaborators(server: McpServer): void {
    // Tool: retrieve_multiple_collaborators
    server.tool(
      'retrieve_multiple_collaborators',
      'Retrieves a paginated list of collaborators (users) in a specified Storyblok space.',
      {
        page: z.number().optional().default(1).describe('Page number'),
        per_page: z.number().optional().default(25).describe('Items per page'),
      },
      async ({ page, per_page }) => {
        try {
          const params: Record<string, string> = {
            page: String(page ?? 1),
            per_page: String(per_page ?? 25),
          };
          const data = await apiGet('/collaborators/', params);
          return createJsonResponse(data);
        } catch (error) {
          if (error instanceof APIError) {
            return createErrorResponse(error);
          }
          throw error;
        }
      }
    );
  
    // Tool: add_collaborator
    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;
        }
      }
    );
  
    // Tool: update_collaborator
    server.tool(
      'update_collaborator',
      'Updates roles, permissions, or access paths for an existing collaborator.',
      {
        collaborator_id: z.number().describe('ID of the collaborator to update'),
        role: z.string().optional().describe('New role string'),
        user_id: z.number().optional().describe('User ID'),
        permissions: z.array(z.string()).optional().describe('List of permissions'),
        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'),
        allowed_paths: z.array(z.number()).optional().describe('List of allowed path IDs'),
        field_permissions: z.array(z.string()).optional().describe('List of field permissions'),
      },
      async ({
        collaborator_id,
        role,
        user_id,
        permissions,
        space_role_id,
        space_role_ids,
        allowed_paths,
        field_permissions,
      }) => {
        try {
          const collaborator: Record<string, unknown> = {};
          if (role !== undefined) collaborator.role = role;
          if (user_id !== undefined) collaborator.user_id = user_id;
          if (permissions !== undefined) collaborator.permissions = permissions;
          if (space_role_id !== undefined) collaborator.space_role_id = space_role_id;
          if (space_role_ids !== undefined) collaborator.space_role_ids = space_role_ids;
          if (allowed_paths !== undefined) collaborator.allowed_paths = allowed_paths;
          if (field_permissions !== undefined) collaborator.field_permissions = field_permissions;
  
          const payload = { collaborator };
          const data = await apiPut(`/collaborators/${collaborator_id}`, payload);
          return createJsonResponse(data);
        } catch (error) {
          if (error instanceof APIError) {
            return createErrorResponse(error);
          }
          throw error;
        }
      }
    );
  
    // Tool: delete_collaborator
    server.tool(
      'delete_collaborator',
      'Deletes a collaborator from a specified Storyblok space. Can delete by collaborator_id or sso_id.',
      {
        collaborator_id: z.number().describe('ID of the collaborator to delete'),
        sso_id: z.string().optional().describe('SSO ID for SSO users (alternative to collaborator_id)'),
      },
      async ({ collaborator_id, sso_id }) => {
        try {
          const identifier = sso_id ?? collaborator_id;
          const data = await apiDelete(`/collaborators/${identifier}`);
          return createJsonResponse(data);
        } catch (error) {
          if (error instanceof APIError) {
            return createErrorResponse(error);
          }
          throw error;
        }
      }
    );
  }

• src/utils/api.ts:211-222 (helper)

  The apiPut helper function used by the 'update_collaborator' handler to make the PUT HTTP request to the Storyblok Management API.

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