Reactome MCP Server

Instructions

Implementation Reference

• src/index.ts:536-627 (handler)

  The main handler function that implements the tool logic. Searches for proteins matching the gene, filters by species if provided, then fetches pathways containing that protein using Reactome API.

  private async handleFindPathwaysByGene(args: any) {
    if (!isValidGeneArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid gene arguments');
    }
  
    try {
      // First search for the gene/protein entity
      const searchResponse = await this.apiClient.get('/search/query', {
        params: {
          query: args.gene,
          types: 'Protein',
          cluster: true
        }
      });
  
      // Extract protein entries from result groups
      let proteinEntries: any[] = [];
      if (searchResponse.data.results) {
        for (const group of searchResponse.data.results) {
          if (group.typeName === 'Protein' && group.entries) {
            proteinEntries = proteinEntries.concat(group.entries);
          }
        }
      }
  
      // Filter by species if specified
      if (args.species) {
        proteinEntries = proteinEntries.filter((entry: any) =>
          Array.isArray(entry.species) ?
            entry.species.some((s: string) => s.toLowerCase().includes(args.species!.toLowerCase())) :
            entry.species?.toLowerCase().includes(args.species!.toLowerCase())
        );
      }
  
      if (proteinEntries.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                gene: args.gene,
                species: args.species || 'Homo sapiens',
                message: 'No protein entity found for this gene',
                pathways: []
              }, null, 2),
            },
          ],
        };
      }
  
      // Get the first matching protein
      const protein = proteinEntries[0];
  
      // Find pathways containing this protein
      const pathwaysResponse = await this.apiClient.get(`/data/pathways/low/entity/${protein.stId}`);
  
      const result = {
        gene: args.gene,
        protein: {
          id: protein.stId,
          name: protein.name,
          species: protein.species?.[0]?.name
        },
        pathwayCount: pathwaysResponse.data?.length || 0,
        pathways: pathwaysResponse.data?.map((pathway: any) => ({
          id: pathway.stId,
          name: pathway.name,
          species: pathway.species?.[0]?.name,
          url: `https://reactome.org/content/detail/${pathway.stId}`
        })) || []
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error finding pathways by gene: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:248-257 (schema)

  Input schema definition for the tool, specifying parameters gene (required) and optional species.

  name: 'find_pathways_by_gene',
  description: 'Find all pathways containing a specific gene or protein',
  inputSchema: {
    type: 'object',
    properties: {
      gene: { type: 'string', description: 'Gene symbol or UniProt ID (e.g., BRCA1, P04637)' },
      species: { type: 'string', description: 'Species name or taxon ID (default: Homo sapiens)' },
    },
    required: ['gene'],
  },

• src/index.ts:331-332 (registration)

  Dispatch registration in the tool call switch statement, routing calls to the handler.

  case 'find_pathways_by_gene':
    return this.handleFindPathwaysByGene(args);

• src/index.ts:49-57 (helper)

  Type guard function for validating input arguments matching the schema.

  const isValidGeneArgs = (args: any): args is { gene: string; species?: string } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.gene === 'string' &&
      args.gene.length > 0 &&
      (args.species === undefined || typeof args.species === 'string')
    );
  };