data-aggregator-mcp 0.11.0__tar.gz

data_aggregator_mcp-0.11.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run pytest -q

data_aggregator_mcp-0.11.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish
+on:
+  release:
+    types: [published]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VER=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$VER" ]; then
+            echo "Release tag '$TAG' != pyproject version '$VER'"; exit 1
+          fi
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  pypi-publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

data_aggregator_mcp-0.11.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/

data_aggregator_mcp-0.11.0/CHANGELOG.md

@@ -0,0 +1,223 @@
+# Changelog
+
+## [0.11.0] - 2026-05-29
+
+### Added
+
+- `fetch(extract=true)` — opt-in unpacking of downloaded zip/tar archives,
+  guarded against path-traversal and runaway extracted size.
+- `fetch` integrity check — an unverified `pdf`/`xml` download whose body is
+  HTML (a login/paywall page) now fails loud instead of saving a bogus file.
+- `resolve` of a Zenodo DOI via DataCite now populates `files[]` (delegates to
+  the native Zenodo adapter); such ids are fetchable.
+- BioProject `resolve` attaches `links[]` to its SRA runs.
+- PubMed `resolve` populates the article abstract (`description`) and, for
+  PMC open-access records, `access`/`license` (from EuropePMC/Unpaywall).
+- `list_sources` reports per-source fetchability, id examples, and the
+  `organism` filter.
+
+### Fixed
+
+- HTTP boundary now fully honors the fail-loud contract: transport-level errors
+  (connect/read/timeout) and malformed HTTP-200 bodies (NCBI throttle envelopes)
+  are retried and surface as a typed `DataAggregatorError`, on both the
+  search/resolve path (`_http`) and the `fetch` streaming path.
+
+## [0.10.0] - 2026-05-29
+
+### Added
+
+- Literature `resolve` (`pubmed:`/`openaire:`) attaches an open-access full-text
+  file via an EuropePMC `fullTextXML` → Unpaywall `url_for_pdf` cascade (first
+  hit wins; `FileEntry.source` labels the origin). Enrichment — fails soft.
+- `DataResource.identifiers` — normalized `{pmid, pmcid, doi}` cross-identifiers.
+  PubMed gets them free from esummary; OpenAIRE via the NCBI ID Converter.
+- `FileEntry.source` — provenance label for an attached file.
+- `pubmed:`/`openaire:` are now fetchable: `fetch` streams open-access full text
+  (unverified — no upstream checksum, like GEO). Fails loud when a paper has no
+  open full text.
+
+### Changed
+
+- New env var `UNPAYWALL_EMAIL` enables the Unpaywall fallback leg (the EuropePMC
+  leg needs no key). `NCBI_EMAIL`/`UNPAYWALL_EMAIL` is forwarded to NCBI idconv.
+
+### Notes
+
+- Cascade deviates from the umbrella spec's literal "PMC → EuropePMC → Unpaywall":
+  PMC's machine download is tgz-over-FTP (not HTTPS-fetchable), and EuropePMC
+  already serves the PMC OA subset as HTTPS XML — so the dedicated PMC leg is
+  dropped. Honors the spec's intent (open full text, first hit wins).
+- No MeSH (ceded to the openalex MCP). Full text is open-access only; paywalled
+  content is never bypassed.
+
+## [0.9.0] - 2026-05-29
+
+### Added
+
+- `resolve(id, cite=<format>)` renders a citation onto the record — `bibtex`,
+  `ris`, `csl-json`, or any CSL style name (`apa`, `mla`, `vancouver`, …). DOI
+  records use DOI content negotiation (CrossRef + DataCite); non-DOI records
+  produce CSL-JSON from metadata. Default off; failures degrade quietly.
+- `DataResource.access` — normalized access status
+  (`open`/`embargoed`/`restricted`/`closed`/`unknown`), populated from Zenodo
+  `access_right`, OpenAIRE `bestAccessRight`, and an open-license signal on
+  DataCite rights.
+- `DataResource.citation` — holds the rendered citation when `cite=` is used.
+
+### Changed
+
+- OpenAIRE records now carry `license` (from the deposit instance) and `access`.
+
+### Notes
+
+- PMC license/access for `pubmed:` records is deferred to Phase 9 (bundled with
+  PMC full-text retrieval). GEO/SRA/BioProject expose no rights → `access` stays
+  null honestly.
+
+## [0.8.0] - 2026-05-29
+
+### Added
+
+- DataCite-repo fetch: resolving a DataCite DOI now attaches `files[]` from the
+  host repo's native API — **Figshare** (md5), **Dataverse** (Harvard default,
+  `DATAVERSE_BASE_URL` override; md5), **OSF** (osfstorage, paginated; md5), all
+  fetchable and checksum-verified. **Dryad** is manifest-only (names/sizes/
+  sha-256) — its downloads are token/bot-challenge gated, so it is excluded from
+  the fetch allowlist and fetching a Dryad DOI fails loud.
+- New per-repo resolver modules: `figshare.py`, `dataverse.py`, `osf.py`, `dryad.py`.
+
+### Changed
+
+- The fetch allowlist accepts `datacite:` ids; fetchability is then decided
+  post-resolve from the detected host repo (`_DATACITE_FETCHABLE`).
+
+### Fixed
+
+- DataCite source detection now recognizes Harvard Dataverse (client id
+  `gdcc.harvard-dv`, which contains no "dataverse" substring).
+
+## [0.7.0] - 2026-05-29
+
+### Added
+
+- Omics fetch: `fetch` now downloads SRA FASTQ files (via the ENA manifest,
+  md5-verified) and GEO supplementary files (parsed from the GEO `suppl/`
+  directory index; unverified — NCBI exposes no checksums there).
+- New `geo.py` supplementary-file resolver; `geo:` resolves now populate
+  `files[]`. A GEO record with no `suppl/` directory (HTTP 404) degrades to
+  `files=[]` rather than failing.
+
+### Changed
+
+- The `fetch` tool resolves through `router.resolve` (source-agnostic) instead
+  of a hardcoded Zenodo path; the `_FETCHABLE_SOURCES` allowlist now includes
+  `sra:` and `geo:`.
+
+## [0.6.0] - 2026-05-29
+
+### Added
+
+- Packaging for publication: `python -m data_aggregator_mcp` entry point,
+  complete `[project.urls]` + `keywords`, Beta classifier.
+- `server.json` for the official MCP registry
+  (`io.github.musharna/data-aggregator-mcp`) + the `mcp-name:` ownership marker
+  in the README.
+- GitHub Actions: `ci.yml` (pytest + ruff, Python 3.11/3.12) and `publish.yml`
+  (Release-triggered PyPI upload via OIDC trusted publishing — no stored token).
+- `PUBLISH.md` runbook and user-facing install/use docs (`uvx`, `pip`,
+  `claude mcp add`).
+
+### Notes
+
+- Prepare-to-the-gate: the public GitHub repo, the real PyPI upload, and the
+  registry submission are documented manual steps, not executed here.
+- HTTP transport remains deferred — distribution is local stdio via PyPI/`uvx`.
+
+## [0.5.0] - 2026-05-28
+
+### Added
+
+- Unifying layer: NCBI-Taxonomy-backed **synonym expansion** on `search`. New
+  optional `organism` param — resolves to a taxid and ANDs the query with the
+  canonical name + synonyms (e.g. `Orobanche aegyptiaca` also matches
+  `Phelipanche aegyptiaca`, taxid 99112). The expansion is echoed in
+  `SearchResult.taxon_expansion`.
+- **Organism normalization**: results/resolved records gain `taxa[]`
+  (`{taxid, name}`) derived from raw `organism[]` via NCBI Taxonomy; raw strings
+  are preserved.
+- **Cross-links**: a `described_in` → `plant-genomics:taxid:<n>` link is attached
+  for Viridiplantae (plant) taxa, the seam to the sibling `plant-genomics-mcp`.
+
+### Notes
+
+- No new search source and no new tool — Phase 5 is a taxonomy module plus a
+  post-merge enrichment pass. `fetch` is unchanged (Zenodo-only).
+- Enrichment incurs zero taxonomy calls for records without an organism. A
+  taxonomy outage surfaces in `errors["taxonomy"]` on `search` (never silently
+  dropped) and degrades gracefully on `resolve`.
+
+## [0.4.0] - 2026-05-28
+
+### Added
+
+- Unified `literature` source: PubMed + OpenAIRE publication discovery, fanned
+  out in parallel and merged. Registered as a fourth `search` source.
+- Resolve-time paper→data links: resolving a `pubmed:` id attaches `links[]` to
+  `sra:`/`geo:`/`bioproject:` ids via NCBI elink; resolving an `openaire:` id
+  attaches `datacite:` links via the ScholeXplorer Scholix API. Publication↔
+  publication citation edges are dropped — that is the standalone openalex MCP's
+  job, not ours.
+
+### Notes
+
+- Literature is discovery-only — `fetch` stays Zenodo-only and fails loud for
+  `pubmed:`/`openaire:` ids.
+- OpenAIRE paper→dataset Scholix links are sparse (most paper edges are
+  citations, which are dropped); the PubMed→GEO/SRA elink path is the reliable
+  paper→data bridge. OpenAIRE's contribution is discovery breadth.
+
+## [0.3.0] - 2026-05-28
+
+### Added
+
+- Unified NCBI omics source: GEO + SRA + BioProject discovery via E-utilities,
+  fanned out internally and merged. Registered as a third `search` source.
+- ENA filereport FASTQ manifest attached on `resolve` of an `sra:` id (direct
+  https URLs).
+- Optional `NCBI_API_KEY` env var to raise the NCBI rate limit (3→10 req/s).
+- Shared round-robin `_merge.interleave` (extracted from the router) so the
+  omics fan-out reuses fair merging.
+
+### Notes
+
+- Omics fetch is deferred — `fetch` remains Zenodo-only and fails loud for omics
+  ids. GEO/BioProject are discovery-only (no file manifest in this phase).
+
+## [0.2.0] - 2026-05-28
+
+### Added
+
+- DataCite discovery adapter — one query spans every DataCite client (Dryad,
+  Figshare, Dataverse, OSF, Mendeley, …); metadata-only, so resources carry no
+  file manifest.
+- Multi-source router: `search` fans out across Zenodo + DataCite in parallel,
+  round-robin merges results so the page limit never starves a later source,
+  dedups by DOI (native fetch backends win over DataCite metadata), and surfaces
+  per-source failures in `errors{}` instead of silently dropping a backend.
+- `search` `sources` filter to restrict fan-out (e.g. `["datacite"]`).
+- Shared `compact()` helper in `models` (extracted from the Zenodo adapter).
+
+### Changed
+
+- `resolve` routes by id shape (`zenodo:` / bare id / `datacite:` / bare DOI).
+- `fetch` is Zenodo-only in Phase 2 and fails loud (`FetchNotSupportedError`)
+  for discovery-only sources; per-repo fetch adapters come in a later phase.
+
+## [0.1.0] - 2026-05-28
+
+### Added
+
+- Initial MCP server: search/resolve/fetch/list_sources over Zenodo.
+- Normalized DataResource model; stream-to-disk fetch with max_bytes guard,
+  checksum verification, and provenance sidecar.

