Noun Project MCP Server

Instructions

Implementation Reference

• src/api.ts:134-156 (handler)

  Core handler function that executes the get_collection tool logic: fetches collection data from Noun Project API using OAuth-authenticated GET request, processes query parameters.

  async getCollection(params: GetCollectionParams) {
    const { collection_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/collection/${collection_id}${
      queryString ? `?${queryString}` : ''
    }`;
    const headers = this.oauth.getHeaders(url);
  
    const response = await this.client.get(`/v2/collection/${collection_id}`, {
      params: queryParams.toString() ? Object.fromEntries(queryParams) : undefined,
      headers,
    });
  
    return response.data;
  }

• src/api.ts:23-28 (schema)

  TypeScript interface defining input parameters for the getCollection handler.

  export interface GetCollectionParams {
    collection_id: number;
    thumbnail_size?: 42 | 84 | 200;
    include_svg?: 0 | 1;
    limit?: number;
  }

• src/tools.ts:69-97 (registration)

  MCP tool registration object including name, description, and input schema validation.

  {
    name: 'get_collection',
    description:
      'Get a collection by ID. Returns collection metadata and the icons it contains.',
    inputSchema: {
      type: 'object',
      properties: {
        collection_id: {
          type: 'number',
          description: 'The unique ID of the collection',
        },
        thumbnail_size: {
          type: 'number',
          enum: [42, 84, 200],
          description: 'Thumbnail size to return for icons (42, 84, or 200 pixels)',
        },
        include_svg: {
          type: 'number',
          enum: [0, 1],
          description: 'Set to 1 to include SVG URLs in the response',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of icons to return from the collection',
        },
      },
      required: ['collection_id'],
    },
  },

• src/index.ts:78-88 (registration)

  MCP server request handler dispatching 'get_collection' tool calls to the api.getCollection implementation.

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