miEAA3 MCP Server

Instructions

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"]
    }
  },