Noun Project MCP Server

Instructions

Implementation Reference

• src/api.ts:109-129 (handler)

  The core handler function implementing the search_collections tool logic. It constructs query parameters from input, authenticates with OAuth, and fetches collection search results from the Noun Project API /v2/collection endpoint.

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

• src/tools.ts:102-128 (schema)

  MCP tool input schema defining parameters for search_collections, including query (required), optional filters like limit, blacklist, and pagination tokens.

  inputSchema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'Search term for collections (e.g., "winter", "business", "animals")',
      },
      blacklist: {
        type: 'number',
        enum: [0, 1],
        description: 'Set to 1 to remove results matching terms or IDs in blacklist',
      },
      limit: {
        type: 'number',
        description: 'Maximum number of results to return',
      },
      prev_page: {
        type: 'string',
        description: 'Token for paging to the previous page',
      },
      next_page: {
        type: 'string',
        description: 'Token for paging to the next page',
      },
    },
    required: ['query'],
  },

• src/tools.ts:98-129 (registration)

  Registration of the search_collections tool in the TOOLS array, which is returned by the ListTools handler.

  {
    name: 'search_collections',
    description:
      'Search for collections on The Noun Project. Returns a list of collections matching the search term.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search term for collections (e.g., "winter", "business", "animals")',
        },
        blacklist: {
          type: 'number',
          enum: [0, 1],
          description: 'Set to 1 to remove results matching terms or IDs in blacklist',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return',
        },
        prev_page: {
          type: 'string',
          description: 'Token for paging to the previous page',
        },
        next_page: {
          type: 'string',
          description: 'Token for paging to the next page',
        },
      },
      required: ['query'],
    },
  },

• src/index.ts:90-100 (handler)

  MCP server tool call dispatcher case for search_collections, invoking the API handler and formatting the JSON response.

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

• src/api.ts:30-36 (schema)

  TypeScript interface defining input parameters for the searchCollections method, matching the tool schema.

  export interface SearchCollectionsParams {
    query: string;
    blacklist?: 0 | 1;
    limit?: number;
    prev_page?: string;
    next_page?: string;
  }