ProteinAtlas MCP Server

Instructions

Implementation Reference

• src/index.ts:1038-1069 (handler)

  The handler function for the 'search_by_subcellular_location' tool. Validates input using isValidSubcellularSearchArgs, constructs a search query for the Human Protein Atlas API, calls searchProteins helper, and formats the response.

  private async handleSearchBySubcellularLocation(args: any) {
    if (!isValidSubcellularSearchArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid subcellular search arguments');
    }
  
    try {
      let searchQuery = `location:"${args.location}"`;
      if (args.reliability) {
        searchQuery += ` AND reliability:"${args.reliability}"`;
      }
  
      const result = await this.searchProteins(searchQuery, args.format || 'json', undefined, args.maxResults);
      return {
        content: [
          {
            type: 'text',
            text: typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error searching by subcellular location: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:547-560 (registration)

  Tool registration in ListToolsRequestSchema response, including name, description, and input schema definition.

  {
    name: 'search_by_subcellular_location',
    description: 'Find proteins localized to specific subcellular compartments',
    inputSchema: {
      type: 'object',
      properties: {
        location: { type: 'string', description: 'Subcellular location (e.g., nucleus, mitochondria, cytosol)' },
        reliability: { type: 'string', enum: ['approved', 'enhanced', 'supported', 'uncertain'], description: 'Reliability filter' },
        format: { type: 'string', enum: ['json', 'tsv'], description: 'Output format (default: json)' },
        maxResults: { type: 'number', description: 'Maximum number of results (1-10000, default: 100)', minimum: 1, maximum: 10000 },
      },
      required: ['location'],
    },
  },

• src/index.ts:146-158 (schema)

  Type guard function for validating input arguments to the search_by_subcellular_location tool.

  const isValidSubcellularSearchArgs = (
    args: any
  ): args is { location: string; reliability?: string; format?: string; maxResults?: number } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.location === 'string' &&
      args.location.length > 0 &&
      (args.reliability === undefined || ['approved', 'enhanced', 'supported', 'uncertain'].includes(args.reliability)) &&
      (args.format === undefined || ['json', 'tsv'].includes(args.format)) &&
      (args.maxResults === undefined || (typeof args.maxResults === 'number' && args.maxResults > 0 && args.maxResults <= 10000))
    );
  };

• src/index.ts:687-688 (registration)

  Dispatch case in the main CallToolRequestSchema handler that routes to the specific tool handler.

  case 'search_by_subcellular_location':
    return this.handleSearchBySubcellularLocation(args);

• src/index.ts:717-736 (helper)

  Core helper function used by search_by_subcellular_location to query the Human Protein Atlas API.

  private async searchProteins(query: string, format: string = 'json', columns?: string[], maxResults?: number): Promise<any> {
    // Default columns if none provided - basic protein information
    const defaultColumns = ['g', 'gs', 'eg', 'gd', 'up', 'chr', 'pc', 'pe'];
    const searchColumns = columns && columns.length > 0 ? columns : defaultColumns;
  
    const params: any = {
      search: query,
      format: format,
      columns: searchColumns.join(','),
      compress: 'no',
    };
  
    const response = await this.apiClient.get('/api/search_download.php', { params });
  
    if (format === 'json') {
      return this.parseResponse(response.data, format);
    }
  
    return response.data;
  }