data_aggregator_mcp-0.11.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaret Arnold
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data_aggregator_mcp-0.11.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: data-aggregator-mcp
+Version: 0.11.0
+Summary: Research-data acquisition MCP — find and fetch datasets across archives, omics registries, and literature
+Project-URL: Homepage, https://github.com/musharna/data-aggregator-mcp
+Project-URL: Repository, https://github.com/musharna/data-aggregator-mcp
+Project-URL: Issues, https://github.com/musharna/data-aggregator-mcp/issues
+Author-email: Jaret Arnold <mjarnold1998@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bioinformatics,datacite,datasets,geo,mcp,model-context-protocol,ncbi,research-data,sra,zenodo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🔎 data-aggregator-mcp
+
+**One MCP server to find and fetch research data across archives, omics
+registries, and literature — behind a single normalized model.**
+
+[![PyPI](https://img.shields.io/pypi/v/data-aggregator-mcp.svg)](https://pypi.org/project/data-aggregator-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/data-aggregator-mcp.svg)](https://pypi.org/project/data-aggregator-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/musharna/data-aggregator-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/musharna/data-aggregator-mcp/actions/workflows/ci.yml)
+
+`search` one query across **Zenodo, DataCite** (Dryad / Figshare / Dataverse /
+OSF / Mendeley), **NCBI omics** (GEO / SRA / BioProject), and **literature**
+(PubMed / OpenAIRE) — deduplicated, normalized, and cross-linked. `resolve` any
+hit to its file manifest, citation, and the data it points at. `fetch` it to
+disk with checksum verification.
+
+mcp-name: io.github.musharna/data-aggregator-mcp
+
+<p align="center">
+  <img src="examples/assets/demo.svg"
+       alt="data-aggregator-mcp stdio demo — initialize, tools/list (search, resolve, fetch, list_sources), and a live list_sources call showing the four wired sources"
+       width="820">
+</p>
+
+## ✨ Why this
+
+Most data MCPs wrap a single source. This one **unifies** them behind four tools
+and one `DataResource` model, so an agent searches once and gets back comparable
+records:
+
+- **Multi-domain, one model** — generalist archives + raw omics + literature,
+  deduplicated by DOI (the fetchable record wins over bare metadata).
+- **Taxonomy synonym expansion** — `organism="Orobanche aegyptiaca"` also matches
+  `Phelipanche aegyptiaca` (NCBI Taxonomy), so a species rename doesn't cost you
+  results.
+- **Paper → data bridge** — resolve a paper and get links to the GEO / SRA /
+  BioProject / DataCite records it produced.
+- **Verified fetch** — streams to disk with md5 verification where the source
+  exposes a checksum, optional archive unpacking, and a fail-loud integrity
+  sniff that rejects an HTML paywall page served as a "PDF".
+- **Citations, access & full text** — render a citation in any CSL style, get
+  normalized access/license, and pull open-access full text — all in one
+  `resolve`.
+
+## ⚡ Quickstart
+
+Run with no install:
+
+```bash
+uvx data-aggregator-mcp
+```
+
+Register with Claude Code:
+
+```bash
+claude mcp add data-aggregator -- uvx data-aggregator-mcp
+```
+
+A typical agent flow:
+
+```text
+search("drought stress RNA-seq", organism="Sorghum bicolor")
+  → [ geo:GSE..., sra:SRX..., zenodo:..., pubmed:... ]   # deduped, taxa-normalized
+
+resolve("sra:SRX079566")
+  → DataResource{ files: [ENA FASTQ urls…], access: "open", taxa: [...] }
+
+fetch("sra:SRX079566", dest="./data")
+  → ["./data/SRX079566_1.fastq.gz", …]                   # md5-verified
+```
+
+<details>
+<summary>Other ways to run (pip, python -m, raw client config)</summary>
+
+```bash
+pip install data-aggregator-mcp
+data-aggregator-mcp        # or: python -m data_aggregator_mcp
+```
+
+Add to a client's MCP config (e.g. Claude Desktop `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "data-aggregator": {
+      "command": "uvx",
+      "args": ["data-aggregator-mcp"],
+      "env": { "NCBI_API_KEY": "your-optional-key" }
+    }
+  }
+}
+```
+
+</details>
+
+## 🗂️ Sources
+
+| Source                       | Discover |       Fetch       |     Checksum     |
+| ---------------------------- | :------: | :---------------: | :--------------: |
+| Zenodo                       |    ✅    |        ✅         |       md5        |
+| DataCite → Figshare          |    ✅    |        ✅         |       md5        |
+| DataCite → Dataverse         |    ✅    |        ✅         |       md5        |
+| DataCite → OSF               |    ✅    |        ✅         |       md5        |
+| DataCite → Dryad             |    ✅    |  manifest only¹   | sha-256 (listed) |
+| DataCite → Mendeley & others |    ✅    |         —         |        —         |
+| NCBI SRA                     |    ✅    |  ✅ (ENA FASTQ)   |       md5        |
+| NCBI GEO                     |    ✅    |   ✅ (`suppl/`)   |      none²       |
+| NCBI BioProject              |    ✅    |    → SRA links    |        —         |
+| PubMed / OpenAIRE            |    ✅    | ✅ (OA full text) |      none²       |
+
+¹ Dryad downloads are token / bot-challenge gated, so `fetch` fails loud;
+`resolve` still lists the files.
+² No upstream checksum — `fetch` verifies content-type instead (rejects an HTML
+page served in place of a binary).
+
+## 🛠️ Tools
+
+### `search(query, size?, sources?, organism?)`
+
+Fan out across all wired sources in parallel and return compact `DataResource`
+records, deduped by DOI. Per-source failures land in `errors{}` — never silently
+dropped.
+
+- `organism` — expand the query with NCBI-Taxonomy synonyms; the expansion is
+  echoed in `taxon_expansion`, and results carry normalized `taxa[]`
+  (`{taxid, name}`) plus a `described_in` link to plant-genomics-mcp for plant
+  taxa.
+- `sources` — restrict the fan-out, e.g. `["omics"]`.
+- `size` — max results (1–50).
+
+### `resolve(id)`
+
+Full record + files manifest. Routes by id shape — `zenodo:7654321`, a bare DOI,
+`datacite:10.5061/dryad.x`, an omics id (`sra:SRX079566`, `geo:GSE332789`,
+`bioproject:PRJNA1468572`), or a literature id (`pubmed:34320281`,
+`openaire:<id>`). Attaches, where available:
+
+- **`files[]`** — ENA FASTQ manifest (SRA), GEO `suppl/`, or the host repo's
+  native manifest (Figshare / Dataverse / OSF / Dryad).
+- **`links[]`** — paper → data: `pubmed:` → `sra:` / `geo:` / `bioproject:` (NCBI
+  elink); `openaire:` → `datacite:` (ScholeXplorer Scholix).
+- **`access` / `license`** — normalized status
+  (`open` / `embargoed` / `restricted` / `closed` / `unknown`) and license where
+  the source exposes it.
+- **`identifiers`** — normalized `{pmid, pmcid, doi}`, plus an open-access
+  full-text `FileEntry` (EuropePMC XML, or an Unpaywall PDF fallback) for papers.
+- **`citation`** — pass `cite=<format>`: `bibtex`, `ris`, `csl-json`, or any CSL
+  style name (`apa`, `mla`, `vancouver`, …). DOI records use content
+  negotiation; others render CSL-JSON from metadata. Off by default; failures
+  degrade quietly.
+
+### `fetch(id, dest?, files?, max_bytes?, force?, extract?)`
+
+Download files to disk and return their paths. Streams under a `max_bytes` guard
+(`force` to override) with md5 verification wherever a checksum exists.
+
+- `files` — restrict to a subset of the resolved manifest.
+- `extract` — unpack downloaded zip / tar archives in place, guarded against
+  path traversal and runaway extracted size. Off by default.
+- Unverified fetches (GEO `suppl/`, literature full text) get a content-type
+  sniff that fails loud if a declared binary is actually an HTML page.
+- Fetchable: **Zenodo**, **SRA**, **GEO**, DataCite-hosted **Figshare** /
+  **Dataverse** / **OSF**, and **literature** open-access full text. **Dryad**
+  and other DataCite repos are discovery-only and raise
+  `FetchNotSupportedError`.
+
+### `list_sources()`
+
+Wired sources with their capabilities — layer, kinds, supported filters,
+fetchability, id examples, auth, and rate limits.
+
+## ⚙️ Configuration
+
+Both optional, set via environment variables:
+
+- `NCBI_API_KEY` — raises the NCBI E-utilities rate limit (3 → 10 req/s) used by
+  the omics, literature, and taxonomy lookups.
+- `UNPAYWALL_EMAIL` — enables the Unpaywall fallback leg of literature full-text
+  retrieval (the EuropePMC leg works without it).
+
+## 🧪 Develop
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+uv run pytest -q
+uv run ruff check src tests
+DATA_AGGREGATOR_MCP_LIVE=1 uv run pytest -k live -q   # real-API probes
+```
+
+The README demo (`examples/assets/demo.svg`) is recorded network-free from
+`examples/_demo_stdio.py` — see the header of that file to re-record.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data_aggregator_mcp-0.11.0/PUBLISH.md

