You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@incubator.apache.org by jm...@apache.org on 2026/09/14 08:27:22 UTC
(incubator) branch master updated (f0d2e67a2 -> fbdde9698)
This is an automated email from the ASF dual-hosted git repository.
justinmclean pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/incubator.git
from f0d2e67a2 fixed an RC naming issue
new d2c853709 Fixed looking at wrong license file when mukltiple exist
new 38e068845 Add MCP server setup for the release check skill
new c365e5f62 Keep release check findings independent of the vote thread
new fbdde9698 Note the dev@ arguments for summarize_release_vote_thread
The 4 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
tools/skills/releasecheck/Makefile | 40 +-
tools/skills/releasecheck/README.md | 51 +++
tools/skills/releasecheck/SKILL.md | 22 +-
tools/skills/releasecheck/references/tools.md | 9 +-
tools/skills/releasecheck/scripts/check_rc.py | 18 +-
tools/skills/releasecheck/scripts/setup_mcps.py | 418 +++++++++++++++++++++
tools/skills/releasecheck/scripts/test_check_rc.py | 6 +
7 files changed, 548 insertions(+), 16 deletions(-)
create mode 100644 tools/skills/releasecheck/scripts/setup_mcps.py
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org
(incubator) 03/04: Keep release check findings independent of the vote thread
Posted by jm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
justinmclean pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator.git
commit c365e5f62a86e84bbcefe2d7fc5f1adb6c3282b9
Author: Justin Mclean <jm...@apache.org>
AuthorDate: Mon Sep 14 17:54:14 2026 +1000
Keep release check findings independent of the vote thread
SKILL.md now does its own checks before reading replies in the current vote, then marks what voters also raised or it missed, and judges -1s against policy. setup_mcps.py approves MCP tool calls for Codex, which never asks in exec mode.
---
tools/skills/releasecheck/SKILL.md | 22 +++++++++++++++++++---
tools/skills/releasecheck/scripts/setup_mcps.py | 5 ++++-
2 files changed, 23 insertions(+), 4 deletions(-)
diff --git a/tools/skills/releasecheck/SKILL.md b/tools/skills/releasecheck/SKILL.md
index 69369b4eb..3567b4ddf 100644
--- a/tools/skills/releasecheck/SKILL.md
+++ b/tools/skills/releasecheck/SKILL.md
@@ -24,6 +24,11 @@ looked at.
Get the podling, RC, tag and dist/dev URL from the vote email. If only a name
is given, confirm it's a current podling with `podlings:get_podling`.
+Read only the opening message of this RC's vote threads, on dev@ and
+general@, until step 7. Replies, including other people's votes and "I
+checked" lists, come after your own checks. Otherwise their findings can't be
+told apart from yours, and their severity replaces your judgement.
+
Step 4 needs a shell with network access. Without one, do the other steps and
say the archive contents were not checked.
@@ -51,7 +56,8 @@ then read every -1, 0, CANCEL and "I checked" message in full with
`get_incubator_general_email`. Check the dev list for the PPMC vote with
`search_podling_mail`. Each issue found becomes a check in step 5: is it
fixed in this RC? Read the messages rather than adding up a tally
-(`references/tools.md`).
+(`references/tools.md`). This means earlier RCs and releases only; skip
+replies in this RC's own threads, which are step 7.
## 3. Inventory
@@ -106,6 +112,16 @@ the IPMC vote has passed?
## 7. Report
+Write your findings down first. Then read the replies in this RC's vote
+threads and reconcile:
+
+- A finding a voter also raised stays yours; add "also raised by" and a link.
+- Something a voter raised that you missed goes in with "raised in the
+ thread by" and a link, and is not in "I checked".
+- Judge each voter's point against policy yourself. A -1 is not a blocker
+ because it is a -1: release votes can't be vetoed, and plenty of -1s are
+ about bugs or next-release cleanup rather than what may be released.
+
1. Previously raised: each issue, fixed or not, with a link.
2. Must fix, needs a new RC: findings that change what is inside an archive,
so the artifacts have to be rebuilt and re-signed. Path, evidence and
@@ -123,8 +139,8 @@ Sorting between 2 and 3 is the useful judgement. Ask whether fixing it
changes a byte of any artifact. If it does not, the release manager can fix
it during the vote and the vote stands.
-For a mailing list, use the IPMC style: an "I checked:" list, then the
-issues, no headings or bold, no vote. If nothing is found, say what was
+For a mailing list, use the IPMC style: an "I checked:" list of what you
+checked yourself, then the issues, no headings or bold, no vote. If nothing is found, say what was
checked; don't call the release compliant.
## 8. Vote result (only when asked)
diff --git a/tools/skills/releasecheck/scripts/setup_mcps.py b/tools/skills/releasecheck/scripts/setup_mcps.py
index d35e6093b..845d278e9 100644
--- a/tools/skills/releasecheck/scripts/setup_mcps.py
+++ b/tools/skills/releasecheck/scripts/setup_mcps.py
@@ -296,7 +296,10 @@ class Codex(Target):
def block(name, cmd):
# JSON string escapes are valid TOML basic strings.
args = ", ".join(json.dumps(a) for a in cmd[1:])
- return f"\n[mcp_servers.{name}]\ncommand = {json.dumps(cmd[0])}\nargs = [{args}]\n"
+ # codex exec never asks for approval, so without this every MCP call is
+ # refused. These servers are all read-only.
+ return (f"\n[mcp_servers.{name}]\ncommand = {json.dumps(cmd[0])}\nargs = [{args}]\n"
+ 'default_tools_approval_mode = "approve"\n')
def snippet(self, commands):
return "".join(self.block(n, c) for n, c in commands.items())
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org
(incubator) 01/04: Fixed looking at wrong license file when mukltiple exist
Posted by jm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
justinmclean pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator.git
commit d2c8537091d6ba01ca408db52b702f4a744cec35
Author: Justin Mclean <jm...@apache.org>
AuthorDate: Mon Sep 14 16:50:34 2026 +1000
Fixed looking at wrong license file when mukltiple exist
---
tools/skills/releasecheck/scripts/check_rc.py | 18 +++++++++++++++---
tools/skills/releasecheck/scripts/test_check_rc.py | 6 ++++++
2 files changed, 21 insertions(+), 3 deletions(-)
diff --git a/tools/skills/releasecheck/scripts/check_rc.py b/tools/skills/releasecheck/scripts/check_rc.py
index 39391a9f2..fd76b0812 100644
--- a/tools/skills/releasecheck/scripts/check_rc.py
+++ b/tools/skills/releasecheck/scripts/check_rc.py
@@ -98,6 +98,9 @@ LEGAL_DIR_NAMES = {"licenses", "licences", "license", "licence", "legal", "licen
# "licenses/LICENSE-[project].txt". A path that runs into one of these is a
# worked example for the reader, not a file the archive is meant to contain.
PLACEHOLDER_OPENERS = "[<{(%$*"
+# Suffixes a real LICENSE/NOTICE file can carry. Anything else after the
+# stem (LICENSE.header, NOTICE.vm) is a build input, not the document.
+TEXT_SUFFIXES = {"", ".txt", ".md", ".rst", ".adoc"}
HIDDEN_JUNK = {".DS_Store", "Thumbs.db", ".git", ".svn", ".idea", ".vscode"}
# macOS resource-fork sidecars. bsdtar folds them back into extended attributes
# and does not list them, so a reviewer on macOS never sees them; GNU tar and
@@ -641,9 +644,13 @@ def compare_al2(text):
def check_root_files(root, label, rc_year, f, templates=None):
templates = templates or {}
- names = set(os.listdir(root))
+ # Sorted, because the choice between LICENSE and LICENSE.header must not
+ # depend on the order the filesystem happens to return.
+ names = sorted(os.listdir(root))
for req in ("LICENSE", "NOTICE"):
- hits = [n for n in names if n == req or n.startswith(req + ".")]
+ hits = [n for n in names if n == req] + \
+ [n for n in names if n != req and n.startswith(req + ".")
+ and os.path.splitext(n)[1].lower() in TEXT_SUFFIXES]
if hits:
f.ok("root-files", f"{req} present", path=f"{label}/{hits[0]}")
else:
@@ -707,7 +714,12 @@ def check_root_files(root, label, rc_year, f, templates=None):
path=f"{label}/{notice}", evidence=text[max(0, m.start() - 150):m.end() + 150])
f.info("notice", "NOTICE text for review", path=f"{label}/{notice}", evidence=text[:4000])
- lic = next((n for n in names if n == "LICENSE" or n.startswith("LICENSE.")), None)
+ # "LICENSE" itself first, then a plain-text variant. Never LICENSE.header,
+ # which is the header template a build stamps into source files, not the
+ # licence of the release.
+ lic = next((n for n in sorted(names) if n == "LICENSE"), None) or \
+ next((n for n in sorted(names) if n.startswith("LICENSE.")
+ and os.path.splitext(n)[1].lower() in TEXT_SUFFIXES), None)
if lic:
text = read_text(os.path.join(root, lic)) or ""
if "Apache License" not in text[:400] or "Version 2.0" not in text[:600]:
diff --git a/tools/skills/releasecheck/scripts/test_check_rc.py b/tools/skills/releasecheck/scripts/test_check_rc.py
index c4caf41e2..bfdb593bd 100644
--- a/tools/skills/releasecheck/scripts/test_check_rc.py
+++ b/tools/skills/releasecheck/scripts/test_check_rc.py
@@ -122,6 +122,10 @@ def build(tmp):
"dist-material/licenses/ui-licenses/license-vben.txt\n")
w(f"{s}/dist-material/licenses/ui-licenses/license-vben.txt", "MIT\n")
w(f"{s}/licenses/LICENSE-unused.txt", "MIT stub\n")
+ # A build input, not the licence of the release. Picking this instead of
+ # LICENSE made the whole AL2 text look missing, and which one won depended
+ # on the order the filesystem listed them in.
+ w(f"{s}/LICENSE.header", "Licensed to the Apache Software Foundation (ASF) under one\n")
w(f"{s}/licenses/LICENSE-mitlib.txt", "Copyright (c) 2014 Someone\nPermission is hereby granted\n")
w(f"{s}/test/data.xlsx", b"PK\x03\x04\x00\x00xlsx")
w(f"{s}/NOTICE", "Apache Demo (Incubating)\nCopyright 2024 The Apache Software Foundation\n\n"
@@ -318,6 +322,8 @@ def main():
or (i["check"] == "license" and "LICENSES/" in (i["path"] or ""))
or ("DISCLAIMER-BINARIES" in (i["path"] or "")
and i["kind"] in ("fail", "candidate"))
+ or ("LICENSE.header" in (i["path"] or "")
+ and i["check"] in ("license", "license-text", "root-files"))
or (i["check"] == "license" and i["kind"] == "fail"
and "vben" in json.dumps(i["evidence"] or ""))
or (i["check"] in ("root-files", "disclaimer") and i["kind"] == "fail"
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org
(incubator) 04/04: Note the dev@ arguments for summarize_release_vote_thread
Posted by jm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
justinmclean pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator.git
commit fbdde96982e199edd84869f33eaf4005a8e6bd75
Author: Justin Mclean <jm...@apache.org>
AuthorDate: Mon Sep 14 18:03:59 2026 +1000
Note the dev@ arguments for summarize_release_vote_thread
It takes list_name and domain, not podling. Also drop the note that a message with no vote counts as 0, which is no longer true.
---
tools/skills/releasecheck/references/tools.md | 9 ++++++---
1 file changed, 6 insertions(+), 3 deletions(-)
diff --git a/tools/skills/releasecheck/references/tools.md b/tools/skills/releasecheck/references/tools.md
index 4d1fc84d2..ed3e8d77d 100644
--- a/tools/skills/releasecheck/references/tools.md
+++ b/tools/skills/releasecheck/references/tools.md
@@ -36,9 +36,12 @@ carry on. Do not skip the step. All of these were checked and answer:
roster; that was corrected and its `binding` flags can be relied on. Two
things still need care. It returns one row per message, not per voter, so
someone who votes and then joins the discussion appears several times, and
- the opening [VOTE] call itself appears as a row. A message with no vote in
- it is reported as a 0. So take each person's latest actual vote rather than
- adding the rows up, which is what step 8 says to do anyway.
+ the opening [VOTE] call itself appears as a row, with no vote. So take each
+ person's latest actual vote rather than adding the rows up, which is what
+ step 8 says to do anyway.
+- `summarize_release_vote_thread` takes no `podling` argument. For a dev@
+ thread pass `list_name="dev"` and `domain`, which
+ `resolve_podling_mail_domain(podling, list_name="dev")` returns.
- `search_incubator_general_mail` ignores quotation marks. Narrow with
`timespan`.
- An empty search means nothing matched, not that nothing was said. Check
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org
(incubator) 02/04: Add MCP server setup for the release check skill
Posted by jm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
justinmclean pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator.git
commit 38e068845216603b06001037439e23de97867d92
Author: Justin Mclean <jm...@apache.org>
AuthorDate: Mon Sep 14 17:30:25 2026 +1000
Add MCP server setup for the release check skill
setup_mcps.py installs the six MCP servers and registers them with Claude Code, Claude Desktop, Codex or OpenCode, asking first and backing up each config file. make install now puts the skill into each client that is present.
---
tools/skills/releasecheck/Makefile | 40 ++-
tools/skills/releasecheck/README.md | 51 +++
tools/skills/releasecheck/scripts/setup_mcps.py | 415 ++++++++++++++++++++++++
3 files changed, 499 insertions(+), 7 deletions(-)
diff --git a/tools/skills/releasecheck/Makefile b/tools/skills/releasecheck/Makefile
index 6ab27bc1b..653e52499 100644
--- a/tools/skills/releasecheck/Makefile
+++ b/tools/skills/releasecheck/Makefile
@@ -10,19 +10,34 @@ SKILLS := $(abspath $(CURDIR)/..)
PACKAGER := $(SKILLS)/package-skills.py
DIST := $(SKILLS)/dist
PACKAGE := $(DIST)/$(SKILL).skill
-INSTALL := $(HOME)/.claude/skills
+
+# make install puts the skill into each client that is present. OpenCode also
+# reads ~/.claude/skills, so it only gets its own copy when there is no
+# ~/.claude; two copies just produce "duplicate skill name" warnings.
+CLAUDE_HOME ?= $(HOME)/.claude
+CLAUDE_SKILLS ?= $(CLAUDE_HOME)/skills
+CODEX_HOME ?= $(HOME)/.codex
+CODEX_SKILLS ?= $(CODEX_HOME)/skills
+XDG_CONFIG_HOME ?= $(HOME)/.config
+OPENCODE_HOME ?= $(XDG_CONFIG_HOME)/opencode
+OPENCODE_SKILLS ?= $(OPENCODE_HOME)/skills
+OPENCODE ?= $(shell command -v opencode)
PYTHON ?= python3
OUT ?= output
TAGDIR ?=
+MCP_ARGS ?=
.DEFAULT_GOAL := help
-.PHONY: help test build install check clean
+.PHONY: help test build install mcp check clean
help:
@echo "make test run the regression test (44 planted faults, 20 unit checks)"
@echo "make build test, then package to $(DIST)/$(SKILL).skill"
- @echo "make install build, then unpack into $(INSTALL)/"
+ @echo "make install build, then unpack into the skills directory of each client present:"
+ @echo " Claude Code, Codex, and OpenCode when there is no ~/.claude"
+ @echo "make mcp install the six MCP servers and register them with Claude Code,"
+ @echo " asking first: make mcp [MCP_ARGS=\"--desktop --codex --opencode\"]"
@echo "make check run the checker on a real RC:"
@echo " make check URL=<dist/dev RC dir> PODLING=<slug> [TAGDIR=<checkout>] [OUT=dir]"
@echo "make clean remove $(OUT)/, __pycache__ and the built package"
@@ -39,10 +54,21 @@ build: test
@$(PYTHON) $(PACKAGER) $(CURDIR)
install: build
- @mkdir -p $(INSTALL)
- @rm -rf $(INSTALL)/$(SKILL)
- @unzip -q $(PACKAGE) -d $(INSTALL)
- @echo "installed to $(INSTALL)/$(SKILL)"
+ @installed=; \
+ put() { mkdir -p "$$1" && rm -rf "$$1/$(SKILL)" && unzip -q $(PACKAGE) -d "$$1" || exit 1; \
+ echo "installed to $$1/$(SKILL)"; installed=1; }; \
+ if [ -d "$(CLAUDE_HOME)" ]; then put "$(CLAUDE_SKILLS)"; fi; \
+ if [ -d "$(CODEX_HOME)" ]; then put "$(CODEX_SKILLS)"; fi; \
+ if [ ! -d "$(CLAUDE_HOME)" ] && { [ -d "$(OPENCODE_HOME)" ] || [ -n "$(OPENCODE)" ]; }; then \
+ put "$(OPENCODE_SKILLS)"; fi; \
+ if [ -z "$$installed" ]; then \
+ echo "no Claude Code, Codex or OpenCode found; using the Claude Code location"; \
+ put "$(CLAUDE_SKILLS)"; fi
+
+# Separate from install: the skill works without the servers, and this clones
+# and pip-installs from GitHub and asks before touching any client config.
+mcp:
+ @$(PYTHON) scripts/setup_mcps.py $(MCP_ARGS)
check:
@test -n "$(URL)$(RCDIR)" || { \
diff --git a/tools/skills/releasecheck/README.md b/tools/skills/releasecheck/README.md
index cf95abad9..7be02a278 100644
--- a/tools/skills/releasecheck/README.md
+++ b/tools/skills/releasecheck/README.md
@@ -15,6 +15,7 @@ a review.
| --- | --- |
| `SKILL.md` | The review process, eight steps. The agent's entry point. |
| `scripts/check_rc.py` | The mechanical checks. Standard library plus the `gpg` binary, no MCP, no third-party packages. |
+| `scripts/setup_mcps.py` | Installs the MCP servers below and registers them, asking first. Not needed to run the checker. |
| `scripts/test_check_rc.py` | Regression test. Builds a release candidate with known faults, runs the checker over it, asserts every planted fault is found and that known false positives stay absent. |
| `references/checks.md` | What each check means and how to judge it. Read when working through candidates. |
| `references/tools.md` | Quirks of the MCP servers the review steps use. |
@@ -62,6 +63,56 @@ and a review still works without them at reduced coverage.
`references/tools.md` records each server's quirks and, for each one, the
public endpoint to fetch directly when it is not installed.
+### Installing them
+
+```
+make mcp # or: python3 scripts/setup_mcps.py
+make mcp MCP_ARGS=--desktop # also register with Claude Desktop
+make mcp MCP_ARGS=--codex # also register with Codex
+make mcp MCP_ARGS=--opencode # also register with OpenCode
+make mcp MCP_ARGS=--dry-run # show the steps, change nothing
+```
+
+`scripts/setup_mcps.py` needs git, Python 3.12 or later, and Node with npm
+for `apache-projects-mcp`. It clones each server into `~/.asf-mcp/src`
+(`--dir` to change), installs the Python ones into a single virtual
+environment there, and runs `npm install` for the Node one. Running it again
+pulls updates into the existing checkouts.
+
+Before changing any config it lists what it would add to which file and asks.
+On a yes it backs up each file it is about to change, next to the original as
+`<file>.<timestamp>.bak`, then registers the servers:
+
+| Client | Where | How |
+| --- | --- | --- |
+| Claude Code | `~/.claude.json` | `claude mcp add -s user` |
+| Claude Desktop, `--desktop` | `claude_desktop_config.json` | `mcpServers` entries |
+| Codex, `--codex` | `~/.codex/config.toml` (`$CODEX_HOME`) | `[mcp_servers.<name>]` tables appended to the end, so nothing already there is rewritten |
+| OpenCode, `--opencode` | `~/.config/opencode/opencode.jsonc` or `.json` | `mcp` entries of type `local` |
+
+A server already registered under the same name is left as it is, so an
+existing setup is never overwritten, and a file with nothing to add is neither
+changed nor backed up. A client that is not installed is skipped. A config
+file the script cannot parse safely, such as an `opencode.jsonc` with
+comments, is left alone and the entries are printed to paste in by hand.
+`--no-claude-code` registers only the clients named, `--yes` skips the question, `--no-register` installs without touching config,
+and `--only <name>...` limits it to some servers.
+
+`make install` does not run this, and needs neither the servers nor any
+desktop app. It unpacks the skill into each client that is present:
+
+| Present | Installed to |
+| --- | --- |
+| `~/.claude` | `~/.claude/skills` |
+| `~/.codex` | `~/.codex/skills` |
+| OpenCode, and no `~/.claude` | `~/.config/opencode/skills` |
+| none of them | `~/.claude/skills` |
+
+OpenCode also reads `~/.claude/skills`, so when both are present it uses that
+copy; a second one would only give "duplicate skill name" warnings. OpenCode
+counts as present when `~/.config/opencode` exists or `opencode` is on the
+PATH.
+
## Running the checker on its own
```
diff --git a/tools/skills/releasecheck/scripts/setup_mcps.py b/tools/skills/releasecheck/scripts/setup_mcps.py
new file mode 100644
index 000000000..d35e6093b
--- /dev/null
+++ b/tools/skills/releasecheck/scripts/setup_mcps.py
@@ -0,0 +1,415 @@
+#!/usr/bin/env python3
+"""Install and register the MCP servers the releasecheck review steps use.
+
+check_rc.py needs none of these. The review steps in SKILL.md use six, all
+read-only, and still work without them at reduced coverage.
+
+What it does:
+ 1. Clones or updates each server under --dir (default ~/.asf-mcp).
+ 2. Puts the Python servers in one virtual environment there, and runs
+ npm install for the Node one.
+ 3. Shows what it would add to which config file and asks before changing
+ anything. On a yes, backs up each file it will change, then registers
+ the servers with Claude Code (user scope) and, when asked, Claude
+ Desktop, Codex and OpenCode.
+
+Running it again updates the existing checkouts with git pull rather than
+cloning again.
+
+A server already registered under the same name is left alone, so an existing
+setup is never overwritten. Standard library only.
+
+ python3 scripts/setup_mcps.py install and register
+ python3 scripts/setup_mcps.py --dry-run show what would happen
+ python3 scripts/setup_mcps.py --desktop also add to Claude Desktop
+ python3 scripts/setup_mcps.py --codex also add to Codex
+ python3 scripts/setup_mcps.py --opencode also add to OpenCode
+ python3 scripts/setup_mcps.py --no-register install only
+ python3 scripts/setup_mcps.py --yes do not ask before registering
+"""
+
+import argparse
+import datetime
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+GITHUB = "https://github.com/justinmclean"
+
+# name: (repo, kind, console script or entry file). The ipmc server pulls in
+# its own dependencies (health, reports, mail, releases, podlings, trademark)
+# from GitHub when it is installed.
+SERVERS = {
+ "asf-policy": ("PolicyMCP", "python", "asf-policy-mcp"),
+ "incubator-mail": ("MailMCP", "python", "incubator-mail-mcp"),
+ "incubator-releases": ("ReleaseMCP", "python", "incubator-releases-mcp"),
+ "podlings": ("PodlingsMCP", "python", "podlings-mcp"),
+ "ipmc": ("IncubatorMCP", "python", "ipmc-mcp"),
+ "apache-projects-mcp": ("apache-projects-mcp", "node", "index.js"),
+}
+
+# podlings and ipmc need 3.12; the rest need 3.10 or 3.11.
+MIN_PYTHON = (3, 12)
+
+CLAUDE_CODE_CONFIG = os.path.expanduser("~/.claude.json")
+if sys.platform == "darwin":
+ DESKTOP_CONFIG = os.path.expanduser(
+ "~/Library/Application Support/Claude/claude_desktop_config.json")
+elif os.name == "nt":
+ DESKTOP_CONFIG = os.path.join(os.environ.get("APPDATA", ""), "Claude",
+ "claude_desktop_config.json")
+else:
+ DESKTOP_CONFIG = os.path.expanduser("~/.config/Claude/claude_desktop_config.json")
+
+CODEX_CONFIG = os.path.join(os.environ.get("CODEX_HOME") or os.path.expanduser("~/.codex"),
+ "config.toml")
+OPENCODE_DIR = os.path.join(os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config"),
+ "opencode")
+
+DRY = False
+
+
+def say(msg):
+ print(msg, flush=True)
+
+
+def run(cmd, cwd=None):
+ say(" $ " + " ".join(cmd))
+ if not DRY:
+ subprocess.run(cmd, cwd=cwd, check=True)
+
+
+def find_python(preferred=None):
+ # The default python3 first: a newer interpreter found on PATH may have no
+ # prebuilt wheels for dependencies such as cryptography.
+ for name in ([preferred] if preferred else ["python3", "python3.12", "python3.13", "python"]):
+ exe = shutil.which(name)
+ if not exe:
+ continue
+ out = subprocess.run([exe, "-c", "import sys; print(*sys.version_info[:2])"],
+ capture_output=True, text=True)
+ if out.returncode == 0 and tuple(map(int, out.stdout.split())) >= MIN_PYTHON:
+ return exe
+ return None
+
+
+def fetch(repo, dest):
+ if os.path.isdir(os.path.join(dest, ".git")):
+ # Already cloned: update it. A checkout with local changes or a
+ # diverged branch is kept as it is rather than stopping the run.
+ try:
+ run(["git", "-C", dest, "pull", "--ff-only", "-q"])
+ except subprocess.CalledProcessError:
+ say(f" could not update {dest}; using it as it is")
+ else:
+ run(["git", "clone", "-q", f"{GITHUB}/{repo}.git", dest])
+
+
+def venv_bin(venv, name):
+ if os.name == "nt":
+ return os.path.join(venv, "Scripts", name + ".exe")
+ return os.path.join(venv, "bin", name)
+
+
+def install(root, only, preferred=None):
+ need_py = any(SERVERS[n][1] == "python" for n in only)
+ need_node = any(SERVERS[n][1] == "node" for n in only)
+
+ python = find_python(preferred) if need_py else None
+ if need_py and not python:
+ sys.exit(f"need Python {MIN_PYTHON[0]}.{MIN_PYTHON[1]} or later on PATH")
+ for tool in ["git"] + (["node", "npm"] if need_node else []):
+ if not shutil.which(tool):
+ sys.exit(f"need {tool} on PATH")
+
+ src = os.path.join(root, "src")
+ venv = os.path.join(root, "venv")
+ commands = {}
+
+ if need_py:
+ if not os.path.isdir(venv):
+ say(f"creating virtual environment {venv}")
+ run([python, "-m", "venv", venv])
+ pip = [venv_bin(venv, "python"), "-m", "pip", "install", "-q", "--upgrade"]
+ run(pip + ["pip"])
+
+ for name in only:
+ repo, kind, entry = SERVERS[name]
+ dest = os.path.join(src, repo)
+ say(f"\n{name} ({GITHUB}/{repo})")
+ fetch(repo, dest)
+ if kind == "python":
+ run(pip + [dest])
+ commands[name] = [venv_bin(venv, entry)]
+ else:
+ run(["npm", "install", "--omit=dev", "--silent"], cwd=dest)
+ commands[name] = [shutil.which("node"), os.path.join(dest, entry)]
+ return commands
+
+
+def backup(path, stamp):
+ if not os.path.isfile(path):
+ return
+ copy = f"{path}.{stamp}.bak"
+ say(f" backup {path} -> {copy}")
+ if not DRY:
+ shutil.copy2(path, copy)
+
+
+def read(path):
+ try:
+ with open(path, encoding="utf-8") as fh:
+ return fh.read()
+ except FileNotFoundError:
+ return None
+
+
+def write(path, text):
+ if DRY:
+ return
+ tmp = path + ".tmp"
+ with open(tmp, "w", encoding="utf-8") as fh:
+ fh.write(text)
+ os.replace(tmp, path)
+
+
+class Target:
+ """One client's config. names() returns the servers already registered,
+ or None when the file can't be read safely, in which case it is left
+ alone. add() re-reads the file immediately before writing it, so nothing
+ changed since the plan was made is lost."""
+
+ label = path = None
+ hint = ""
+
+ def names(self):
+ raise NotImplementedError
+
+ def add(self, new):
+ raise NotImplementedError
+
+
+class ClaudeCode(Target):
+ label, path = "Claude Code", CLAUDE_CODE_CONFIG
+
+ def __init__(self, claude):
+ self.claude = claude
+
+ def names(self):
+ text = read(self.path)
+ try:
+ return set(json.loads(text).get("mcpServers", {})) if text else set()
+ except ValueError:
+ return None
+
+ def add(self, new):
+ for name, cmd in new.items():
+ run([self.claude, "mcp", "add", "-s", "user", name, "--"] + cmd)
+
+
+class JsonTarget(Target):
+ key = None
+
+ def names(self):
+ text = read(self.path)
+ try:
+ return set(json.loads(text).get(self.key, {})) if text else set()
+ except ValueError:
+ return None
+
+ def entry(self, cmd):
+ raise NotImplementedError
+
+ def add(self, new):
+ text = read(self.path)
+ config = json.loads(text) if text else self.empty()
+ servers = config.setdefault(self.key, {})
+ for name, cmd in new.items():
+ servers.setdefault(name, self.entry(cmd))
+ write(self.path, json.dumps(config, indent=2) + "\n")
+
+ def empty(self):
+ return {}
+
+
+class ClaudeDesktop(JsonTarget):
+ label, path, key = "Claude Desktop", DESKTOP_CONFIG, "mcpServers"
+ hint = "restart Claude Desktop to pick them up"
+
+ def entry(self, cmd):
+ return {"command": cmd[0], "args": cmd[1:]}
+
+
+class OpenCode(JsonTarget):
+ label, key = "OpenCode", "mcp"
+
+ def __init__(self):
+ # opencode.jsonc may hold comments, which the json module can't read;
+ # names() then returns None and the block is printed to paste instead.
+ for name in ("opencode.jsonc", "opencode.json"):
+ self.path = os.path.join(OPENCODE_DIR, name)
+ if os.path.isfile(self.path):
+ break
+ else:
+ self.path = os.path.join(OPENCODE_DIR, "opencode.json")
+
+ def empty(self):
+ return {"$schema": "https://opencode.ai/config.json"}
+
+ def entry(self, cmd):
+ return {"type": "local", "command": cmd, "enabled": True}
+
+ def snippet(self, commands):
+ body = {n: self.entry(c) for n, c in commands.items()}
+ return '"mcp": ' + json.dumps(body, indent=2)
+
+
+class Codex(Target):
+ label, path = "Codex", CODEX_CONFIG
+
+ def names(self):
+ text = read(self.path)
+ if not text:
+ return set()
+ try:
+ import tomllib
+ except ImportError:
+ return None
+ try:
+ return set(tomllib.loads(text).get("mcp_servers", {}))
+ except tomllib.TOMLDecodeError:
+ return None
+
+ def add(self, new):
+ # The standard library reads TOML but can't write it, so new tables
+ # are appended as text and everything already there is untouched.
+ text = read(self.path) or ""
+ have = self.names() or set()
+ blocks = [self.block(n, c) for n, c in new.items() if n not in have]
+ if text and not text.endswith("\n"):
+ text += "\n"
+ write(self.path, text + "".join(blocks))
+
+ @staticmethod
+ def block(name, cmd):
+ # JSON string escapes are valid TOML basic strings.
+ args = ", ".join(json.dumps(a) for a in cmd[1:])
+ return f"\n[mcp_servers.{name}]\ncommand = {json.dumps(cmd[0])}\nargs = [{args}]\n"
+
+ def snippet(self, commands):
+ return "".join(self.block(n, c) for n, c in commands.items())
+
+
+def targets(args):
+ found = []
+ claude = shutil.which("claude")
+ if args.no_claude_code:
+ pass
+ elif claude:
+ found.append(ClaudeCode(claude))
+ else:
+ say("\nclaude CLI not found, so Claude Code is skipped")
+ wanted = [(args.desktop, ClaudeDesktop, os.path.dirname(DESKTOP_CONFIG)),
+ (args.codex, Codex, os.path.dirname(CODEX_CONFIG)),
+ (args.opencode, OpenCode, OPENCODE_DIR)]
+ for asked, cls, home in wanted:
+ if not asked:
+ continue
+ if os.path.isdir(home):
+ found.append(cls())
+ else:
+ say(f"\n{cls.label} does not look installed ({home} missing), so it is skipped")
+ return found
+
+
+def plan(commands, found):
+ """Work out what would be added where, without changing anything."""
+ steps = []
+ for target in found:
+ have = target.names()
+ if have is None:
+ say(f"\n{target.label}: could not read {target.path}, so it is left alone")
+ if hasattr(target, "snippet"):
+ say(" add this by hand if you want these servers there:\n")
+ say(target.snippet(commands))
+ continue
+ new = {n: c for n, c in commands.items() if n not in have}
+ steps.append((target, new, sorted(set(commands) & have)))
+ return steps
+
+
+def confirm(steps, assume_yes):
+ say("\nThis will change your configuration:")
+ for target, new, kept in steps:
+ say(f"\n {target.label}: {target.path}")
+ for name in new:
+ say(f" add {name}")
+ for name in kept:
+ say(f" keep {name} (already registered, not changed)")
+ say("\n Each file is backed up first, next to the original, as <file>.<timestamp>.bak")
+ if assume_yes:
+ return True
+ if not sys.stdin.isatty():
+ say("\nno terminal to confirm on (pass --yes to allow it)")
+ return False
+ try:
+ return input("\nGo ahead? [y/N] ").strip().lower() in ("y", "yes")
+ except EOFError:
+ return False
+
+
+def main():
+ global DRY
+ ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+ ap.add_argument("--dir", default=os.path.expanduser("~/.asf-mcp"),
+ help="where servers are cloned and installed (default ~/.asf-mcp)")
+ ap.add_argument("--only", nargs="+", choices=sorted(SERVERS), metavar="NAME",
+ help="install only these servers: " + ", ".join(SERVERS))
+ ap.add_argument("--python", help="interpreter for the virtual environment (default: first 3.12+ found)")
+ ap.add_argument("--desktop", action="store_true", help="also register with Claude Desktop")
+ ap.add_argument("--codex", action="store_true", help="also register with Codex (~/.codex/config.toml)")
+ ap.add_argument("--opencode", action="store_true", help="also register with OpenCode (~/.config/opencode)")
+ ap.add_argument("--no-claude-code", action="store_true",
+ help="leave Claude Code alone, for setting up only the other clients")
+ ap.add_argument("--yes", action="store_true", help="register without asking first")
+ ap.add_argument("--no-register", action="store_true", help="install without touching any config")
+ ap.add_argument("--dry-run", action="store_true", help="print the steps without running them")
+ args = ap.parse_args()
+ DRY = args.dry_run
+
+ root = os.path.abspath(os.path.expanduser(args.dir))
+ only = args.only or list(SERVERS)
+ try:
+ commands = install(root, only, args.python)
+ except subprocess.CalledProcessError as exc:
+ sys.exit(f"\nfailed: {' '.join(exc.cmd)}\nnothing was registered; fix the error above and run again")
+
+ if not args.no_register:
+ steps = plan(commands, targets(args))
+ if not any(new for _, new, _ in steps):
+ say("\nevery server is already registered; config not touched")
+ elif DRY or confirm(steps, args.yes):
+ stamp = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+ say("\nbacking up")
+ for target, new, _ in steps:
+ if new:
+ backup(target.path, stamp)
+ for target, new, _ in steps:
+ if not new:
+ continue
+ say(f"\n{target.label}")
+ target.add(new)
+ for name in new:
+ say(f" added {name}")
+ if target.hint:
+ say(f" {target.hint}")
+ else:
+ say("\nnothing registered")
+
+ say("\ndone" + (" (dry run, nothing changed)" if DRY else ""))
+
+
+if __name__ == "__main__":
+ main()
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org