This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 3492257 docs(ponymail): point install docs at apache/comdev's
official MCP (#279)
3492257 is described below
commit 34922571cb08b45975d1d35e7af726918f083642
Author: Jarek Potiuk <[email protected]>
AuthorDate: Mon May 25 17:08:05 2026 +0200
docs(ponymail): point install docs at apache/comdev's official MCP (#279)
The PonyMail MCP setup was previously documented around the
rbowen/ponymail-mcp fork, which has now been promoted into the
ASF's official ComDev MCP repository at apache/comdev under
mcp/ponymail-mcp/. Re-point the framework docs at the official
location and update the install + registration recipe accordingly:
- tools/ponymail/tool.md: backend pointer (rbowen -> apache/comdev),
prereq (Python 3.11+ -> Node.js 20+), install (uv tool install
-> git clone + npm install), MCP entry JSON (`"command":
"ponymail-mcp"` -> `"command": "node"` + absolute path to
index.js), `claude mcp add` shortcut, and a callout for the new
PONYMAIL_ALLOWED_LISTS opt-in -- the comdev server default-denies
all private lists, so following the old docs verbatim would
silently get empty results on `security@` until the project's
list is opted in.
- tools/ponymail/operations.md: header pointer swapped.
- docs/prerequisites.md: "on the horizon" paragraph rewritten as
"now an official ASF alternative for the read side"; the read-
only / drafts-still-Gmail caveat made explicit. Second paragraph
("until ponymail-mcp is wired in with ASF OAuth") softened -- it
IS wired in now; the PMC LDAP gate still applies regardless of
read path.
- .claude/skills/security-cve-allocate/SKILL.md: drop "on the
horizon" phrase from the prerequisites cross-reference.
Session cookie path (~/.ponymail-mcp/session.json) is unchanged --
the comdev implementation uses the same path as the fork.
Generated-by: Claude Code (Opus 4.7)
---
.claude/skills/security-cve-allocate/SKILL.md | 2 +-
docs/prerequisites.md | 25 +++++++++------
tools/ponymail/operations.md | 5 +--
tools/ponymail/tool.md | 45 ++++++++++++++++++++-------
4 files changed, 52 insertions(+), 25 deletions(-)
diff --git a/.claude/skills/security-cve-allocate/SKILL.md
b/.claude/skills/security-cve-allocate/SKILL.md
index f68e661..91085ad 100644
--- a/.claude/skills/security-cve-allocate/SKILL.md
+++ b/.claude/skills/security-cve-allocate/SKILL.md
@@ -170,7 +170,7 @@ anything else.
See
[Prerequisites for running the agent
skills](../../../docs/prerequisites.md#prerequisites-for-running-the-agent-skills)
in `docs/prerequisites.md` for the overall setup (including the
-ponymail-mcp option on the horizon for non-personal-Gmail access).
+ponymail-mcp option for non-personal-Gmail read access).
---
diff --git a/docs/prerequisites.md b/docs/prerequisites.md
index c272bcd..bd4feb8 100644
--- a/docs/prerequisites.md
+++ b/docs/prerequisites.md
@@ -72,14 +72,18 @@ who is subscribed to the adopting project's security list
(see
access for the skills to see inbound reports and create drafts on
the right threads.
-There is an ASF-wide alternative on the horizon:
-[`rbowen/ponymail-mcp`](https://github.com/rbowen/ponymail-mcp) (by
-Rich Bowen, former ASF board director and ComDev lead) now supports
-OAuth authentication and can read private ASF lists. Once ASF OAuth
-is wired in, individual triagers should be able to run the skills
-without connecting their personal Gmail — authenticating directly
-against ASF credentials (and, eventually, the ASF's new MFA) will be
-sufficient. Until then, Gmail MCP is the way.
+There is now an official ASF alternative for the **read** side:
+[`apache/comdev`'s
`mcp/ponymail-mcp/`](https://github.com/apache/comdev/tree/main/mcp/ponymail-mcp)
+(under the ComDev PMC; originally authored by Rich Bowen, former ASF
+board director and ComDev lead, with supply-chain hardening and
+private-list restrictions layered in upstream) supports ASF LDAP
+OAuth and can read private ASF lists. Individual triagers can wire
+it up to read inbound `security@<project>.apache.org` threads
+without subscribing a personal Gmail account — see
+[`tools/ponymail/tool.md`](../tools/ponymail/tool.md) for the
+setup. **Drafts remain Gmail-only** today (PonyMail MCP is
+read-only and has no `create_draft` equivalent), so Gmail MCP is
+still required for the reply path.
**Without this connection:** `security-issue-import` cannot find new
reports, `security-issue-sync` cannot reconcile status with the mail
@@ -112,8 +116,9 @@ click through instead. The concrete tool + URL is declared
in
[`<project-config>/project.md → CVE
tooling`](<project-config>/project.md#cve-tooling).
The same PMC gate applies to ponymail URL lookups on private ASF
-lists; until `ponymail-mcp` is wired in with ASF OAuth, only PMC
-members can see private-list archives directly.
+lists — only PMC members (via ASF LDAP) can see private-list
+archives directly, whether through `ponymail-mcp`'s OAuth flow or
+the `lists.apache.org` web UI.
### 5. Browser (for the human-click steps)
diff --git a/tools/ponymail/operations.md b/tools/ponymail/operations.md
index 6335b4d..1a6589f 100644
--- a/tools/ponymail/operations.md
+++ b/tools/ponymail/operations.md
@@ -30,8 +30,9 @@
# PonyMail — MCP operation catalogue
Shared reference for the `mcp__ponymail__*` tool calls against the
-[`rbowen/ponymail-mcp`](https://github.com/rbowen/ponymail-mcp) MCP
-server. Skills reference this file for call shape, parameter
+official ASF
+[`apache/comdev`
`mcp/ponymail-mcp/`](https://github.com/apache/comdev/tree/main/mcp/ponymail-mcp)
+MCP server. Skills reference this file for call shape, parameter
semantics, and the split between list-prefix and domain in every
query.
diff --git a/tools/ponymail/tool.md b/tools/ponymail/tool.md
index 2ea0f41..9f3ca71 100644
--- a/tools/ponymail/tool.md
+++ b/tools/ponymail/tool.md
@@ -40,8 +40,9 @@ adapter with a writable Drafts mailbox) as
`preferred for create_draft, list_drafts` so the skills' reply-draft
operations have a place to land.
-The backing MCP server is
[`rbowen/ponymail-mcp`](https://github.com/rbowen/ponymail-mcp)
-(Python) which wraps the public PonyMail HTTP API at
+The backing MCP server is the official ASF
+[`apache/comdev`
`mcp/ponymail-mcp/`](https://github.com/apache/comdev/tree/main/mcp/ponymail-mcp)
+(Node.js) which wraps the public PonyMail HTTP API at
[`lists.apache.org`](https://lists.apache.org/) and layers ASF LDAP
OAuth on top so private-list archives (e.g. `security@<project>.apache.org`,
`private@<project>.apache.org`) are reachable from the MCP client.
@@ -103,7 +104,8 @@ draft composition regardless of which read backend is
active.
Prerequisites:
-- Python 3.11+ (the MCP server is a Python package).
+- Node.js 20+ (the MCP server is a Node.js package; see the `engines`
+ field of its
[`package.json`](https://github.com/apache/comdev/blob/main/mcp/ponymail-mcp/package.json)).
- An ASF LDAP account with access to the lists the project needs.
Typically that is the project's PMC LDAP group (e.g.
`pmc-<project>`), which gates the `<security-list>` and
@@ -113,17 +115,19 @@ Prerequisites:
### 1. Install the MCP server
-The server is published as
[`rbowen/ponymail-mcp`](https://github.com/rbowen/ponymail-mcp).
-Install it with `uv tool install`, `pipx install`, or via the
-package-manager of your choice. Confirm the binary resolves on
-`PATH`:
+The server lives in the [`apache/comdev`](https://github.com/apache/comdev)
+repository under `mcp/ponymail-mcp/`. There is no published binary —
+clone the repo and install dependencies from the subdirectory:
```bash
-uv tool install git+https://github.com/rbowen/ponymail-mcp
-which ponymail-mcp
-# /home/<user>/.local/bin/ponymail-mcp
+git clone https://github.com/apache/comdev.git
+cd comdev/mcp/ponymail-mcp
+npm install
```
+The MCP server is invoked as `node <abs-path>/index.js`. Note the
+absolute path to `index.js` — the next step needs it.
+
### 2. Register the MCP with Claude Code
Add the server to Claude Code's MCP configuration. Two common
@@ -142,19 +146,36 @@ The `mcpServers` entry looks like:
{
"mcpServers": {
"ponymail": {
- "command": "ponymail-mcp",
- "args": [],
+ "command": "node",
+ "args": ["/absolute/path/to/comdev/mcp/ponymail-mcp/index.js"],
"env": {}
}
}
}
```
+Or, equivalently, register from the command line (user scope shown):
+
+```bash
+claude mcp add ponymail node \
+ /absolute/path/to/comdev/mcp/ponymail-mcp/index.js -s user
+```
+
The tool names that Claude Code surfaces after registration are
prefixed with `mcp__ponymail__` (derived from the key under
`mcpServers`). If you name the server differently, the prefix
changes and this directory's docs need to be re-pointed.
+The comdev server also honours a small set of environment variables
+(see its
[`README.md`](https://github.com/apache/comdev/blob/main/mcp/ponymail-mcp/README.md)):
+`PONYMAIL_BASE_URL` (defaults to `https://lists.apache.org`),
+`PONYMAIL_SESSION_COOKIE` (manual cookie override that skips OAuth),
+`PONYMAIL_RESTRICTED_LISTS` and `PONYMAIL_ALLOWED_LISTS` (deny / opt-in
+patterns). By default the server **blocks all private lists** and
+expects the operator to opt the relevant ones in via
+`PONYMAIL_ALLOWED_LISTS` — list those that match the project's
+`<security-list>` / `<private-list>` if the skills need to read them.
+
Restart Claude Code (or run `/mcp` → `reconnect`) so the new server
is picked up and its tools appear in the deferred-tool list.
