feat(magg): add magg 1.3.0 MCP aggregator package
CI / check (push) Has been cancelled

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.
This commit is contained in:
2026-11-08 12:48:30 +03:00
parent e569243ae4
commit 44e6d90a77
7 changed files with 1196 additions and 0 deletions
+1
View File
@@ -304,6 +304,7 @@ nix build .#<package-name>
### Package-Specific Notes ### Package-Specific Notes
- **magg**: Python/hatchling package built with `python3Packages.buildPythonApplication`; tagged releases mean plain `nix-update --flake .#magg` works, but upstream also publishes alias/junk tags (`v1.3`, `latest-publish`, `root`) so verify the picked tag on bump; `checkPhase` runs pytest with `-m "not integration"` because the integration-marked tests need a live server
- **mcp-gateway**: Standard Rust package, `nix-update` handles version + cargoHash - **mcp-gateway**: Standard Rust package, `nix-update` handles version + cargoHash
- **skillsmcp**: Pinned to a commit hash; use `--version=branch=main` or specify the target commit with `--commit` - **skillsmcp**: Pinned to a commit hash; use `--version=branch=main` or specify the target commit with `--commit`
+1
View File
@@ -26,6 +26,7 @@ A custom Nix overlay and flake providing additional packages not found in upstre
| `g3` | AI coding agent that writes code and executes commands, with multi-provider LLM support, context compaction, and desktop automation | AI Coding Agents | | `g3` | AI coding agent that writes code and executes commands, with multi-provider LLM support, context compaction, and desktop automation | AI Coding Agents |
| `haivemind` | Multi-model AI consensus, aggregation, and fusion runner for popular AI CLIs | AI Coding Agents | | `haivemind` | Multi-model AI consensus, aggregation, and fusion runner for popular AI CLIs | AI Coding Agents |
| `hipengine` | ROCm-native local LLM inference engine with torch-free runtime for AMD RDNA GPUs | AI Inference | | `hipengine` | ROCm-native local LLM inference engine with torch-free runtime for AMD RDNA GPUs | AI Inference |
| `magg` | MCP aggregator / meta-MCP server that aggregates, proxies and manages other MCP servers so agents can discover and manage tools at runtime, ships `magg` and `mbro` | MCP Servers |
| `marmel` | Autonomous agentic coding assistant with Manager + specialist subagent orchestration over any OpenAI-compatible LLM backend | AI Coding Agents | | `marmel` | Autonomous agentic coding assistant with Manager + specialist subagent orchestration over any OpenAI-compatible LLM backend | AI Coding Agents |
| `mcp-gateway` | Universal Model Context Protocol gateway that sits between AI client and MCP tools/servers | MCP Servers | | `mcp-gateway` | Universal Model Context Protocol gateway that sits between AI client and MCP tools/servers | MCP Servers |
| `memdoor` | Coding and automation agent in one CLI binary: runs locally or over SSH, with YAML workflows and a decision model in front of the chat model | AI Coding Agents | | `memdoor` | Coding and automation agent in one CLI binary: runs locally or over SSH, with YAML workflows and a decision model in front of the chat model | AI Coding Agents |
+367
View File
@@ -0,0 +1,367 @@
# Build/verification report: `packages/magg` (magg 1.3.0)
- **Task:** t-005 — independent verification of the newly added `magg` package.
- **Verifier role:** read-only audit. `packages/magg/*`, `README.md`, `AGENTS.md`, `flake.lock` were **not**
modified (proven by `sha256sum -c` at the end of this report) and **nothing was committed**.
- **Host system:** `x86_64-linux` (`nix eval --raw --impure --expr 'builtins.currentSystem'`), Nix 2.34.9.
- **Verdict:** **PASS** — the derivation evaluates, builds from a forced rebuild, its test suite genuinely
re-runs and passes (329 passed / 3 skipped / 3 deselected / 0 failed), and both console scripts work.
---
## 1. Git index state (blueprint discovers packages from the git index)
```console
$ git status --porcelain
M .serena/project.yml
M AGENTS.md
M README.md
A packages/magg/default.nix
A packages/magg/package.nix
?? .marmel/
?? docs/research_magg_build.md
?? docs/research_magg_upstream.md
$ git ls-files packages/magg
packages/magg/default.nix
packages/magg/package.nix
$ git diff --cached --stat
packages/magg/default.nix | 5 ++
packages/magg/package.nix | 165 ++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 170 insertions(+)
```
Both files are already **staged** (`A`, present in the index), so blueprint can see the package.
**`git add` was NOT needed and was not run.**
Note: `README.md` / `AGENTS.md` doc rows are modified but **unstaged**, and `docs/research_magg_*.md`
(including this report) are untracked. That does not affect package visibility to `nix build`, but the
commit that lands this change must stage them together with `packages/magg/` or the docs will be lost.
## 2. Flake attribute exists and evaluates via the blueprint `perSystem` output
`nix flake show '.#magg'` is not valid CLI syntax (`error: unexpected fragment 'magg' in flake reference
'.#magg'`), and a whole-flake `nix flake show .` aborts on a **pre-existing, repo-wide** nixpkgs problem
(see §9), so the attribute was probed directly:
```console
$ nix eval .#magg.version
"1.3.0"
$ nix eval --raw .#magg.meta.mainProgram
magg
$ nix eval --raw .#packages.x86_64-linux.magg.pname # blueprint perSystem output
magg
$ nix eval .#checks.x86_64-linux --apply 'x: builtins.attrNames x'
[ ..., "pkgs-magg", ... ] # blueprint check attr present
```
`nix flake show .` does list the package in the (cached) output tree, e.g.
`├───pkgs-magg omitted (use '--all-systems' to show)`.
## 3. Real rebuild with the check phase re-executed (not a cached echo)
`nix build .#magg --check` does not exist on Nix 2.34 (`error: unrecognised flag '--check'`); the
equivalent flag is `--rebuild` ("Rebuild an already built package and compare the result"), so that was
used to force a genuine re-run of every phase, including the test suite:
```console
$ nix build .#magg --rebuild --no-link --print-build-logs
checking outputs of '/nix/store/njvx0wy8h1lyg0iw2k2nnjmk64mgk8x4-magg-1.3.0.drv'...
magg> Running phase: unpackPhase
magg> Running phase: buildPhase
magg> Successfully built magg-1.3.0-py3-none-any.whl
magg> Running phase: pythonRuntimeDepsCheckHook
magg> Checking runtime dependencies for magg-1.3.0-py3-none-any.whl
magg> Running phase: installPhase
magg> Successfully installed magg-1.3.0-py3-none-any.whl
magg> wrapping `/nix/store/y9n7l82x6k766bjygf73vag5ivw9vnsx-magg-1.3.0/bin/magg'...
magg> wrapping `/nix/store/y9n7l82x6k766bjygf73vag5ivw9vnsx-magg-1.3.0/bin/mbro'...
magg> Running phase: installCheckPhase
magg> ============================= test session starts ==============================
magg> platform linux -- Python 3.14.7, pytest-9.1.1, pluggy-1.6.0
magg> rootdir: /build/source
magg> configfile: pyproject.toml
magg> plugins: asyncio-1.4.0, anyio-4.14.2
magg> asyncio: mode=Mode.STRICT, debug=False, ...
magg> collected 335 items / 3 deselected / 332 selected
magg> ...
magg> test/magg/test_in_memory.py ..... [ 30%]
magg> test/magg/test_mounting_real.py . [ 73%]
magg> test/magg/test_server_robustness.py ................... [ 93%]
magg> test/magg/test_transport.py ............. [100%]
magg> ================ 329 passed, 3 skipped, 3 deselected in 42.50s =================
magg> installCheckPhase completed in 44 seconds
magg> Running phase: pythonImportsCheckPhase
magg> Check whether the following modules can be imported: magg
NIXBUILD_EXIT=0
```
- **Test-suite summary line:** `329 passed, 3 skipped, 3 deselected in 42.50s` — **0 failed, 0 errored**.
- **Final exit status:** `0`. `--rebuild` also compares the freshly produced output against the stored one;
a mismatch would have been a hard error, so the cached output is reproducible.
- The suite really ran: `installCheckPhase completed in 44 seconds`, `pytest-asyncio 1.4.0` loaded in
`mode=Mode.STRICT` (so async tests are executed, not silently skipped), and the stdio-backend test
modules the derivation comment calls out (`test_in_memory.py`, `test_mounting_real.py`,
`test_client_mounting.py`, `test_server_robustness.py`, `test_transport.py`) all pass — i.e. the
venv/`.pth` trick in `checkPhase` works: those tests are green instead of dying with
`ModuleNotFoundError: No module named 'fastmcp'`.
- The 3 deselected tests are the `-m "not integration"` e2e tests; the 3 skipped ones are upstream's own
capability probes in `test/magg/test_client_api.py` (`"Command keyword syntax not supported"`,
`"Positional command syntax not supported"`, `"WebSocket URLs not supported"`), not packaging-induced skips.
- `pythonImportsCheck = [ "magg" ]` executed and passed.
## 4. Binary smoke tests
```console
$ OUT=$(nix build .#magg --no-link --print-out-paths)
/nix/store/y9n7l82x6k766bjygf73vag5ivw9vnsx-magg-1.3.0
$ ls $OUT/bin
magg .magg-wrapped mbro .mbro-wrapped
$ $OUT/bin/magg --version ; echo exit=$?
magg 1.3.0
exit=0
$ $OUT/bin/magg --help | head -6 ; echo exit=${PIPESTATUS[0]}
usage: magg [-h] [--version] [--config CONFIG] [-e] [-E KEY VALUE]
{serve,server,config,kit,auth} ...
Magg - MCP Aggregator: Manage and aggregate MCP servers
...
exit=0
$ $OUT/bin/mbro --version < /dev/null ; echo exit=$?
mbro (magg) 1.3.0
exit=0
$ $OUT/bin/mbro --help < /dev/null | head -6 ; echo exit=${PIPESTATUS[0]}
usage: mbro [-h] [-V] [--json] [--no-rich] [--indent INDENT] [-v] [-q] [-e]
[-E KEY VALUE] [--repl] [-n] [-x SCRIPT] [-X SCRIPT]
[--status-bar] [--fail-fast] [--timeout SECONDS] [commands ...]
MBRO - MCP Browser
exit=0
$ nix run .#magg -- --help # resolves meta.mainProgram = "magg"
usage: magg [-h] [--version] [--config CONFIG] [-e] [-E KEY VALUE]
{serve,server,config,kit,auth} ...
Magg - MCP Aggregator: Manage and aggregate MCP servers
nixrun_exit=0
```
Both console scripts declared in upstream `[project.scripts]` (`magg = magg.cli:main`,
`mbro = magg.mbro.cli:main`) are installed, wrapped and functional; `mainProgram` resolves.
### `mbro` TTY caveat (upstream behaviour, **not** a packaging defect)
First attempt through a non-foreground pipe appeared to hang with no output:
```console
$ timeout 60 $OUT/bin/mbro --version > out 2> err # stdin = a TTY, process in a background pgroup
exit=124 # timeout; 0 bytes on stdout/stderr
```
Root cause (obtained with `timeout -s ABRT` + `python -X faulthandler`):
```
Fatal Python error: Aborted
Current thread ... (most recent call first):
File ".../python3.14/_pyrepl/fancy_termios.py", line 63 in tcsetattr
File ".../python3.14/_pyrepl/unix_console.py", line 836 in __input_fd_set
File ".../python3.14/_pyrepl/readline.py", line 364 in get_reader
File ".../python3.14/_pyrepl/main.py", line 15 in <module>
File ".../site-packages/magg/mbro/arepl.py", line 27 in <module>
File ".../site-packages/magg/mbro/cli.py", line 22 in <module>
```
`magg/mbro/arepl.py:27` does a module-level `from _pyrepl.main import CAN_USE_PYREPL`; importing
`_pyrepl.main` runs its top-level `check()`, which builds a `UnixConsole` and calls `tcsetattr(0, …)`.
If stdin is a TTY **and** the process is not in the terminal's foreground process group, that ioctl raises
`SIGTTOU` and the process is stopped before argparse ever sees `--help`. Proof it is environmental, not
packaging:
- foreground in a real terminal: `mbro --version` → `mbro (magg) 1.3.0`, exit 0;
`mbro --help` → full usage, exit 0.
- stdin redirected (`< /dev/null`): both exit 0.
- Nothing in `packages/magg/package.nix` is involved (`patchPhase` was a no-op; the shipped
`arepl.py` is byte-identical upstream source).
Suggested upstream/CPython-level follow-up (out of scope for this overlay): import
`_pyrepl.constants`/`_pyrepl.unix_console` instead of `_pyrepl.main`, or guard the import.
## 5. Metadata audit
```console
$ nix eval --json .#magg.meta | ...
description : "MCP aggregator server that manages, aggregates and proxies other MCP servers
so LLMs can discover, add and manage tools at runtime" (130 chars, <= 140)
homepage : https://github.com/sitbon/magg
changelog : https://github.com/sitbon/magg/releases
license : spdxId = AGPL-3.0-or-later, free = true (= lib.licenses.agpl3Plus)
mainProgram : magg
sourceProvenance : [ { isSource = true, shortName = "fromSource" } ]
platforms : 79 entries, x86_64-linux = True, aarch64-linux = True, aarch64-darwin = True
available/broken/disabled : true / false / false
$ nix eval --json .#magg.passthru | ...
category : "MCP Servers"
updateScript : ["nix-update","--flake",".#magg"]
```
All requested metadata criteria are met. Cross-checked against the upstream source in the store
(`/nix/store/5ddzskmb15i6lnsv6khjzxa8gzz4ad80-source/pyproject.toml`):
| upstream | value | derivation |
| --- | --- | --- |
| `version` | `1.3.0` | `version = "1.3.0"` ✔ |
| `license = {text = "AGPL-3.0-or-later"}` + classifier `…General Public License v3 or later (AGPLv3+)` | AGPL-3.0-or-later | `license = lib.licenses.agpl3Plus` ✔ |
| `[project.scripts] magg`, `mbro` | 2 scripts | both installed, `mainProgram = "magg"` ✔ |
| `requires-python = ">=3.12"` | built with python3.14.7 from nixpkgs ✔ |
`platforms = lib.platforms.all` matches the convention used by the other pure-Python packages in this repo
(`desloppify`, `graphify`, `haivemind`, `nftables-analyzer`, `relay-free-llm`).
## 6. Upstream-pinning audit
```console
$ curl -sS https://api.github.com/repos/sitbon/magg/releases/latest
tag_name: v1.3.0 name: 🧲 Magg Release v1.3.0 published_at: 2026-09-26T16:29:41Z prerelease: False
$ git ls-remote --tags https://github.com/sitbon/magg | sed 's#.*refs/tags/##' | grep -v '\^{}' | sort -V
latest-publish latest-release root
magg/v0.3.6.30 … magg/v0.5.1.53
v0.6 v0.6.0 v0.6.1 v0.7 v0.7.0 v0.7.1 v0.8 v0.8.0 v0.9 v0.9.0 v0.9.1
v0.10 v0.10.0 v0.10.1 v1.1 v1.1.0 v1.2 v1.2.0 v1.2.1 v1.3 v1.3.0
$ git ls-remote --tags https://github.com/sitbon/magg | grep -E 'v1\.3'
1b18b87fdcda9628381888aea25fefa60fe1f923 refs/tags/v1.3
cc9963ea784fcc2e465c318ab9f0f24e5059c1d1 refs/tags/v1.3.0
1b18b87fdcda9628381888aea25fefa60fe1f923 refs/tags/v1.3.0^{}
$ nix eval --raw .#magg.src.rev ; nix eval --raw .#magg.src.hash
v1.3.0
sha256-Dj8f+MwefUD5wk4JFTkrC72QGqfJoWQd8ToOeNI6rmM=
$ nix-prefetch-url --unpack https://github.com/sitbon/magg/archive/v1.3.0.tar.gz
0qxf7b97h3isy4fn98f9lwd91g8b5cwia2afqbwl0z8yrkw1ygqf
$ nix hash convert --hash-algo sha256 --to sri 0qxf7b97h3isy4fn98f9lwd91g8b5cwia2afqbwl0z8yrkw1ygqf
sha256-Dj8f+MwefUD5wk4JFTkrC72QGqfJoWQd8ToOeNI6rmM= # == declared src.hash ✔
```
- **No newer release exists**: `v1.3.0` is both the GitHub `releases/latest` and the highest dotted tag.
The pin is current — nothing to flag.
- The independently recomputed SRI hash of the `v1.3.0` GitHub tarball is **identical** to the declared
`src.hash`, so the hash corresponds to the tag content (and Nix's fixed-output validation agreed during
the §3 rebuild).
- The derivation's warning comment about alias tags is accurate: `v1.3` peels to the same commit as
`v1.3.0` (`1b18b87fd…`), and `latest-publish` / `latest-release` / `root` / `magg/v0.5.1.53`-style tags
all exist and would confuse a naive tag picker.
## 7. Formatting / lint
`nix flake check` (the repo's documented formatting entry point) was **not** run: blueprint registers every
package as a check (`checks.x86_64-linux.pkgs-*`, 36 of them), so it would build the entire overlay, and it
additionally aborts on the pre-existing x86_64-darwin failure (§9). The repo's own formatter was instead run
in CI mode, scoped to the changed files, inside a scratch copy so nothing on disk could be rewritten:
```console
$ nix build --no-link --print-out-paths .#formatter.x86_64-linux
/nix/store/b6mf3mzvln2igb244baas9vi6pywa05x-nixfmt-tree-2.6.0 # treefmt v2.6.0, config = treefmt.toml (nixfmt)
$ mkdir /tmp/fmtcheck && cp treefmt.toml packages/magg/*.nix /tmp/fmtcheck/
$ cd /tmp/fmtcheck && treefmt --ci --no-cache --tree-root /tmp/fmtcheck --walk filesystem .
traversed 3 files
emitted 2 files for processing
formatted 2 files (0 changed) in 292ms
treefmt_ci_exit=0
```
`packages/magg/package.nix` and `packages/magg/default.nix` are **format-clean** (0 files changed, exit 0)
under the repo's pinned nixfmt.
## 8. Doc consistency
`README.md:29`:
```
| `magg` | MCP aggregator / meta-MCP server that aggregates, proxies and manages other MCP servers
so agents can discover and manage tools at runtime, ships `magg` and `mbro` | MCP Servers |
```
- Category column is `MCP Servers`, matching `passthru.category = "MCP Servers"` ✔
- Local alphabetical slot is correct: `hipengine → magg → marmel` ✔
- Caveat (pre-existing, not introduced here): the README table is **not globally sorted** — e.g.
`agnix, awg-tool, awgen, aionui, …` and `…, skillsmcp, kubernetes-mcp-server, kyojin, …`. The `magg`
row is placed correctly with its immediate neighbours; the overall table ordering is a separate
pre-existing cleanup.
`AGENTS.md:307` (Package-Specific Notes, inserted directly above the `mcp-gateway` note):
> **magg**: Python/hatchling package built with `python3Packages.buildPythonApplication`; tagged releases
> mean plain `nix-update --flake .#magg` works, but upstream also publishes alias/junk tags (`v1.3`,
> `latest-publish`, `root`) so verify the picked tag on bump; `checkPhase` runs pytest with
> `-m "not integration"` because the integration-marked tests need a live server
Every claim is accurate and independently confirmed: hatchling build-system (§5/§3), `updateScript ==
["nix-update","--flake",".#magg"]` (§5), the alias/junk tags really exist (§6), and the marker filter is
present in `checkPhase` with exactly 3 tests deselected (§3).
## 9. Pre-existing environment issues (not caused by this change)
1. `nix flake show .` / anything that evaluates all systems fails with:
```
error: Nixpkgs 26.11 has dropped support for x86_64-darwin.
```
Reproduced with an unrelated package to prove it is repo-wide and pre-existing:
```console
$ nix eval --raw --impure --expr 'let f = builtins.getFlake (toString ./.); in f.packages.x86_64-darwin.stakpak.pname'
error: Nixpkgs 26.11 has dropped support for x86_64-darwin.
```
Unrelated to `magg` (it is a nixpkgs-unstable policy change affecting every attr in this flake).
2. `nix build .#magg --check` is not a valid flag on Nix 2.34; use `--rebuild` (see §3).
3. The `mbro` TTY/SIGTTOU import-time hang described in §4 is upstream code.
## 10. Non-blocking nits for the coder/fix task
1. `packages/magg/package.nix` comment: "so the other 332 tests all run" — measured reality is
`335 collected / 3 deselected / 332 selected`, of which **3 are skipped upstream-side** →
`329 passed`. Consider "332 selected, 329 passed, 3 skipped by upstream capability guards".
2. `README.md` / `AGENTS.md` edits are unstaged and `docs/*.md` untracked; stage them with the package when
committing (§1).
3. Cosmetic: the README table's global sort order is inconsistent (pre-existing).
## 11. Non-modification proof
```console
$ sha256sum -c /tmp/protected_baseline.txt
packages/magg/package.nix: OK
packages/magg/default.nix: OK
README.md: OK
AGENTS.md: OK
flake.lock: OK
```
No `git add`, no `git commit`, no source edits were performed by this verification.
---
## Verdict
| Check | Result |
| --- | --- |
| 1. `packages/magg/` staged in git index | **PASS** (already staged; `git add` not needed) |
| 2. Attribute exists via blueprint `perSystem` and evaluates | **PASS** (`.#magg`, `.#packages.x86_64-linux.magg`, `checks.…pkgs-magg`) |
| 3. Real rebuild, tests genuinely run and pass | **PASS** (`--rebuild`; 329 passed, 3 skipped, 3 deselected, 0 failed; exit 0) |
| 4. Binaries smoke-tested + `mainProgram`/`nix run` | **PASS** (`magg`/`mbro` `--version` & `--help` exit 0; `nix run .#magg -- --help` exit 0) |
| 5. Metadata audit | **PASS** (desc 130 chars, agpl3Plus, homepage+changelog, mainProgram=magg, platforms incl. x86_64-linux, fromSource, category "MCP Servers", updateScript present) |
| 6. Upstream pinning | **PASS** (v1.3.0 is latest release; src hash independently reproduced) |
| 7. Formatting | **PASS** (treefmt/nixfmt `--ci`: 2 files, 0 changed) |
| 8. Doc consistency | **PASS** (README row correct local slot + category; AGENTS.md note accurate) |
**PASS** — no blocking defects found in `packages/magg/package.nix` or `packages/magg/default.nix`.
+308
View File
@@ -0,0 +1,308 @@
# Build/packaging requirements: `sitbon/magg`
Companion to `docs/research_magg_upstream.md` (upstream fact sheet). This file answers only
the build/packaging questions an implementer needs answered before picking a build helper.
Evidence snapshot (all verified, nothing inferred):
| item | value | source |
| --- | --- | --- |
| upstream | <https://github.com/sitbon/magg>, default branch `main`, head tree `dafa9c9ccbfc7209f7bd8e5f303d51598d19f59c` | `GET /repos/sitbon/magg/git/trees/main?recursive=1` (146 entries) |
| latest release / PyPI | `v1.3.0` (published 2026-09-26) == PyPI `magg` 1.3.0 | `GET /repos/sitbon/magg/releases/latest`, `GET /pypi/magg/json` |
| language | Python only (no Rust/Go/Node sources, no `Makefile`, no `Cargo.toml`, no `go.mod`, no `package.json` anywhere in the 146-entry tree) | git tree listing |
| nixpkgs pin used for version checks | `nixos-unstable` rev `eaad089433ca2bb662274377d33df3d0e51ef28b` (== this overlay's `nixpkgs` **and** `nixpkgs-latest`, see `flake.lock` nodes `nixpkgs`/`nixpkgs-latest`) | `flake.lock` |
---
## 1. Which nixpkgs build helper
**`python3Packages.buildPythonApplication` with `pyproject = true` and `build-system = [ hatchling ]`.**
Evidence:
- `pyproject.toml:120-122` — `[build-system] requires = ["hatchling"] / build-backend = "hatchling.build"`.
The pin is unpinned (`"hatchling"`, no version specifier), so no `sed` pin-relax hack like
`packages/graphify/package.nix:48-50` is needed.
- Pure-python wheel: PyPI ships `magg-1.3.0-py3-none-any.whl` (62 files, no compiled extension of its own)
and an sdist `magg-1.3.0.tar.gz` (121 entries).
- Version is static in `pyproject.toml` (no `dynamic = ["version"]`, no `uv-dynamic-versioning`), so no
`writableTmpDirAsHomeHook`/setuptools-scm dance is required.
- None of the other helpers apply: no `Cargo.toml` (→ not `buildRustPackage`), no `package.json`/`bun.lock`
(→ not `buildNpmPackage`/`bun2nix`), no `go.mod`/`go.sum` (→ not `buildGoModule`), no `Makefile`
(→ not `stdenv.mkDerivation`).
- In-repo precedent to copy verbatim: `packages/skillsmcp/package.nix:7-30` already does
`python3Packages.buildPythonApplication` + `build-system = [ hatchling ]` + `python3Packages.fastmcp`.
`packages/nftables-analyzer/package.nix` and `packages/freetoken/package.nix:82-104` are the same shape.
Secondary option (deliberately **not** recommended): the repo commits `uv.lock`, so `uv2nix` /
`pyproject-nix` (`pyproject.buildApplication` + `pyparsix`/`fetchPypiTree`) is technically possible.
It buys nothing here because every dependency exists in nixpkgs (see §3), and the overlay has no
`uv2nix` precedent.
## 2. Lockfiles
- **Committed: `uv.lock`** (387 038 bytes at head, also included in the PyPI sdist).
Header: `version = 1`, `revision = 3`, `requires-python = ">=3.12"`, 92 resolved `[[package]]`
entries, all from `https://pypi.org/simple` with sdist+wheel hashes.
- **Not present:** `Cargo.lock`, `package-lock.json`, `bun.lock`, `pnpm-lock.yaml`, `go.sum`,
`requirements.txt`, `poetry.lock`.
- Consequence: there is **no `cargoHash` / `npmDepsHash` / `vendorHash` equivalent to fill in** when using
`buildPythonApplication` — dependencies come from `python3Packages`, so the only hash in the
derivation is the `src` hash. The offline build is automatic (no network at build time).
`uv.lock` would only matter for a `uv sync --locked`-based build (uv2nix route), where each of the
92 locked artifacts must be prefetched — another argument for the nixpkgs-deps route.
## 3. Toolchain version requirements
Declared upstream:
- `pyproject.toml:4` → `requires-python = ">=3.12"`; classifiers list 3.12 / 3.13 / 3.14.
- `.python-version` → `3.14` (upstream's own preferred interpreter).
- `.github/workflows/test.yml` matrix → `python-version: ['3.12', '3.13', '3.14']`, installed via
`astral-sh/setup-uv@v8.2.0` + `uv python install`.
- No Rust / Go / Node toolchain requirement. `nodejs`/`npm` appear only in `dockerfile:10`
(`apk add … nodejs npm`) so that *runtime*-mounted `npx` MCP servers work inside the container image —
not a build requirement.
Fit against this overlay's pinned nixpkgs (`eaad0894…`):
- `pkgs/top-level/all-packages.nix:4484` at that rev says `python3 = python314;`, and
`pkgs/development/interpreters/python/cpython/` ships `3.11 … 3.15`. So the default `python3Packages`
already matches upstream's `.python-version = 3.14`. **No `nixpkgs-latest`, `nixpkgs-rust195` or
`nixpkgs-torch211` instance is needed.**
Direct-dependency floors vs. what the pinned nixpkgs ships (versions read from
`pkgs/development/python-modules/<name>/default.nix` at `eaad0894…`):
| magg requirement (`pyproject.toml:31-42`) | nixpkgs attr | nixpkgs version | ok |
| --- | --- | --- | --- |
| `fastmcp>=3.4,<4` | `fastmcp` (thin wrapper over `fastmcp-slim`) | 3.4.7 | ✅ |
| `mcp>=1.28` | `mcp` | 1.29.0 | ✅ |
| `aiohttp>=3.12.13` | `aiohttp` | 3.14.3 | ✅ |
| `art>=6.5` | `art` | 6.5 | ✅ (exactly at the floor) |
| `cryptography>=45.0.4` | `cryptography` | 50.0.0 | ✅ |
| `pydantic>=2.11.7` | `pydantic` | 2.13.4 | ✅ |
| `pydantic-settings>=2.10.0` | `pydantic-settings` | 2.12.0 | ✅ |
| `pyjwt>=2.10.1` | `pyjwt` | 2.13.0 | ✅ |
| `prompt-toolkit>=3.0.51` | `prompt_toolkit` | 3.0.52 | ✅ |
| `rich>=14.0.0` | `rich` | 15.0.0 | ✅ |
| `watchdog>=6.0.0` | `watchdog` | 6.0.0 | ✅ (exactly at the floor) |
| test extra: `pytest>=8.4`, `pytest-asyncio>=1.0` | `pytest`, `pytest-asyncio` | 9.1.1, 1.4.0 | ✅ |
All 11 runtime deps + both test deps exist as `pkgs/development/python-modules/<name>/`. `fastmcp-slim`
is present and its own `doCheck = pythonAtLeast "3.14"` confirms 3.14 support.
**Bonus evidence that the nixpkgs dep set reproduces upstream's locked environment** — the versions
`uv.lock` resolved on upstream's own machine are the same ones nixpkgs ships:
| package | `uv.lock` @ head | nixpkgs `eaad0894…` |
| --- | --- | --- |
| pytest | 9.1.1 | 9.1.1 |
| pytest-asyncio | 1.4.0 | 1.4.0 |
| mcp | 1.29.0 | 1.29.0 |
| rich | 15.0.0 | 15.0.0 |
| aiohttp | 3.14.3 | 3.14.3 |
| art | 6.5 | 6.5 |
| watchdog | 6.0.0 | 6.0.0 |
| fastmcp | 3.4.5 | 3.4.7 (only drift, still inside `<4`) |
This is a good signal that `doCheck = true` is realistic rather than optimistic.
Undeclared-but-imported modules to keep in mind (they arrive transitively via `fastmcp`/`mcp`/`rich`,
so no extra `dependencies` entry is normally needed, but they explain a `pythonImportsCheck` failure if
a transitive dep is ever cut): `httpx`, `pygments`, `readline`/`tomllib` (stdlib).
## 4. Pre-build steps / build-time network
**None.** Verified:
- No frontend/JS asset, no protobuf/gRPC/ANTLR codegen, no WASM, no `Makefile`, no `build.sh`,
no asset download script in the tree. `scripts/` holds only `bump_version.py` and
`validate_manual_release.py` (release tooling; CI uses the former to check `server.json` ↔
`pyproject.toml` version parity — irrelevant to the build).
- Upstream's own build is `uv sync --locked` + `uv build`/`uv publish`
(`.github/workflows/publish.yml:86-110`), i.e. plain hatchling.
- Hatchling is a pure-python backend; with `dependencies` supplied from `python3Packages` the build is
fully offline. Nothing to prefetch (no `cargoHash`-style extra fetch).
- The only "asset" handling is hatchling copying non-`.py` files that live inside the `magg/` package
directory (see §6). `[tool.hatch.build.targets.sdist]` (`pyproject.toml:100-119`) only affects the
sdist, not the wheel.
## 5. Test suite & `doCheck` policy
Upstream has a real suite: `test/magg/*.py` — 35 files, 328 `def test_*` (180 `async def`).
CI (`.github/workflows/test.yml`) runs `uv sync --all-groups --locked` then `uv run pytest -v`
(no `-m` filter) on 3.12/3.13/3.14; last run of that workflow: **success** (2026-09-26T16:28Z,
`GET /actions/workflows/test.yml/runs`). No `conftest.py`; `[tool.pytest.ini_options]`
(`pyproject.toml:86-89`) declares only the `integration` marker.
Sandbox-safety audit of the suite:
- **No outbound network in tests.** The discovery clients that *do* hit the network
(`magg/discovery/search.py:32` `registry.modelcontextprotocol.io`, `:144` `glama.ai`,
`:264` `api.github.com`, `:318` `registry.npmjs.org`) are exercised only through canned fixtures
(`test/magg/test_registry_search.py:7-56` `SAMPLE_RESPONSE`) and `monkeypatch`ed methods
(`test/magg/test_cli_fixes.py:118-124`). No `httpx`/`aiohttp`/`requests` call appears in `test/`.
- **Loopback only.** The two e2e tests bind `localhost:54322` (hard-coded,
`test/magg/test_e2e_simple.py:65,91`, `test/magg/test_e2e_mounting.py:129`) and poll for up to 10 s.
Loopback works in the Nix sandbox, but the fixed port + wall-clock polling is the main flake risk.
- **Subprocess tests need `python` on PATH**: `test/magg/test_integration.py:37` and
`test/magg/test_mounting_real.py` spawn `python <generated server.py>` stdio MCP backends;
`test/magg/test_server_robustness.py:374` and `test/magg/test_cli_fixes.py:140` run
`sys.executable -m magg …`. `buildPythonPackage`'s `checkPhase` runs inside its venv, so `python`
resolves and `magg` is importable — satisfied automatically.
- **`$HOME` is read, not written**: `test/magg/test_config.py:95`, `test_auth.py:25`,
`test_config_safety.py:76` assert `Path.home()/".magg"` / `Path.home()/".ssh"/"magg"` defaults;
`test_cli_fixes.py:25` monkeypatches `HOME` to a tmp dir. Scratch space is
`tempfile.TemporaryDirectory()` (→ `$TMPDIR`, writable in the sandbox).
- **`sh` is required**: `test/magg/test_cli_fixes.py:78` runs `subprocess.run(["sh", "-c", …])`
(bash provides `bin/sh` in the build env — fine).
- Timing-sensitive groups: `test_config_reload.py` (watchdog/polling), `test_server_robustness.py`
(hung-backend timeouts).
Recommended policy (mirrors the `packages/marmel/package.nix:33-60` comment style — explain each
workaround and what would let it be dropped):
```nix
nativeCheckInputs = with python3Packages; [ pytestCheckHook pytest-asyncio ];
# Upstream runs the whole suite (`.github/workflows/test.yml`: `uv run pytest -v`), but the three
# `integration`-marked tests (test/magg/test_basic.py:97, test_e2e_mounting.py:18,
# test_e2e_simple.py:16) spawn real stdio/HTTP backends and hard-code localhost:54322 with a
# 10 s poll loop (test_e2e_simple.py:65,91), which is the only flake source in an otherwise
# network-free suite (registry/glama/github/npm clients are monkeypatched in the unit tests).
# Drop this once upstream picks an ephemeral port.
pytestOptions = [ "-m" "not integration" ];
preCheck = ''
# pydantic-settings defaults read $HOME (magg/settings.py:72,203) and the config-reload tests
# poll files under $TMPDIR; keep both inside the writable sandbox tmp dir.
export MAGG_AUTO_RELOAD=false
mkdir -p /tmp/magg-check
export TMPDIR=/tmp/magg-check
export HOME=/tmp/magg-check
'';
pythonImportsCheck = [ "magg" ]; # import magg pulls fastmcp/mcp/aiohttp/cryptography
```
Notes for the implementer:
- `pytest-asyncio` is mandatory in `nativeCheckInputs`: essentially every async test carries
`@pytest.mark.asyncio` (178 marker lines for 180 `async def test_*` definitions) and pytest-asyncio
defaults to strict mode, so unmarked async tests are only skipped. The 2 apparently unmarked ones are
therefore silently skipped upstream too — do not add `-W error`.
- Only the `[project.optional-dependencies] test` extra is needed; the `[dependency-groups] dev`
group additionally pulls `keyring`, `anthropic`, `ruff` — do **not** add those.
- If the suite turns out to be flaky in practice, the repo-wide fallback is
`doCheck = false; pythonImportsCheck = [ "magg" ];` as in `packages/skillsmcp/package.nix:33-34`.
## 6. Install phase
Standard wheel install — **no custom `installPhase` needed.**
- The published wheel contains exactly `magg/**` + `magg-1.3.0.dist-info/` (62 files), so
`buildPythonApplication` puts `$out/lib/python3.14/site-packages/magg/` plus two console scripts
from `entry_points.txt`: `magg = magg.cli:main`, `mbro = magg.mbro.cli:main`
(same as `pyproject.toml:65-67`) → `$out/bin/magg`, `$out/bin/mbro`. Set `mainProgram = "magg";`.
- **Runtime-loaded data files live inside the package dir and must not be stripped**:
`magg/contrib/magg.mbro`, `magg/contrib/readme.md`, `magg/contrib/kit.d/example.json` (confirmed
present in the wheel). `magg/contrib` is a **namespace package with no `__init__.py`**; hatchling
still ships it, and it is discovered at runtime via `magg/util/paths.py:12-15`
(`contrib.__path__`), which feeds the `MAGG_PATH` search list at `magg/settings.py:203`
(`./.magg`, `~/.magg`, contrib dirs) used for `config.json` and `kit.d/`.
⇒ Do not add `disallowedReReferences`/`find -delete` rules for `*.json`/`*.mbro`, and do not
"fix" the missing `__init__.py`.
- Everything else in the repo is *not* installed and must not be: `server.json` (MCP-registry manifest),
`compose.yaml`, `dockerfile`, `docs/`, `examples/`, `scripts/`, and `etc/glama-mcp-api.json`
(a static API dump — `grep -rn "glama-mcp-api" magg/` has no hits; the live code calls
`https://glama.ai/api/mcp/v1/servers` instead).
- No `share/` payloads, no shell completions, no man pages, no `py.typed`.
- Hatchling needs `readme.md` and `license.md` present (`pyproject.toml:6-7`); both are in git and in
the sdist.
## 7. Runtime dependencies
- The Python interpreter wrapper comes from `buildPythonApplication` (shebang points at
`python3`'s `$out`), plus the 11 declared python deps and their transitive closure
(`openssl` via `cryptography`, `readline` — `magg/mbro/arepl.py` imports `readline`, and nixpkgs'
CPython already carries it, `pcre2`/`multidict`/`yarl` C extensions from `aiohttp`).
- **TLS trust store** for the search features: `magg/discovery/search.py:40` builds
`aiohttp.ClientSession(trust_env=True)` against `registry.modelcontextprotocol.io`, `glama.ai`,
`api.github.com`, `registry.npmjs.org`. nixpkgs' OpenSSL/CPython resolve the bundle from
`SSL_CERT_FILE` / `/etc/ssl/certs`, so it works out of the box on NixOS; on non-NixOS hosts users
need `SSL_CERT_FILE` (same class of issue documented in `packages/marmel/package.nix:33-45`).
Adding `cacert` to the *runtime* wrapper is optional, not required.
- **Writable state at runtime**: `CatalogManager` writes `<cwd>/.magg/search_cache.json`
(`magg/discovery/catalog.py:15-16`) and the config lives at `./.magg/config.json` or
`~/.magg/config.json` (`magg/settings.py:203`, `MAGG_CONFIG_PATH`, `MAGG_PATH`, `MAGG_READ_ONLY`).
Worth a `meta` note / NixOS-module hint, nothing build-time.
- **Optional external programs** (only when a user mounts such a server): `npx`/`node`, `uvx`,
`python` for stdio backends — spawned by `fastmcp`, not by magg itself
(`grep -rn "subprocess|Popen" magg/` → no hits). Upstream's image installs `nodejs`/`npm`
(`dockerfile:10`) for that reason. Not a build or hard runtime dep.
- `magg --version` reads `importlib.metadata.version("magg")` (`magg/__init__.py:9-12`) → works
because the dist-info is installed; no source-tree assumption.
## 8. Prior art
**`magg` is not packaged in nixpkgs, and upstream ships no Nix expression.**
- Complete (non-truncated) listing of `pkgs/development/python-modules` at `eaad0894…` → 9949 entries,
none named `magg` (nearest neighbours in that listing: `magic`, `magic-filter`, `magicgui`,
`magic-wormhole`, `magika`).
- `pkgs/top-level/all-packages.nix` at that rev → `grep -i magg` returns nothing (so it is not a
top-level tool either).
- The magg repo (146-entry tree) contains no `.nix` file and no `flake.nix`; upstream's documented
install paths are `uv tool install magg`, `uvx --from git+https://github.com/sitbon/magg.git magg`,
`pip`/`poetry`, and GHCR Docker images.
- Nothing reusable to mirror; write from scratch. Best in-repo template:
`packages/skillsmcp/package.nix` (hatchling + `python3Packages.fastmcp`), with
`packages/nftables-analyzer/package.nix` as the `fetchFromGitHub` + dated-version variant.
## 9. Update mechanism
Use the plain form (repo-wide list style, cf. `packages/agnix/package.nix:34-38`):
```nix
passthru.updateScript = [
"nix-update"
"--flake"
".#magg"
];
```
- Upstream **does** tag releases: `v1.3.0` (2026-09-26) matching PyPI `magg 1.3.0`, and `pyproject.toml`
carries a static `version`, so nix-update's default version detection works — no
`--version=branch=main` (that form is only used in this repo for untagged upstreams, e.g.
`packages/ds4/package.nix:78`, `packages/skillsmcp/package.nix:39`).
- **Caveat if you use `fetchFromGitHub` + `tag = "v${version}"`:** the full tag list (30 tags) also
contains two-part alias tags — `v1.3`, `v1.2`, `v1.1`, `v0.10`, `v0.9`, `v0.8`, `v0.7`, `v0.6` — plus
non-version tags `root`, `latest-release`, `latest-publish` and legacy `magg/v0.5.1.53`-style tags, so
a tag-based bump can pick the `v1.3` alias (a valid tag, but an ugly version string) or a junk tag.
Two clean options:
1. **Preferred:** build from PyPI — `src = fetchPypi { pname = "magg"; inherit version; format = "pyproject"; }`.
The sdist is complete (121 entries: `magg/`, `test/`, `pyproject.toml`, `uv.lock`, `readme.md`,
`license.md`), so `checkPhase` still works, and nix-update's PyPI updater resolves clean versions
deterministically. Ready-made hash for 1.3.0:
`sha256-2jzBtka4YWp4yEGvJorHN/JQpI6sWCrmRu/TtvRnqpU=`
(sha256 `da3cc1b646b8616a78c841af268ac737f250a48eac582ae646efd3b6f467aa95`).
2. Keep `fetchFromGitHub` (rev = tag `v1.3.0`) and pin the updater with `--version=tag`, then verify
the picked version is the 3-part tag.
---
### One-paragraph summary for the implementer
`magg` is a pure-python hatchling project: use `python3Packages.buildPythonApplication` with
`pyproject = true`, `build-system = [ python3Packages.hatchling ]`, and all 11 runtime deps taken from
`python3Packages` (all present and new enough on the overlay's pinned `nixos-unstable`, whose default
`python3` is 3.14 — exactly upstream's `.python-version`). No lockfile hash, no vendorHash, no
pre-build codegen, no asset fetch, no custom install phase; two console scripts (`magg`, `mbro`) and
the `magg/contrib/**` data files come along via the wheel. Run the test suite (`pytest` +
`pytest-asyncio`) with `-m "not integration"` and a tmp `$HOME`/`$TMPDIR` in `preCheck`, keep
`pythonImportsCheck = [ "magg" ]`, set `mainProgram = "magg"`, license `agpl3Plus`
(`license = {text = "AGPL-3.0-or-later"}`), and update with plain `nix-update --flake .#magg`
(prefer `fetchPypi` over `fetchFromGitHub` because upstream also publishes `v1.3`-style alias tags).
MISSION COMPLETE (t-002)
+343
View File
@@ -0,0 +1,343 @@
# 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.toml` with the `hatchling` build backend**, project managed
with **uv** (a committed `uv.lock` and `.python-version` are present). There is **no**
`Cargo.toml`, `package.json`, `go.mod`, `Makefile`, `justfile`, or `setup.py`.
Evidence: root listing of tag `v1.3.0` via
`https://api.github.com/repos/sitbon/magg/contents/?ref=v1.3.0` and
`https://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):
```toml
[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`**, committed `2026-09-27T19:05:55Z`
("Add security policy"). Verified as a descendant of `v1.3.0` (the only extra commit adds
`security.md`), so **`v1.3.0` is the right packaging rev**.
- Other branches: `beta` (`774636eb…`, feeds the `ghcr.io/sitbon/magg:beta` image), plus two
stale `claude/*` 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`; wheel `METADATA` has
`License: 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:
```ini
[console_scripts]
magg = magg.cli:main
mbro = magg.mbro.cli:main
```
- `meta.mainProgram = "magg";`
- Second binary: **`mbro`** (the "MCP Browser" interactive CLI, documented in `docs/mbro.md`).
Set `meta.mainProgram` to `magg` and expect both `bin/magg` and `bin/mbro` in the output.
- `python -m magg` and `python -m magg.mbro` also work (`magg/__main__.py`,
`magg/mbro/__main__.py` exist in the wheel).
- Upstream install docs' primary entry point is `uv tool install magg` then `magg 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 to `pyproject.toml` (hatchling auto-detects it; no `[tool.hatch.build]` wheel
`packages` override). **No Cargo/npm workspace, no `src/` layout, no sub-crate.**
- Package subpackages inside `magg/`: `contrib/`, `discovery/`, `logs/`, `mbro/`, `proxy/`,
`server/`, `util/` — 66 files total in `magg/`.
- **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 omits `etc/`. 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 being `uv.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/`) —
a `checkPhase` can run `pytest` from the unpacked sdist. `pyproject.toml` registers the
`integration` marker; 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 with `pyproject.toml`
by `scripts/bump_version.py --check`), `docs/` (11 markdown files, `docs/index.md` is 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".
```bash
# 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";`** (matches `server.json.websiteUrl`).
Note: the GitHub repo's own `homepage` field points to `https://pypi.org/project/magg/` —
use the GitHub URL for `meta.homepage` (per manifest) and add
`https://pypi.org/project/magg/` as a source/download location.
- **`meta.changelog = "https://github.com/sitbon/magg/releases";`** — there is **no
`CHANGELOG`/`HISTORY` file anywhere in the repo** (verified via the full recursive git tree of
`v1.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), plus `docs/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/magg` on `https://registry.modelcontextprotocol.io`.
---
## 9. Supported platforms
- **Declared: OS-independent, CPython only.** `pyproject.toml` classifiers include
`"Operating System :: OS Independent"` and `"Programming Language :: Python :: 3 :: Only"` /
`Implementation :: CPython`; `requires-python = ">=3.12"` (3.12/3.13/3.14 listed).
No `platform_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 by `if 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 the `rich`/`prompt-toolkit` REPL
when not interactive.
- `magg/mbro/arepl.py:110` prints `f"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 target `x86_64-linux` with libc-agnostic Python; nothing in pure-Python Magg itself is
libc-specific (only `cryptography`/`aiohttp` wheels matter).
- Termux/Android is implicitly considered (commit `1b18b87f` notes that Termux sets env vars
like `PREFIX`/`URI`/`KEY_PATH`, which Magg's config models no longer read).
- **Practical conclusion for `meta.platforms`:** `lib.platforms.all`-ish (pure `py3-none-any`
wheel, `Operating System :: OS Independent`); upstream *tests* Linux only, and the interactive
`mbro` REPL + 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)
+5
View File
@@ -0,0 +1,5 @@
{
pkgs,
...
}:
pkgs.callPackage ./package.nix { }
+171
View File
@@ -0,0 +1,171 @@
{
lib,
python3Packages,
fetchFromGitHub,
}:
python3Packages.buildPythonApplication rec {
pname = "magg";
version = "1.3.0";
pyproject = true;
# Upstream emits an alias tag for every release that points at the same commit
# (v1.3 -> 1b18b87fdcda, the very commit v1.3.0 peels to) plus a moving
# `latest-publish`/`latest-release` tag, a `root` tag and legacy
# `magg/v0.5.1.53`-style names. nix-update normally picks the dotted tag, but
# eyeball every bump so the version does not silently degrade to "1.3".
src = fetchFromGitHub {
owner = "sitbon";
repo = "magg";
rev = "v${version}";
hash = "sha256-Dj8f+MwefUD5wk4JFTkrC72QGqfJoWQd8ToOeNI6rmM=";
};
# PEP 621 + hatchling (pyproject.toml [build-system]). Pure Python: the wheel
# is py3-none-any, needs no compiler, and `[build-system] requires =
# ["hatchling"]` is unpinned, so no pin-relaxing patch is needed.
build-system = with python3Packages; [
hatchling
];
# The 11 runtime imports of [project.dependencies], each present in nixpkgs and
# at or above upstream's floor (fastmcp 3.4.7, mcp 1.29.0, aiohttp 3.14.3,
# pydantic 2.13.4, pydantic-settings 2.12.0, rich 15.0.0, prompt-toolkit 3.0.52,
# cryptography 50.0.0, pyjwt 2.13.0, watchdog 6.0.0, art 6.5). Upstream commits
# only `uv.lock`, which Nix does not consume, so there is no vendorHash: the
# dependency closure comes from python3Packages and the wheel build is offline.
dependencies = with python3Packages; [
aiohttp
art
cryptography
fastmcp
mcp
prompt-toolkit
pydantic
pydantic-settings
pyjwt
rich
watchdog
];
# [project.optional-dependencies] test = pytest + pytest-asyncio; pytest-asyncio
# is mandatory because ~180 async tests carry @pytest.mark.asyncio and its strict
# mode silently skips unmarked coroutines. pytestCheckHook only contributes
# pytest itself (see dontUsePytestCheck below). The `dev` dependency-group extras
# (keyring, anthropic, packaging, ruff) are release/lint tooling and are
# deliberately not pulled in.
nativeCheckInputs = with python3Packages; [
pytestCheckHook
pytest-asyncio
];
doCheck = true;
# mcp's stdio client starts every backend with a hand-picked environment:
# mcp/client/stdio/__init__.py `get_default_environment()` keeps only HOME,
# LOGNAME, PATH, SHELL, TERM and USER, so PYTHONPATH never reaches a backend
# process. Upstream's CI runs pytest from a uv venv, where `python` and
# `sys.executable` already carry the dependencies in their own site-packages;
# run the suite on nixpkgs' plain interpreter and the 12 tests that mount a
# real stdio backend (test_in_memory.py, test_mounting_real.py,
# test_client_mounting.py, test_server_robustness.py, test_transport.py) die
# with "ModuleNotFoundError: No module named 'fastmcp'" and then report the
# resulting "Connection closed" as a missing tool. Two of them
# (test_transport.py:36,51) additionally assert that the resolved interpreter
# ends in "python"/"python3", which the store path
# <store>-python3.14.7/bin/python3.14 never does.
#
# So recreate the venv layout instead of skipping those tests, and run pytest
# from it. pytestCheckHook cannot do this: its phase hard-codes the unwrapped
# interpreter path, and it ignores the obsolete `pytestOptions` attribute
# entirely (it only reads pytestFlags/pytestFlagsArray and the
# enabled/disabledTestMarks lists), which is why the marker deselection is
# spelled out in the command line below.
dontUsePytestCheck = true;
checkPhase = ''
runHook preCheck
# `--without-pip`: the sandbox has no network and nothing is installed into
# this venv. The .pth mirrors PYTHONPATH (which pypa-install-hook has already
# extended with $out/lib/python3.14/site-packages) into the venv's own
# site-packages, i.e. into sys.path entries that survive the stripped child
# environment, so a backend spawned as `sys.executable server.py` can import
# magg, fastmcp and friends without any environment variable.
venv="$TMPDIR/magg-check/venv"
mkdir -p "$venv"
python -m venv --without-pip "$venv"
# Written with Python's os.linesep rather than `tr ':' '\n'`: that backslash
# escape does not survive the Nix indented string verbatim (the .pth came out
# joined by literal backslashes instead of newlines, so site.py never split
# it), and a here-doc for one line would be more noise than signal.
python -c 'import os; print(os.environ["PYTHONPATH"].replace(":", os.linesep))' \
> "$venv/lib/${python3Packages.python.libPrefix}/site-packages/nix-pythonpath.pth"
# First on PATH so the tests that mount a backend through
# NoValidatePythonStdioTransport, whose python_cmd defaults to the bare string
# "python" (test_mounting_real.py:44, test_client_mounting.py:41), pick the
# same venv interpreter.
export PATH="$venv/bin:$PATH"
# `-m "not integration"`: the three integration tests (test/magg/test_basic.py:97,
# test_e2e_mounting.py:18, test_e2e_simple.py:16) boot a real HTTP backend on
# the hard-coded localhost:54321/54322 and poll it for up to 10 s
# (test_e2e_simple.py:65,91). That fixed port plus wall-clock polling is the
# only flake source in an otherwise network-free suite (the registry/glama/
# github/npm discovery clients are monkeypatched in the unit tests), so every
# remaining test is selected and runs for real. A handful of them skip
# themselves: upstream capability guards in test/magg/test_client_api.py
# probe whether the installed fastmcp exposes a given Client API variant
# (command keyword syntax, positional command syntax, WebSocket URLs) and
# report a skip when it does not - upstream's own skips, not a packaging
# defect. No test count is quoted here on purpose: the suite grows on almost
# every bump, so any hard-coded number rots immediately. Drop the marker
# filter once upstream picks an ephemeral port.
"$venv/bin/python" -m pytest test/magg -m "not integration"
runHook postCheck
'';
# Two plausible sandbox hardenings are deliberately absent:
# - MAGG_AUTO_RELOAD=false (the config-reload watcher otherwise starts poller
# threads): pydantic-settings reads that variable into the config default, so
# pinning it breaks the 5 tests that assert the shipped default - 2 in
# test_config_safety.py and 3 in test_config_reload.py.
# - a pinned HOME/TMPDIR: the suite only reads $HOME for the ~/.magg and
# ~/.ssh/magg defaults (test_config.py:95, test_auth.py:25,
# test_config_safety.py:76) and keeps scratch state in tempfile directories,
# so the sandbox defaults (HOME=/homeless-shelter, TMPDIR=/build) are enough -
# verified by running the suite with HOME=/homeless-shelter.
# Importing magg pulls in fastmcp/mcp/aiohttp/cryptography, so this still
# catches a cut transitive dependency if the check phase is ever disabled.
pythonImportsCheck = [ "magg" ];
passthru = {
category = "MCP Servers";
updateScript = [
"nix-update"
"--flake"
".#magg"
];
};
meta = {
description = "MCP aggregator server that manages, aggregates and proxies other MCP servers so LLMs can discover, add and manage tools at runtime";
homepage = "https://github.com/sitbon/magg";
changelog = "https://github.com/sitbon/magg/releases";
# pyproject.toml `license = {text = "AGPL-3.0-or-later"}`, matching license.md
# (the verbatim AGPLv3 text, shipped as license.md rather than LICENSE).
license = lib.licenses.agpl3Plus;
sourceProvenance = with lib.sourceTypes; [ fromSource ];
# [project.scripts] installs `magg` (magg.cli:main) and `mbro`
# (magg.mbro.cli:main); `magg` is the documented entry point.
mainProgram = "magg";
# Pure py3-none-any wheel, "Operating System :: OS Independent" classifier and
# no platform markers in the dependency set. The SIGHUP config reload is
# guarded by hasattr(signal, "SIGHUP") and the interactive mbro REPL degrades
# on non-TTY stdout, so nothing is Unix-only in practice.
platforms = lib.platforms.all;
maintainers = [ ];
};
}