Reactome MCP Server

Instructions

Implementation Reference

• src/index.ts:693-774 (handler)

  The handler function that implements the core logic for the get_pathway_hierarchy tool. It validates input, resolves the pathway ID, fetches pathway data from Reactome API, attempts to retrieve ancestor and child pathways, and returns formatted hierarchy information as JSON.

  private async handleGetPathwayHierarchy(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,
        };
      }
  
      // Get basic pathway information first
      const pathwayInfo = await this.apiClient.get(`/data/query/${pathwayId}`);
  
      // Try alternative endpoints for hierarchy
      let ancestors = [];
      let children = [];
  
      try {
        // Try to get orthologous events (related pathways)
        const orthologousResponse = await this.apiClient.get(`/data/orthologous/${pathwayId}/pathways`);
        ancestors = orthologousResponse.data || [];
      } catch (e) {
        // Try to extract hierarchy info from basic pathway data
        if (pathwayInfo.data.hasEvent) {
          children = pathwayInfo.data.hasEvent.map((event: any) => ({
            id: event.stId || event.dbId,
            name: event.displayName || event.name,
            type: event.schemaClass || 'Event'
          }));
        }
      }
  
      const hierarchy = {
        pathwayId: pathwayId,
        originalQuery: args.id,
        basicInfo: {
          name: pathwayInfo.data.displayName || pathwayInfo.data.name,
          type: pathwayInfo.data.schemaClass,
          species: pathwayInfo.data.species?.[0]?.displayName
        },
        ancestors: ancestors.length > 0 ? ancestors.slice(0, 10).map((ancestor: any) => ({
          id: ancestor.stId || ancestor.dbId,
          name: ancestor.displayName || ancestor.name,
          type: ancestor.schemaClass || 'Pathway'
        })) : 'Ancestor information not available via current API',
        children: children.length > 0 ? children.slice(0, 10) : 'Child pathway information not available via current API',
        note: 'Hierarchy data may be limited due to API endpoint availability'
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(hierarchy, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error getting pathway hierarchy: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:271-281 (schema)

  The tool schema defining the name, description, and input validation schema (requiring 'id' parameter of type string). This is part of the tools array registered with the MCP server.

  {
    name: 'get_pathway_hierarchy',
    description: 'Get hierarchical structure and parent/child relationships for a pathway',
    inputSchema: {
      type: 'object',
      properties: {
        id: { type: 'string', description: 'Reactome pathway stable identifier' },
      },
      required: ['id'],
    },
  },

• src/index.ts:335-336 (registration)

  The switch case in the MCP request handler that routes calls to 'get_pathway_hierarchy' to the specific handler method.

  case 'get_pathway_hierarchy':
    return this.handleGetPathwayHierarchy(args);

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

  Helper function used by the handler to resolve a pathway name or identifier to its Reactome stable ID via direct match or API search.

  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;
  }