Reactome MCP Server

Instructions

Implementation Reference

• src/index.ts:776-876 (handler)

  The main handler function that executes the tool logic: validates input, resolves pathway ID, fetches participants from Reactome API using primary endpoint /data/pathway/{id}/participatingMolecules with fallbacks to extract from events or basic info, formats results.

  private async handleGetPathwayParticipants(args: any) {
    if (!isValidIdArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Pathway ID is required');
    }
  
    try {
      // Resolve pathway ID if it's a name
      const pathwayId = await this.resolvePathwayId(args.id);
      if (!pathwayId) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                error: `No pathway found for identifier: ${args.id}`,
                suggestion: 'Try using a Reactome stable identifier (e.g., R-HSA-1640170) or search for the pathway first'
              }, null, 2),
            },
          ],
          isError: true,
        };
      }
  
      // Try alternative approaches for getting participants
      let participants = [];
  
      try {
        // Try the working endpoint for participating molecules
        const response = await this.apiClient.get(`/data/pathway/${pathwayId}/participatingMolecules`);
        participants = response.data || [];
      } catch (error1) {
        try {
          // Alternative: get pathway details and extract participants from events
          const pathwayDetails = await this.apiClient.get(`/data/query/${pathwayId}`);
          if (pathwayDetails.data.hasEvent) {
            participants = pathwayDetails.data.hasEvent.map((event: any) => ({
              stId: event.stId || event.dbId,
              name: event.displayName || event.name,
              schemaClass: event.schemaClass,
              identifier: event.stId || event.dbId
            }));
          }
        } catch (error2) {
          // Final fallback: return pathway basic info
          const basicInfo = await this.apiClient.get(`/data/query/${pathwayId}`);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify({
                  pathwayId: pathwayId,
                  originalQuery: args.id,
                  basicInfo: {
                    name: basicInfo.data.displayName || basicInfo.data.name,
                    type: basicInfo.data.schemaClass,
                    species: basicInfo.data.species?.[0]?.displayName
                  },
                  participantCount: 0,
                  participants: 'Participants data not available via current API endpoints',
                  note: 'Use search_pathways or get_pathway_details for alternative pathway information'
                }, null, 2),
              },
            ],
          };
        }
      }
  
      const result = {
        pathwayId: pathwayId,
        originalQuery: args.id,
        participantCount: participants.length,
        participants: participants.slice(0, 50).map((participant: any) => ({
          id: participant.stId,
          name: participant.name || participant.displayName,
          type: participant.schemaClass,
          species: participant.species?.[0]?.name || participant.species?.[0]?.displayName,
          identifier: participant.identifier,
          url: `https://reactome.org/content/detail/${participant.stId}`
        }))
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error getting pathway participants: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:282-292 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and input schema.

  {
    name: 'get_pathway_participants',
    description: 'Get all molecules (proteins, genes, compounds) participating in a pathway',
    inputSchema: {
      type: 'object',
      properties: {
        id: { type: 'string', description: 'Reactome pathway stable identifier' },
      },
      required: ['id'],
    },
  },

• src/index.ts:337-338 (registration)

  Dispatch case in the CallToolRequestSchema switch statement that routes to the handler.

  case 'get_pathway_participants':
    return this.handleGetPathwayParticipants(args);

• src/index.ts:40-46 (helper)

  Input validation helper function used by the handler to validate pathway ID argument.

  const isValidIdArgs = (args: any): args is { id: string } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.id === 'string' &&
      args.id.length > 0
    );

• src/index.ts:428-456 (helper)

  Shared helper function used by the handler to resolve pathway names or identifiers to stable Reactome pathway IDs.

  private async resolvePathwayId(identifier: string): Promise<string | null> {
    // If it's already a stable identifier, return it
    if (identifier.match(/^R-[A-Z]{3}-\d+$/)) {
      return identifier;
    }
  
    // Search for the pathway by name
    try {
      const searchResponse = await this.apiClient.get('/search/query', {
        params: {
          query: identifier,
          types: 'Pathway',
          cluster: true
        }
      });
  
      if (searchResponse.data.results &&
          searchResponse.data.results.length > 0 &&
          searchResponse.data.results[0].entries &&
          searchResponse.data.results[0].entries.length > 0) {
        const resolvedId = searchResponse.data.results[0].entries[0].stId;
        return resolvedId;
      }
    } catch (error) {
      // Silently handle pathway resolution errors
    }
  
    return null;
  }