over_representation_analysis

Perform over-representation analysis (ORA) to identify enriched miRNA or precursor categories in biological datasets using the miEAA platform.

Instructions

Run miEAA over-representation analysis (ORA) for miRNA or precursor.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`species`	Yes
`entity`	Yes
`ids`	Yes
`category_selection`	No
`reference_set`	No
`p_adjust`	No
`p_scope`	No
`alpha`	No
`min_hits`	No

Implementation Reference

src/handlers/over_representation_analysis_handler.ts:179-342 (handler)

The OverRepresentationAnalysisHandler class provides the core implementation of the 'over_representation_analysis' tool. It includes validation, body building for API calls, category selection parsing, and the main 'run' method that orchestrates the miEAA over-representation analysis job submission and result retrieval.

export class OverRepresentationAnalysisHandler {

  // -----------------------------------------------------
  // VALIDATION
  // -----------------------------------------------------
  validate(options: ORAOptions): string | null {
    if (!options.species) {
      return "species is required";
    }

    if (!["mirna", "precursor"].includes(options.entity)) {
      return "entity must be 'mirna' or 'precursor'";
    }

    if (!options.ids || !Array.isArray(options.ids) || options.ids.length === 0) {
      return "ids must be a non-empty array";
    }

    return null;
  }

  // -----------------------------------------------------
  // BUILD POST BODY (ORA ONLY)
  // -----------------------------------------------------
  buildBody(options: ORAOptions): any {
    const testset = options.ids.join(",");

    return {
      testset,
      categories: options.categories,
      reference: options.reference_set ?? [],
      p_adjust: options.p_adjust ?? "BH",
      adjust_scope: options.p_scope ?? "global",
      p_value: options.alpha ?? 0.05,
      min_hits: options.min_hits ?? 2
    };
  }

  // -----------------------------------------------------
  // PARSE CATEGORY SELECTION
  // -----------------------------------------------------
  parseCategorySelection(selection: string, categories: string[]): string[] {
    if (!selection || selection === "all") {
      return categories;
    }

    const chosen = new Set<string>();
    const parts = selection.split(",");

    for (let p of parts) {
      p = p.trim();

      if (p.includes("-")) {
        const [start, end] = p.split("-").map(n => parseInt(n.trim()));
        for (let i = start; i <= end; i++) {
          if (categories[i - 1]) chosen.add(categories[i - 1]);
        }
      } else {
        const num = parseInt(p);
        if (!isNaN(num) && categories[num - 1]) {
          chosen.add(categories[num - 1]);
        }
      }
    }

    return Array.from(chosen);
  }

  // -----------------------------------------------------
  // MAIN EXECUTION
  // -----------------------------------------------------
  async run(options: ORAOptions): Promise<any | MiEAAError> {

    // Validate
    const validationError = this.validate(options);
    if (validationError) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({ success: false, error: validationError })
          }
        ],
        structuredContent: {
          success: false,
          error: validationError
        }
      };
    }

    // Auto-fetch categories if needed
    if (!options.categories || options.categories.length === 0) {
      const catRes = await fetchMiEAACategories(
        options.species,
        options.entity
      );

      if ("error" in catRes) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(catRes)
            }
          ],
          structuredContent: catRes
        };
      }

      options.categories = catRes.ids;
    }

    // Apply numeric category selection
    options.categories = this.parseCategorySelection(
      options.category_selection ?? "all",
      options.categories
    );

    // Build ORA body
    const body = this.buildBody(options);

    // Start ORA job (analysis_type is FIXED to ORA)
    const startJob: MiEAAStartResponse = await startMiEAAJob(
      body,
      options.species,
      options.entity,
      "ORA"
    );

    if ("error" in startJob) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(startJob)
          }
        ],
        structuredContent: startJob
      };
    }

    const jobId = startJob.job_id;

    // Log metadata to stderr (MCP-safe)
    console.error(`ORA job started: ${jobId}`);
    console.error(
      `Result URL: https://ccb-compute2.cs.uni-saarland.de/mieaa/api/v1/enrichment_analysis/results/${jobId}/`
    );

    // Fetch final ORA results
    const results = await fetchMiEAAResults(jobId);

    // Final MCP-compliant return
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(results)
        }
      ],
      structuredContent: results
    };
  }
}

src/handlers/over_representation_analysis_handler.ts:162-177 (schema)

Type definitions for Entity and ORAOptions interface defining the input parameters for the over-representation analysis tool.

type Entity = "mirna" | "precursor";

interface ORAOptions {
  species: string;
  entity: Entity;
  ids: string[];

  category_selection?: string;
  categories?: string[];

  reference_set?: string[];
  p_adjust?: string;
  p_scope?: string;
  alpha?: number;
  min_hits?: number;
}

src/server.ts:49-49 (registration)
Instantiation of the OverRepresentationAnalysisHandler instance used for executing the tool.
```
const oraTool = new OverRepresentationAnalysisHandler();
```
src/server.ts:193-195 (registration)
Dispatch logic in the CallToolRequest handler that routes calls to 'over_representation_analysis' to the handler's run method.
```
if (name === "over_representation_analysis") {
  return await oraTool.run(args as any);
}
```

src/server.ts:102-119 (schema)

MCP tool schema registration in the ListTools response, defining name, description, and inputSchema for 'over_representation_analysis'.

  name: "over_representation_analysis",
  description: "Run miEAA over-representation analysis (ORA) for miRNA or precursor.",
  inputSchema: {
    type: "object",
    properties: {
      species: { type: "string" },
      entity: { type: "string", enum: ["mirna", "precursor"] },
      ids: { type: "array", items: { type: "string" } },
      category_selection: { type: "string" },
      reference_set: { type: "array", items: { type: "string" } },
      p_adjust: { type: "string" },
      p_scope: { type: "string" },
      alpha: { type: "number" },
      min_hits: { type: "number" }
    },
    required: ["species", "entity", "ids"]
  }
},

miEAA3 MCP Server