# miEAA3_MCP

An MCP (Model Context Protocol) server that integrates the **miEAA 3.x REST API** with **Claude Desktop**, exposing miEAA functionality as callable tools for microRNA and precursor enrichment analysis.

---

## Introduction

`miEAA3_MCP` provides a clean integration layer between **Claude Desktop** and the **miEAA bioinformatics platform**.  
The server is implemented in **TypeScript**, bundled as a single **Node.js ESM** entry point, and registered with Claude via MCP.

The project focuses on:
- Correct MCP protocol integration
- Robust request/response normalization
- Reliable execution of miEAA tools inside Claude Desktop

No biological logic is reimplemented; all analysis is performed by the official miEAA API.

---

## Repository Structure

```
miEAA3_mcp/
├── README.md
├── manifest.json
├── package.json
├── package-lock.json
├── tsconfig.json
├── dist/
│ ├── server.js
│ └── handlers/
│ ├── mieaa_categories_handler.js
│ ├── mieaa_mirna_precursor_converter_handler.js
│ ├── mieaa_mirbase_converter_handler.js
│ └── over_representation_analysis_handler.js
├── src/
│ ├── server.ts
│ ├── handlers/
│ │ ├── mieaa_categories_handler.ts
│ │ ├── mieaa_mirna_precursor_converter_handler.ts
│ │ ├── mieaa_mirbase_converter_handler.ts
│ │ └── over_representation_analysis_handler.ts
│ └── utils/
│ └── mieaa.ts
├── test.mjs
└── miEAA3_mcp.dxt
```

---

## Integrated Tools (Claude MCP)

The following **four miEAA tools are integrated, registered, and visible in Claude Desktop**:

### 1. Over-Representation Analysis (ORA)
**Tool:** `over_representation_analysis`

- Runs miEAA ORA for miRNA or precursor inputs
- Handles job submission, polling, and result retrieval
- Supports category-based enrichment analysis

---

### 2. List Enrichment Categories
**Tool:** `list_enrichment_categories`

- Queries available enrichment categories from miEAA
- Intended to guide category selection for ORA

---

### 3. miRNA ↔ Precursor Converter
**Tool:** `mirna_precursor_converter`

- Converts between miRNA and precursor identifiers
- Handles miEAA rate limits
- Normalizes plain-text API responses into structured output

---

### 4. miRBase Version Converter
**Tool:** `mirbase_version_converter`

- Converts miRNA identifiers between miRBase versions
- Explicitly reports converted, unchanged, and unmappable entries

---

## Environment Setup

### Prerequisites
- Node.js ≥ 18
- npm

Install dependencies:

```bash
npm install
```

---

## Build Process

The MCP server must be bundled into a **single ESM-compatible file** for Claude Desktop.

```bash
npx esbuild src/server.ts   --bundle   --platform=node   --format=esm   --target=node18   --outfile=dist/server.js   --log-level=debug
```

### Why this build step is required

- Bundles all handlers and utilities into one file
- Ensures compatibility with Claude’s Node runtime
- Resolves MCP SDK and module resolution issues

---

## Claude Desktop Integration

- The MCP server is correctly discovered and launched by Claude Desktop
- Extension folder detection issues are resolved
- MCP SDK resolution issues are resolved by the current build setup
- All four tools appear as callable tools inside Claude

No manual server startup is required when using Claude Desktop.

---

## Local Testing

```bash
node test.mjs
```

All tools execute correctly in a local Node.js environment.

---

## MCP Inspector

For protocol-level inspection and debugging:

```bash
npm install @modelcontextprotocol/inspector --save-dev
npx @modelcontextprotocol/inspector
```

## Using in Claude as `.dxt`

- Install prerequisites: **Node.js ≥ 18**, **npm**, and **Claude Desktop**
- Clone or open the `miEAA3_mcp` project directory
- Install dependencies:

  ```bash
  npm install
  ```
  
### Build the MCP server into a single ESM file:
```Linux / WSL
npx esbuild src/server.ts \
  --bundle \
  --platform=node \
  --format=esm \
  --target=node18 \
  --outfile=dist/server.js
```
```Windows (PowerShell)
npx esbuild src/server.ts `
  --bundle `
  --platform=node `
  --format=esm `
  --target=node18 `
  --outfile=dist/server.js
 ``` 
### Create the Claude extension package (.dxt)
(or use the existing .dxt file from the repository):
```Bash
zip -r miEAA3_mcp.dxt \
  manifest.json \
  package.json \
  package-lock.json \
  tsconfig.json \
  dist \
  -x "*.ts" "*.map" "*.log"
```
- Open Claude Desktop → Settings → Advanced → Install Extension
- Select the miEAA3_mcp.dxt file (from your Windows or local folder)
- Open a new Claude chat and use the miEAA tools directly
- (no manual server start required)

---

## Current Issue
At the moment, I am refining the result formatting, so the outputs are more structured and easier to use by user, while remaining MCP-compatible. The miEAA server was temporarily down during testing, but I expect to complete this today once it is reachable again.

One issue I encountered is that GSEA analysis has API endpoints but expects a different input format that is not documented on the miEAA website, which currently prevents successful execution. All other API-based tools are working as expected.

---