get_packages

Instructions

Implementation Reference

• src/api/packages.ts:66-84 (handler)

  The core handler function for the get_packages tool. Makes a GET request to the MASV API endpoint `/v1.1/teams/{teamId}/packages` with query parameters for filtering and pagination.

  async function getPackages({ page, ...params }: GetPackagesParams) {
    const url = new URL(`${MASV_BASE_URL}/v1.1/teams/${MASV_TEAM_ID}/packages`);
  
    Object.entries(params).forEach(([key, value]) => {
      if (value !== undefined) {
        url.searchParams.append(key, String(value));
      }
    });
  
    const headers = {
      "content-type": "application/json",
      "x-api-key": MASV_API_KEY,
    };
  
    const r = await fetch(url.toString(), { headers });
    const data = await r.json();
  
    return data;
  }

• src/api/packages.ts:4-62 (schema)

  Zod schema defining the input parameters for get_packages, with fields for pagination (page, limit), sorting, status filtering, name, sender, tags, date ranges, teamspaces, and extra_storage flag.

  const GetPackagesSchema = z.object({
    page: z
      .number()
      .min(1)
      .describe("Page number of paginated response. First page is 1")
      .optional(),
    limit: z
      .number()
      .min(1)
      .max(100)
      .describe("Number of records returned per page")
      .optional(),
    sort: z
      .string()
      .describe("Sort results ascending (fieldname) or descending (-fieldname)")
      .optional(),
    status: z
      .array(z.enum(["new", "finalized", "expired", "archived"]))
      .describe(
        "Select packages with status. New - package is currently uploading and not ready for view/download yet, finalized - package was uploaded and is ready for download, view, or transfer to another storage destination, expired and archived means that package was deleted and files are not available anymore",
      )
      .optional(),
    name: z.string().describe("Filter packages by name").optional(),
    sender: z.string().describe("Filter packages by sender email").optional(),
    tags: z
      .array(z.string())
      .describe(
        "Filter packages by tag id. If any of provided tag ids match package will be returned",
      )
      .optional(),
    created_at_start: z
      .string()
      .describe("Retrieve records that were created after (YYYY-MM-DDTHH:mm:SS)")
      .optional(),
    created_at_end: z
      .string()
      .describe("Retrieve records that were created before (YYYY-MM-DDTHH:mm:SS)")
      .optional(),
    teamspaces: z
      .array(z.string())
      .describe(
        "Retrieve records where teamspace id is equal to one of these values",
      )
      .optional(),
    expiry_start: z
      .string()
      .describe("Retrieve records that expire after (YYYY-MM-DDTHH:mm:SS)")
      .optional(),
    expiry_end: z
      .string()
      .describe("Retrieve records that expire before (YYYY-MM-DDTHH:mm:SS)")
      .optional(),
    extra_storage: z
      .boolean()
      .describe(
        "If true, will only include packages which will or have already incurred extended storage costs",
      )
      .optional(),
  });

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

  Registration of the 'get_packages' tool with the MCP server, binding the schema and handler into the tool system.

  server.registerTool(
    "get_packages",
    {
      description:
        "Get team packages. These are packages sent by MASV team users directly to MASV. It does not include packages sent to Portals. To get full list of packages you need to get both team packages and portal packages",
      inputSchema: GetPackagesSchema.shape,
    },
    async (args) => {
      try {
        const data = await getPackages(args);
  
        return mcpOk(data);
      } catch (error) {
        return mcpError(error);
      }
    },

• src/api/env.ts:11-14 (helper)

  Environment helper providing MASV_BASE_URL, MASV_TEAM_ID, and MASV_API_KEY used by the getPackages handler to construct the API request.

  export const MASV_BASE_URL = process.env.MASV_BASE_URL || "https://api.massive.app";
  export const MASV_TEAM_ID = process.env.MASV_TEAM_ID;
  export const MASV_API_KEY = process.env.MASV_API_KEY;
  export const MASV_ALLOW_DELETE = process.env.MASV_ALLOW_DELETE === "true";