@@ -0,0 +1,61 @@
+# Publishing data-aggregator-mcp
+
+Every step below is **outward-facing and irreversible** (PyPI versions cannot be
+re-uploaded or deleted; the PyPI project name and the registry name are
+permanent). The repo is prepared to the gate — nothing here has been executed.
+Run these manually when ready to ship a release.
+
+## One-time setup
+
+### 1. Create the public GitHub repo
+
+```bash
+gh repo create musharna/data-aggregator-mcp --public --source=. --remote=origin --push
+```
+
+### 2. Configure PyPI trusted publisher (no token needed)
+
+On https://pypi.org → your account → _Publishing_ → _Add a pending trusted publisher_:
+
+- PyPI Project Name: `data-aggregator-mcp`
+- Owner: `musharna`
+- Repository name: `data-aggregator-mcp`
+- Workflow name: `publish.yml`
+- Environment name: `pypi`
+
+The first OIDC publish (step 3) creates the project automatically.
+
+## Per release
+
+### 3. Cut the release (fires `.github/workflows/publish.yml`)
+
+Set the version in **all three** places to the release value —
+`pyproject.toml`, `src/data_aggregator_mcp/__init__.py`, and `server.json`
+(both top-level `version` and `packages[0].version`). The tree is already at
+`0.11.0` for the first release, so no bump is needed there — just tag. Then:
+
+```bash
+git tag v0.11.0
+git push origin main --tags
+gh release create v0.11.0 --title v0.11.0 --notes-from-tag
+```
+
+The publish workflow verifies the tag matches the package version, builds the
+wheel + sdist, and uploads to PyPI via OIDC trusted publishing.
+
+### 4. Submit to the official MCP registry (after the PyPI release is live)
+
+```bash
+# install the publisher CLI (see modelcontextprotocol/registry releases)
+mcp-publisher login github      # OIDC device flow; grants the io.github.musharna/* namespace
+mcp-publisher publish           # reads server.json; validates the README mcp-name marker
+```
+
+The registry fetches `https://pypi.org/pypi/data-aggregator-mcp/json` and
+confirms the `mcp-name: io.github.musharna/data-aggregator-mcp` marker is present
+in the published description — so the PyPI release in step 3 must land first.
+
+## Future enhancement (not built)
+
+Registry submission can be automated in GitHub Actions via OIDC (a separate
+`mcp-publisher` CI step). Left manual here by design.