Noun Project MCP Server

Instructions

Implementation Reference

• src/api.ts:196-218 (handler)

  Core handler function that performs the HTTP request to the Noun Project API to generate a customized download URL for the specified icon.

  async getDownloadUrl(params: DownloadIconParams) {
    const { icon_id, ...rest } = params;
    const queryParams = new URLSearchParams(
      Object.fromEntries(
        Object.entries(rest)
          .filter(([_, v]) => v !== undefined)
          .map(([k, v]) => [k, String(v)])
      )
    );
  
    const queryString = queryParams.toString();
    const url = `${BASE_URL}/v2/icon/${icon_id}/download${
      queryString ? `?${queryString}` : ''
    }`;
    const headers = this.oauth.getHeaders(url);
  
    const response = await this.client.get(`/v2/icon/${icon_id}/download`, {
      params: queryString ? Object.fromEntries(queryParams) : undefined,
      headers,
    });
  
    return response.data;
  }

• src/api.ts:43-48 (schema)

  TypeScript interface defining the input parameters for the getDownloadUrl handler, used for type safety.

  export interface DownloadIconParams {
    icon_id: number;
    color?: string;
    filetype?: 'svg' | 'png';
    size?: number;
  }

• src/tools.ts:158-185 (registration)

  Tool registration object defining the MCP tool name, description, and input schema, exported in TOOLS array for listTools.

  {
    name: 'get_download_url',
    description:
      'Get a download URL for an icon with custom color and size options. Supports SVG and PNG formats. Note: Free API access is limited to public domain icons only.',
    inputSchema: {
      type: 'object',
      properties: {
        icon_id: {
          type: 'number',
          description: 'The unique ID of the icon to download',
        },
        color: {
          type: 'string',
          description: 'Hexadecimal color value (e.g., "FF0000" for red)',
        },
        filetype: {
          type: 'string',
          enum: ['svg', 'png'],
          description: 'File format: svg or png (note: SVG does not accept size parameter)',
        },
        size: {
          type: 'number',
          description: 'For PNG only, size in pixels (minimum 20, maximum 1200)',
        },
      },
      required: ['icon_id'],
    },
  },

• src/index.ts:126-136 (registration)

  Switch case in the MCP CallToolRequest handler that routes calls to get_download_url to the api.getDownloadUrl function and formats the response.

  case 'get_download_url': {
    const result = await api.getDownloadUrl(args as any);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }