Reactome MCP Server

Instructions

Implementation Reference

• src/index.ts:943-1067 (handler)

  The main handler function that implements the core logic for the 'get_protein_interactions' tool. It validates input, resolves the pathway ID, fetches pathway data, proteins, and reactions from the Reactome API, constructs interaction information, and returns formatted JSON.

  private async handleGetProteinInteractions(args: any) {
    if (!isValidInteractionArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid interaction arguments');
    }
  
    try {
      // Resolve pathway ID if it's a name
      const pathwayId = await this.resolvePathwayId(args.pathwayId);
      if (!pathwayId) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                error: `No pathway found for identifier: ${args.pathwayId}`,
                suggestion: 'Try using a Reactome stable identifier (e.g., R-HSA-1640170) or search for the pathway first'
              }, null, 2),
            },
          ],
          isError: true,
        };
      }
  
      // Get basic pathway information first
      const pathwayInfo = await this.apiClient.get(`/data/query/${pathwayId}`);
  
      // Try multiple approaches to get interaction data
      let proteins = [];
      let reactions = [];
  
      try {
        // Try to get participating molecules
        const participantsResponse = await this.apiClient.get(`/data/pathway/${pathwayId}/participatingMolecules`);
        proteins = participantsResponse.data?.filter((p: any) =>
          p.schemaClass === 'EntityWithAccessionedSequence' || p.schemaClass === 'Protein'
        ) || [];
      } catch (e1) {
        // Alternative: search for proteins related to this pathway
        try {
          const searchResponse = await this.apiClient.get('/search/query', {
            params: {
              query: pathwayInfo.data.displayName || pathwayInfo.data.name,
              types: 'Protein',
              cluster: true
            }
          });
  
          if (searchResponse.data.results) {
            for (const group of searchResponse.data.results) {
              if (group.typeName === 'Protein' && group.entries) {
                proteins = group.entries.slice(0, 10); // Limit to 10 proteins
              }
            }
          }
        } catch (e2) {
          // Final fallback: extract from pathway hasEvent
          if (pathwayInfo.data.hasEvent) {
            proteins = pathwayInfo.data.hasEvent
              .filter((event: any) => event.schemaClass?.includes('Protein') || event.schemaClass?.includes('Entity'))
              .slice(0, 5);
          }
        }
      }
  
      try {
        // Try to get pathway reactions
        const reactionsResponse = await this.apiClient.get(`/data/pathway/${pathwayId}/containedEvents`);
        reactions = reactionsResponse.data?.filter((event: any) =>
          event.schemaClass === 'Reaction'
        ) || [];
      } catch (e) {
        // Extract reactions from pathway events
        if (pathwayInfo.data.hasEvent) {
          reactions = pathwayInfo.data.hasEvent
            .filter((event: any) => event.schemaClass === 'Reaction')
            .slice(0, 10);
        }
      }
  
      const interactions = {
        pathwayId: pathwayId,
        originalQuery: args.pathwayId,
        basicInfo: {
          name: pathwayInfo.data.displayName || pathwayInfo.data.name,
          type: pathwayInfo.data.schemaClass,
          species: pathwayInfo.data.species?.[0]?.displayName
        },
        proteinCount: proteins.length,
        reactionCount: reactions.length,
        proteins: proteins.slice(0, 20).map((protein: any) => ({
          id: protein.stId || protein.dbId,
          name: protein.name || protein.displayName,
          type: protein.schemaClass,
          identifier: protein.identifier
        })),
        potentialInteractions: reactions.slice(0, 15).map((reaction: any) => ({
          reactionId: reaction.stId || reaction.dbId,
          reactionName: reaction.name || reaction.displayName,
          type: reaction.schemaClass,
          reversible: reaction.reversible
        })),
        note: "Protein interactions inferred from pathway components and reactions. For detailed molecular interactions, consider using specialized protein interaction databases.",
        analysisNote: args.interactionType !== 'all' ? `Filtered for ${args.interactionType} interactions` : 'Showing all available interaction types'
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(interactions, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error getting protein interactions: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:304-319 (schema)

  The input schema definition for the 'get_protein_interactions' tool, specifying parameters pathwayId (required) and optional interactionType.

  {
    name: 'get_protein_interactions',
    description: 'Get protein-protein interactions within pathways',
    inputSchema: {
      type: 'object',
      properties: {
        pathwayId: { type: 'string', description: 'Reactome pathway stable identifier' },
        interactionType: {
          type: 'string',
          enum: ['protein-protein', 'regulatory', 'catalysis', 'all'],
          description: 'Type of interactions to retrieve (default: all)'
        },
      },
      required: ['pathwayId'],
    },
  },

• src/index.ts:341-342 (registration)

  Tool registration in the CallToolRequestSchema switch statement, dispatching calls to the handler function.

  case 'get_protein_interactions':
    return this.handleGetProteinInteractions(args);

• src/index.ts:69-77 (helper)

  Type guard and validation function specifically for 'get_protein_interactions' input arguments.

  const isValidInteractionArgs = (args: any): args is { pathwayId: string; interactionType?: string } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.pathwayId === 'string' &&
      args.pathwayId.length > 0 &&
      (args.interactionType === undefined || ['protein-protein', 'regulatory', 'catalysis', 'all'].includes(args.interactionType))
    );
  };