get_portals

Instructions

Implementation Reference

• src/api/portals.ts:40-66 (handler)

  The getPortals function that implements the tool logic. It constructs a URL with query parameters (page, limit, sort, and filters like name, subdomain, tags, teamspaces), then fetches data from the MASV API and returns the JSON response.

  async function getPortals({ page, limit, sort, ...params }: GetPortalsParams) {
      const url = new URL(`${MASV_BASE_URL}/v1.1/teams/${MASV_TEAM_ID}/portals`);
  
      if (page !== undefined) url.searchParams.append("page", String(page));
      if (limit !== undefined) url.searchParams.append("limit", String(limit));
      if (sort !== undefined) url.searchParams.append("sort", sort);
  
      Object.entries(params).forEach(([key, value]) => {
          if (value !== undefined) {
              if (Array.isArray(value)) {
                  value.forEach((v) => url.searchParams.append(key, String(v)));
              } else {
                  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/portals.ts:4-36 (schema)

  The GetPortalsSchema Zod schema defining input parameters: page (number, min 1), limit (number, 1-100), sort (enum of name/-name/created_at/-created_at/active/-active), name, subdomain, tags (array of strings), and teamspaces (array of strings).

  const GetPortalsSchema = 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
          .enum(["name", "-name", "created_at", "-created_at", "active", "-active"])
          .describe(
              "Sort results by field. Use field name for ascending order or prefix with '-' for descending (e.g., 'name' or '-created_at')",
          )
          .optional(),
      name: z.string().describe("Filter portals by name").optional(),
      subdomain: z.string().describe("Filter portals by subdomain").optional(),
      tags: z
          .array(z.string())
          .describe(
              "Filter portals by tag id. If any of provided tag ids match portal will be returned",
          )
          .optional(),
      teamspaces: z
          .array(z.string())
          .describe(
              "Retrieve records where teamspace id is equal to one of these values",
          )
          .optional(),
  });

• src/index.ts:316-331 (registration)

  Registration of the 'get_portals' tool with the MCP server. Registers the tool name, description, input schema (from GetPortalsSchema.shape), and handler that calls getPortals(args) and returns the result via mcpOk.

  server.registerTool(
    "get_portals",
    {
      description:
        "Get list of portals that belong to the team. Portals are used to collect files from external users. Each portal has a unique subdomain and can be configured with various settings like upload and download password, file type restrictions, connected integrations, metadata forms, etc.",
      inputSchema: GetPortalsSchema.shape,
    },
    async (args) => {
      try {
        const data = await getPortals(args);
  
        return mcpOk(data);
      } catch (error) {
        return mcpError(error);
      }
    },

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

  The MASV_BASE_URL, MASV_TEAM_ID, and MASV_API_KEY environment variables used by the getPortals handler to construct the API request URL and headers.

  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";

• src/mcp-responses.ts:1-10 (helper)

  The mcpOk helper function used by the tool handler to format successful responses as MCP content.

  export function mcpOk(data: object | string) {
    return {
      content: [
        {
          type: "text" as const,
          text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
        },
      ],
    };
  }