Files
alex 44e6d90a77
CI / check (push) Has been cancelled
feat(magg): add magg 1.3.0 MCP aggregator package
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.
2026-11-08 12:48:30 +03:00

368 lines
17 KiB
Markdown

# 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`.