Metadata-Version: 2.5
Name: gwasharmonizer-mcp
Version: 0.1.3
Summary: MCP server and CLI for agent-driven GWAS summary-statistics harmonization
Project-URL: Homepage, https://gwasharmonizer.org/
Project-URL: Documentation, https://gwasharmonizer.org/agents
Project-URL: Repository, https://github.com/MadisLemsalu/gwas-harmonize-hub
Keywords: agents,allele-alignment,bioinformatics,gwas,harmonization,liftover,mcp,summary-statistics,sumstats
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.12
Description-Content-Type: text/markdown

# GWAS Harmoniser MCP

An MCP server that lets AI agents harmonize local GWAS summary-statistics files with the strict workflow at [gwasharmonizer.org](https://gwasharmonizer.org/).

Use it when a researcher asks to harmonize or harmonise GWAS sumstats, standardize columns, align effect and non-effect alleles, handle GRCh37/GRCh38 liftover, validate rsIDs, run harmonization QC, or prepare summary statistics for meta-analysis, downstream analysis, submission, or a paper. It does not run association tests.

## Install

Install via `uv`:

```bash
uv tool install gwasharmonizer-mcp
```

Or via `pip`:
```bash
pip install gwasharmonizer-mcp
```

### Register with your AI client

**Codex:**
```bash
codex mcp add gwasharmonizer -- gwasharmonizer-mcp
```

**Claude Code:**
```bash
claude mcp add --transport stdio --scope user gwasharmonizer -- gwasharmonizer-mcp
```

By default, local inputs must be under `~/Desktop`. Files are uploaded to the configured live service for processing; raw variant rows are not returned to the agent through the MCP.

## Agent tools

- `start_harmonization`: start harmonization for a local GWAS file. Use `output_profile="strict_meta"` for a full-file `META_READY` METAL export and `download_kind="data"` when only the `.tsv.gz` output should be downloaded.
- `get_harmonization`: check progress, required confirmations, blockers, and artifact paths.
- `confirm_harmonization`: resume only with scientific metadata the user verified from authoritative study documentation.

Example request: `Harmonize ~/Desktop/study.tsv.gz for meta-analysis, verify META_READY, and download only the output file.`

See the public [agent and MCP guide](https://gwasharmonizer.org/agents) for routing terms and scientific boundaries.

### Resumable uploads (0.1.2)

Uploads use checksum-verified 8 MiB chunks when the backend supports them. Each
request has at most three transient attempts. Calling `start_harmonization` again
with the same file/options after a transfer failure resumes the retained transfer;
repeated new whole-file transfers are unnecessary. Preview completion survives a
backend restart and is polled independently of the upload connection. Changed
options can reuse retained source bytes while keeping a separate preview/job.
Older backends use the bounded multipart compatibility path. Update the installed
client with `uv tool install --force ./tools/gwasharmonizer-mcp` from the repository
root; already-running client processes need to finish/restart to load the update.
