jgrants-mcp

Instructions

Implementation Reference

• index.ts:261-355 (handler)

  The handler function for the 'download_attachment' tool. It fetches the subsidy details from the API, validates the category and index, extracts the specific attachment's base64-encoded data, computes its size, and returns the file metadata along with the data in a structured response.

  case "download_attachment": {
    const args = DownloadAttachmentSchema.parse(request.params.arguments);
  
    try {
      const response = await fetch(
        `${API_BASE_URL}/subsidies/id/${args.subsidy_id}`
      );
      if (!response.ok) {
        const errorBody = await response.text();
        throw new Error(`API error: ${response.status} - ${errorBody}`);
      }
      const data = (await response.json()) as SubsidyDetailResponse;
  
      if (!data.result || data.result.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `Subsidy with ID ${args.subsidy_id} was not found.`,
            },
          ],
        };
      }
  
      const subsidyInfo = data.result[0];
  
      if (
        !subsidyInfo[args.category] ||
        !Array.isArray(subsidyInfo[args.category])
      ) {
        return {
          content: [
            {
              type: "text",
              text: `Attachment category '${args.category}' does not exist.`,
            },
          ],
        };
      }
  
      const attachments = subsidyInfo[args.category]!;
      if (args.index < 0 || args.index >= attachments.length) {
        return {
          content: [
            {
              type: "text",
              text: `Attachment index ${args.index} is invalid.`,
            },
          ],
        };
      }
  
      const attachment = attachments[args.index];
      const actualByteSize = Buffer.from(attachment.data, "base64").length;
  
      const output = {
        subsidy_id: subsidyInfo.id,
        subsidy_name: subsidyInfo.name,
        category: args.category,
        index: args.index,
        file_name: attachment.name,
        data: attachment.data,
        data_size_bytes: actualByteSize,
        encoding: "base64" as const,
      };
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                ...output,
                data: `[Base64 data: ${actualByteSize} bytes]`,
              },
              null,
              2
            ),
          },
        ],
        structuredContent: output,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error occurred: ${
              error instanceof Error ? error.message : "Unknown error"
            }`,
          },
        ],
      };
    }
  }

• index.ts:27-35 (schema)

  Zod schema used for input validation in the download_attachment tool handler.

  const DownloadAttachmentSchema = z.object({
    subsidy_id: z.string(),
    category: z.enum([
      "application_guidelines",
      "outline_of_grant",
      "application_form",
    ]),
    index: z.number().int().min(0),
  });

• index.ts:84-112 (registration)

  Registration of the download_attachment tool in the ListTools response, including its name, description, and input schema.

  {
    name: "download_attachment",
    description:
      "Download a subsidy's attachment document. Returns the file data in base64 encoding along with metadata. First call get_subsidy_detail to see the attachments array for each category (application_guidelines, outline_of_grant, application_form), then use the 'index' from attachments[n].index to download the specific file.",
    inputSchema: {
      type: "object",
      properties: {
        subsidy_id: {
          type: "string",
          description: "Subsidy ID",
        },
        category: {
          type: "string",
          enum: [
            "application_guidelines",
            "outline_of_grant",
            "application_form",
          ],
          description: "Attachment category",
        },
        index: {
          type: "integer",
          description: "Attachment index (starts from 0)",
          minimum: 0,
        },
      },
      required: ["subsidy_id", "category", "index"],
    },
  },