Add magg, an MCP aggregator / meta-MCP server, to the overlay. It is a Python package on the hatchling backend, built with python3Packages.buildPythonApplication from the v1.3.0 source tarball, so no upstream release artifacts are fetched. Ships both console scripts declared upstream: magg (the aggregator CLI/server) and mbro (the MCP browser). License is AGPL-3.0-or-later. The install check runs the upstream pytest suite with -m "not integration", because the integration-marked tests need a live server. A forced nix build .#magg --rebuild passes with 329 passed, 3 skipped, 3 deselected, 0 failed, and both binaries smoke-test clean. Also adds the README and AGENTS.md package rows, the upstream and build research notes, and the verification report in docs/magg_build_report.md.
18 KiB
Upstream fact sheet: sitbon/magg
Task: t-001 — upstream research for a Nix derivation. Researched: 2026-11-08 (all facts fetched live from GitHub/PyPI on that date).
Headline: The repository exists and is public: https://github.com/sitbon/magg
(GitHub repo id 1005453886, private: false, archived: false, 143 stars, 25 forks).
It is a pure-Python, PEP 621 / hatchling / uv project published to PyPI as magg,
with GitHub Releases + git tags. Latest release: v1.3.0.
1. What is magg?
Short description for meta.description (129 chars):
MCP aggregator server that manages, aggregates and proxies other MCP servers so LLMs can discover, add and manage tools at runtime
Alternatives (all sourced verbatim from upstream):
| Source | Text |
|---|---|
GitHub repo description |
Magg: The MCP Aggregator |
pyproject.toml → project.description |
MCP Aggregator |
server.json → description |
Aggregates and proxies other MCP servers, letting LLMs discover, add, and manage tools at runtime. |
readme.md (line 12, intro) |
A Model Context Protocol server that manages, aggregates, and proxies other MCP servers, enabling LLMs to dynamically extend their own capabilities. |
readme.md (heading) |
🧲 Magg - The MCP Aggregator |
Longer explanation (upstream's own words, readme.md § "What is Magg?"):
Magg is a meta-MCP server acting as a central hub for managing multiple MCP servers. It exposes
MCP tools that let an LLM search for new MCP servers online, add/configure them dynamically,
enable/disable them, aggregate their tools under unified prefixes, and persist configuration
across sessions (.magg/config.json). Upstream describes it as "a 'package manager for LLM
tools' - it lets AI assistants install and manage their own capabilities at runtime". It supports
stdio / HTTP / hybrid transports, optional RSA-JWT bearer auth for HTTP mode, dynamic config
reload (file watch + SIGHUP), "kits" (bundles of servers), and ships a second CLI, mbro
("MCP Browser") for interactive inspection.
Evidence: https://raw.githubusercontent.com/sitbon/magg/v1.3.0/readme.md,
https://raw.githubusercontent.com/sitbon/magg/v1.3.0/server.json,
https://api.github.com/repos/sitbon/magg.
2. Implementation language & build system
- Language: Python only. GitHub language breakdown returns exactly
{"Python": 739242}(100 %). Source tree contains only*.py+ markdown/JSON. Evidence:https://api.github.com/repos/sitbon/magg/languages. - Build system: PEP 621
pyproject.tomlwith thehatchlingbuild backend, project managed with uv (a committeduv.lockand.python-versionare present). There is noCargo.toml,package.json,go.mod,Makefile,justfile, orsetup.py. Evidence: root listing of tagv1.3.0viahttps://api.github.com/repos/sitbon/magg/contents/?ref=v1.3.0andhttps://raw.githubusercontent.com/sitbon/magg/v1.3.0/pyproject.toml.
Root of v1.3.0 (full listing):
.env.example, .gitignore, .python-version, compose.yaml, contributing.md, dockerfile,
license.md, pyproject.toml, readme.md, security.md, server.json, uv.lock,
plus dirs .github/, docs/, etc/, examples/, magg/, scripts/, test/.
Key manifest facts (pyproject.toml @ v1.3.0):
[project]
name = "magg"
version = "1.3.0"
requires-python = ">=3.12"
description = "MCP Aggregator"
license = {text = "AGPL-3.0-or-later"}
license-files = ["license.md"]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project.optional-dependencies]
test = ["pytest>=8.4.0", "pytest-asyncio>=1.0.0"]
[tool.pytest.ini_options]
markers = ["integration: marks tests as integration tests (deselect with '-m \"not integration\"')"]
Runtime dependencies ([project.dependencies], v1.3.0):
fastmcp>=3.4,<4, mcp>=1.28, aiohttp>=3.12.13, pydantic>=2.11.7,
pydantic-settings>=2.10.0, rich>=14.0.0, prompt-toolkit>=3.0.51,
cryptography>=45.0.4, pyjwt>=2.10.1, watchdog>=6.0.0, art>=6.5.
Python support: requires-python = ">=3.12"; classifiers list CPython 3.12 / 3.13 / 3.14
(README prose says "Python 3.12 or higher (3.13+ recommended)"; .python-version pins 3.14
for upstream development).
3. Versioning & release state
Yes — upstream publishes both GitHub Releases and annotated git tags, and also publishes to
PyPI (https://pypi.org/project/magg/, 23 releases; PyPI latest = 1.3.0, uploaded
2026-09-26T16:29:42Z, i.e. in lock-step with the GitHub release).
Latest release: v1.3.0
| Field | Value | Evidence |
|---|---|---|
| Release tag name | v1.3.0 (🧲 Magg Release v1.3.0) |
https://api.github.com/repos/sitbon/magg/releases/latest |
| Tag object (annotated) | cc9963ea784fcc2e465c318ab9f0f24e5059c1d1 (type: tag) |
.../git/refs/tags/v1.3.0 |
| Peeled commit SHA | 1b18b87fdcda9628381888aea25fefa60fe1f923 |
.../commits/1b18b87f… |
| Commit date | 2026-09-26T16:28:09Z (authored 2026-09-26 09:28:09 -0700) — "Robustness fixes: config data loss, unmounting, hung backends, CLI and mbro bugs (#21)" |
GitHub API / git log |
| Release created / published | 2026-09-26T16:29:30Z / 2026-09-26T16:29:41Z; prerelease: false, draft: false, target_commitish: main |
.../releases/tags/v1.3.0 |
| Release assets | magg-1.3.0-py3-none-any.whl (143 372 B), magg-1.3.0.tar.gz (340 217 B) |
same |
| Release author | github-actions[bot] (automated release on tag) |
same |
Release-asset hashes (computed locally from the GitHub release downloads):
sha256 magg-1.3.0.tar.gz da3cc1b646b8616a78c841af268ac737f250a48eac582ae646efd3b6f467aa95
sha256 magg-1.3.0-py3-none-any.whl 6360f04b49fdce6d8ec48aa6865848f8a610a60a3e433fcd539383299958c933
Tag hygiene (from https://api.github.com/repos/sitbon/magg/tags?per_page=15): upstream emits
both a patch tag and a minor tag per release, both pointing at the same commit —
v1.3.0 and v1.3 → 1b18b87f…; v1.2.1 → 419e8e07…; v1.2.0 → 5af7cad8…;
v1.2 → 419e8e07…; v1.1.0/v1.1 → 79923f85…; v0.10.1/v0.10 → c237d4c1…; etc.
A moving tag latest-publish also points at 1b18b87f… (marks the last PyPI publish).
⇒ Use the dotted tag v1.3.0 for src.version/rev.
Default branch / HEAD (in case main is preferred over the tag):
- Default branch:
main - HEAD:
dafa9c9ccbfc7209f7bd8e5f303d51598d19f59c, committed2026-09-27T19:05:55Z("Add security policy"). Verified as a descendant ofv1.3.0(the only extra commit addssecurity.md), sov1.3.0is the right packaging rev. - Other branches:
beta(774636eb…, feeds theghcr.io/sitbon/magg:betaimage), plus two staleclaude/*branches. - Repo
pushed_at:2026-09-27T19:05:55Z.
4. License
SPDX: AGPL-3.0-or-later → Nix: meta.licenses = lib.licenses.agpl3Plus;
Evidence:
pyproject.toml:license = {text = "AGPL-3.0-or-later"},license-files = ["license.md"], classifier"License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)".license.md(34 260 B) is the verbatim GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 text (incl. the §13 "remote network interaction" clause).- PyPI metadata:
License: AGPL-3.0-or-later; wheelMETADATAhasLicense: AGPL-3.0-or-later+License-File: license.md. - GitHub API reports
spdx_id: "AGPL-3.0"(GitHub's coarse bucket; the manifest is more precise with-or-later). - Dockerfile OCI label:
org.opencontainers.image.licenses=AGPL-3.0-or-later.
Flag: not dual-licensed, but it is AGPL — strong copyleft with a network-use clause
(free per DFSG, but relevant for redistribution policy). Note the file is license.md
(lowercase markdown), not LICENSE; hatchling ships it into
magg-<ver>.dist-info/licenses/license.md, so a fetchPypi-style build finds it automatically.
There is no separate NOTICE/dual-license file.
5. Binaries produced (meta.mainProgram)
Two console scripts — declared in pyproject.toml [project.scripts] and confirmed by
magg-1.3.0.dist-info/entry_points.txt inside the released wheel:
[console_scripts]
magg = magg.cli:main
mbro = magg.mbro.cli:main
meta.mainProgram = "magg";- Second binary:
mbro(the "MCP Browser" interactive CLI, documented indocs/mbro.md). Setmeta.mainProgramtomaggand expect bothbin/maggandbin/mbroin the output. python -m maggandpython -m magg.mbroalso work (magg/__main__.py,magg/mbro/__main__.pyexist in the wheel).- Upstream install docs' primary entry point is
uv tool install maggthenmagg serve.
6. Repo layout relevant to packaging
- App is at the repo root, single flat package — importable package dir
magg/sits at the top level next topyproject.toml(hatchling auto-detects it; no[tool.hatch.build]wheelpackagesoverride). No Cargo/npm workspace, nosrc/layout, no sub-crate. - Package subpackages inside
magg/:contrib/,discovery/,logs/,mbro/,proxy/,server/,util/— 66 files total inmagg/. - Package data shipped in the wheel (must not be stripped):
magg/contrib/magg.mbro,magg/contrib/readme.md,magg/contrib/kit.d/example.json(default kit directory). Wheel contains 62 files: 56.py+ those 3 data files +dist-info. etc/glama-mcp-api.json(19 729 B) is NOT shipped in the wheel or the sdist — the[tool.hatch.build.targets.sdist]include list omitsetc/. It is a vendored API spec used only for upstream development/discovery. Same for.github/(explicitly excluded).- No git submodules —
https://raw.githubusercontent.com/sitbon/magg/v1.3.0/.gitmodules→ HTTP 404. - No Git LFS —
.gitattributes→ HTTP 404; the git tree lists all 145 entries as plain blobs (git/trees/v1.3.0?recursive=1,truncated: false), largest beinguv.lock(387 038 B),magg/cli.py(41 731 B),magg/server/server.py(37 036 B),license.md(34 260 B). Repo size ≈ 1.3 MB — cheap to fetch. - Tests are shipped in the sdist (
magg-1.3.0/test/…, 35 files, incl.test/magg/) — acheckPhasecan runpytestfrom the unpacked sdist.pyproject.tomlregisters theintegrationmarker; 3 tests in the tree carry@pytest.mark.integration, so-m "not integration"is the safe deselection (upstream's CI runs the full suite on.github/workflows/test.yml,uv run pytest -v). - Other root artifacts:
compose.yaml(Docker Compose),dockerfile,server.json(MCP Registry manifest,io.github.sitbon/magg, version kept in sync withpyproject.tomlbyscripts/bump_version.py --check),docs/(11 markdown files,docs/index.mdis the hub),examples/(6 python examples),scripts/(bump_version.py,validate_manual_release.py).
7. Upstream build / install instructions (from readme.md § Installation)
Prerequisites (upstream's words): "Python 3.12 or higher (3.13+ recommended)" and
"uv (recommended) - Install from astral.sh/uv".
# 1. Recommended: install from PyPI as a uv tool
uv tool install magg
magg serve # stdio transport (Claude Desktop, Cline, …)
magg serve --http # HTTP transport, system-wide
# 2. Run straight from GitHub (no install)
uvx --from git+https://github.com/sitbon/magg.git magg
uvx --from git+https://github.com/sitbon/magg.git magg serve --http
# 3. Local development
git clone https://github.com/sitbon/magg.git && cd magg
uv sync --dev # or: poetry install --with dev
magg --help
# 4. Docker (ghcr images)
docker run -p 8000:8000 ghcr.io/sitbon/magg:latest # prod, WARNING log level
docker run -p 8000:8000 ghcr.io/sitbon/magg:beta # beta, INFO log level
docker compose up # prod/staging/dev via compose.yaml
Other run modes: magg serve --http --port 8000, magg serve --hybrid [--port N],
mbro connect local-magg magg serve.
Required runtime env vars: none are mandatory. All are optional MAGG_* (see .env.example
and README § Environment Variables):
MAGG_CONFIG_PATH (default .magg/config.json, cwd-relative), MAGG_LOG_LEVEL
(DEBUG/INFO/WARNING/ERROR/CRITICAL, default INFO), MAGG_STDERR_SHOW=1,
MAGG_AUTO_RELOAD (default true), MAGG_RELOAD_POLL_INTERVAL (default 1.0),
MAGG_RELOAD_USE_WATCHDOG, MAGG_READ_ONLY=true, MAGG_SELF_PREFIX (default magg),
MAGG_PREFIX_SEP (default _), MAGG_BACKEND_INIT_TIMEOUT (default 30, 0 = wait forever),
MAGG_PRIVATE_KEY / MAGG_JWT (only for authenticated HTTP mode; key generated with
magg auth private-key --oneline / magg auth jwt -q). Docker sets
MAGG_CONFIG_PATH, MAGG_READ_ONLY.
Runtime deps beyond CPython: the Magg package itself needs only the PyPI deps above
(cryptography is the only binary-wheel-dependent one). node/npx and uvx are needed at
runtime only to launch proxied backend MCP servers — Magg explicitly supports backend
commands python, node, npx, uvx (magg/util/transport.py, magg/util/transports.py),
and deliberately defers the "npx not on PATH" failure to connection time rather than startup.
Upstream's own dockerfile (alpine 3.24 base) installs tini bash curl nano nodejs npm plus uv
in a venv — a good hint at what to wrap in buildInputs/makeWrapper if you want out-of-the-box
npx backends. No ffmpeg, no binaries vendored, no network needed at build time (but note
magg_search_servers hits GitHub/Glama/MCP-registry APIs at runtime).
CI reference for a checkPhase (.github/workflows/test.yml): matrix on Python
3.12, 3.13, 3.14, ubuntu-latest, uv sync --all-groups --locked then
uv run pytest -v. Dev group additionally pulls keyring, anthropic, packaging, ruff
(ruff config: line-length = 120, lint select = ["F","I"]).
8. Homepage / documentation / changelog URLs
From pyproject.toml [project.urls] (verbatim) and the wheel METADATA Project-URL lines:
| Key | URL |
|---|---|
| Homepage | https://github.com/sitbon/magg |
| Repository | https://github.com/sitbon/magg.git |
| Documentation | https://github.com/sitbon/magg#readme |
| Issues | https://github.com/sitbon/magg/issues |
| Release Notes | https://github.com/sitbon/magg/releases |
meta.homepage = "https://github.com/sitbon/magg";(matchesserver.json.websiteUrl). Note: the GitHub repo's ownhomepagefield points tohttps://pypi.org/project/magg/— use the GitHub URL formeta.homepage(per manifest) and addhttps://pypi.org/project/magg/as a source/download location.meta.changelog = "https://github.com/sitbon/magg/releases";— there is noCHANGELOG/HISTORYfile anywhere in the repo (verified via the full recursive git tree ofv1.3.0; the only "changelog" mention is inside.github/workflows/readme.md). Release notes are generated per tag by GitHub Actions; per-tag URL form:https://github.com/sitbon/magg/releases/tag/v1.3.0.- In-repo docs:
docs/index.md(hub), plusdocs/mbro.md,docs/authentication.md,docs/config-reload.md,docs/examples.md,docs/kits.md,docs/mcp-registry.md,docs/mcp-stateless.md,docs/messaging.md,docs/proxy.md,docs/proxy-spec.md. These are shipped in the sdist (not the wheel). Third-party AI docs:https://deepwiki.com/sitbon/magg. - MCP Registry listing:
io.github.sitbon/maggonhttps://registry.modelcontextprotocol.io.
9. Supported platforms
- Declared: OS-independent, CPython only.
pyproject.tomlclassifiers include"Operating System :: OS Independent"and"Programming Language :: Python :: 3 :: Only"/Implementation :: CPython;requires-python = ">=3.12"(3.12/3.13/3.14 listed). Noplatform_machine, no macOS/x86-only markers in the dependency set. - CI only exercises Linux (
runs-on: ubuntu-latest, Python 3.12/3.13/3.14). - Platform-specific code (all guarded, none exclusionary):
magg/server/runner.py:102-109,127-135— SIGHUP-triggered config reload is Unix-only, guarded byif hasattr(signal, "SIGHUP"); comment at line 118: "No loop signal support (e.g. Windows): hand the signal to the loop thread-safely". README: "SIGHUP signal:kill -HUP <pid>… (Unix-like systems)".magg/util/uri.py:30-31— Windows path handling:if os.name == "nt" and path.startswith("/") ….magg/util/system.py:24/magg/mbro/cli.py:596/magg/util/terminal.py:39— TTY detection (os.isatty,sys.stdout.isatty) to degrade therich/prompt-toolkitREPL when not interactive.magg/mbro/arepl.py:110printsf"asyncio REPL {sys.version} on {sys.platform}"(cosmetic).
- musl/Alpine: upstream ships a working Alpine image and applies a
"Fix for Python 3.12 extension suffix mismatch on Alpine" in the
dockerfile— relevant if you targetx86_64-linuxwith libc-agnostic Python; nothing in pure-Python Magg itself is libc-specific (onlycryptography/aiohttpwheels matter). - Termux/Android is implicitly considered (commit
1b18b87fnotes that Termux sets env vars likePREFIX/URI/KEY_PATH, which Magg's config models no longer read). - Practical conclusion for
meta.platforms:lib.platforms.all-ish (purepy3-none-anywheel,Operating System :: OS Independent); upstream tests Linux only, and the interactivembroREPL + SIGHUP reload are nicest on Unix.
Quick derivation cheat-sheet (facts, not a proposal)
pname = "magg"; version = "1.3.0";
src = GitHub owner="sitbon" repo="magg" rev="v1.3.0"
sha256 = da3cc1b646b8616a78c841af268ac737f250a48eac582ae646efd3b6f467aa95 # magg-1.3.0.tar.gz
# or PyPI pname="magg" version="1.3.0" (same sha256 family; wheel:
# 6360f04b49fdce6d8ec48aa6865848f8a610a60a3e433fcd539383299958c933)
tag commit = 1b18b87fdcda9628381888aea25fefa60fe1f923 (annotated tag obj cc9963ea784fcc2e465c318ab9f0f24e5059c1d1)
build system = hatchling (PEP 517) ; python = 3.12..3.14
license = AGPL-3.0-or-later ; mainProgram = "magg" (also installs "mbro")
tests = pytest (sdist ships test/); deselect -m "not integration"
MISSION COMPLETE (t-001)