You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/07/10 13:16:23 UTC

(magpie) branch main updated: docs(tools): add **MCP:** marker to MCP-wrapper tools (#802)

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/magpie.git


The following commit(s) were added to refs/heads/main by this push:
     new f17cff7a docs(tools): add **MCP:** marker to MCP-wrapper tools (#802)
f17cff7a is described below

commit f17cff7a8a1aa37674c10a4831f173b36a3feb60
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Fri Jul 10 15:16:18 2026 +0200

    docs(tools): add **MCP:** marker to MCP-wrapper tools (#802)
    
    Introduce a per-tool README marker — **MCP:** <server> (mcp__prefix__*) —
    as the source of truth for the "wraps an MCP" classification, and apply it
    to the four MCP-wrapper tools: github, gmail, ponymail, apache-projects.
    
    - Document the field in tools/AGENTS.md alongside Capability/Organization
    - Note in docs/labels-and-capabilities.md that the per-tool marker is the
      source of truth (the MCP table now mirrors it), and explain that MCP
      servers install at user scope and are usable by any agent session, not
      only Magpie-adopting projects
    
    Co-authored-by: Tester <t...@example.com>
---
 docs/labels-and-capabilities.md | 15 +++++++++++++++
 tools/AGENTS.md                 | 19 +++++++++++++++++++
 tools/apache-projects/README.md |  2 ++
 tools/github/README.md          |  2 ++
 tools/gmail/README.md           |  2 ++
 tools/ponymail/README.md        |  2 ++
 6 files changed, 42 insertions(+)

diff --git a/docs/labels-and-capabilities.md b/docs/labels-and-capabilities.md
index 76b57fd1..471d0c13 100644
--- a/docs/labels-and-capabilities.md
+++ b/docs/labels-and-capabilities.md
@@ -332,10 +332,25 @@ backend the adopter wired in. The framework consumes four:
 | PonyMail MCP (`apache/comdev`) | `mcp__ponymail__*` | [`tools/ponymail`](../tools/ponymail/) | `contract:mail-archive` + `contract:mail-source` | ASF |
 | apache-projects MCP (`apache/comdev`) | `mcp__apache-projects__*` | [`tools/apache-projects`](../tools/apache-projects/) | `contract:project-metadata` | ASF |
 
+Each wrapping tool declares this relationship in its own README with an
+`**MCP:** <server> (mcp__<prefix>__*)` marker (see
+[`tools/AGENTS.md`](../tools/AGENTS.md)) — that per-tool marker is the
+source of truth; this table mirrors it for a one-glance overview.
+
 Non-MCP backends fulfil the same contracts: JIRA is reached over REST
 and `gh` is the CLI fallback, both `contract:tracker`. See
 [`docs/prerequisites.md`](prerequisites.md) for connection setup.
 
+**MCP servers are installed for the user, not the project.** They are
+registered at **user scope** (`claude mcp add … -s user`), so a single
+registration serves every repository on the machine. Consequently they
+are usable by **any** agent session — not only Magpie-adopting projects
+or Magpie-related work. Magpie surfaces the registration command and
+verifies it during setup, but the server itself is a plain,
+project-agnostic MCP: once registered it is available to any agentic
+session the same way a globally-installed CLI would be. Nothing about
+using one ties a session to Magpie.
+
 ---
 
 ## The rule
diff --git a/tools/AGENTS.md b/tools/AGENTS.md
index fd9b9c6d..853d0dea 100644
--- a/tools/AGENTS.md
+++ b/tools/AGENTS.md
@@ -81,6 +81,25 @@ declares, up front:
    `organization:` frontmatter key; skill families with an
    `organization:` scope banner in `docs/<family>/README.md`.
 
+4. **(Optional) its MCP backing** — when a tool wraps a
+   [Model Context Protocol](https://modelcontextprotocol.io) server as a
+   concrete backend, declare it with a line of the exact form
+
+   ```markdown
+   **MCP:** <server> (mcp__<prefix>__*)
+   ```
+
+   e.g. `**MCP:** PonyMail — apache/comdev (mcp__ponymail__*)`. The value
+   names the human-readable server (optionally with `— <org>`) and, in
+   parentheses, the `mcp__<prefix>__*` tool namespace it exposes. Omit the
+   line for tools with no MCP backend — absence means "wraps no MCP". This
+   marker is the per-tool source of truth for the "wraps an MCP"
+   classification: it is mirrored in the
+   [`docs/labels-and-capabilities.md`](../docs/labels-and-capabilities.md#mcp-servers-classified-by-capability)
+   MCP table and read by the project website's tool index to drive its
+   "Wraps an MCP" filter. An MCP is transport, not a capability axis — the
+   `**Capability:**` line still states the contract the tool provides.
+
 The capability and prerequisites are **HARD** checks in
 [`tools/skill-and-tool-validator`](skill-and-tool-validator/) — a tool
 README missing either the `**Capability:**` line or the
diff --git a/tools/apache-projects/README.md b/tools/apache-projects/README.md
index 7b2a1fe0..437b6692 100644
--- a/tools/apache-projects/README.md
+++ b/tools/apache-projects/README.md
@@ -17,6 +17,8 @@
 
 **Kind:** implementation
 
+**MCP:** apache-projects — apache/comdev (mcp__apache-projects__*)
+
 **Vendor:** ASF
 
 **Organization:** ASF
diff --git a/tools/github/README.md b/tools/github/README.md
index f6b9ce32..f4be3354 100644
--- a/tools/github/README.md
+++ b/tools/github/README.md
@@ -17,6 +17,8 @@
 
 **Kind:** implementation
 
+**MCP:** GitHub MCP (mcp__github__*)
+
 **Vendor:** GitHub
 
 GitHub REST + GraphQL substrate. Pure read/write wrapper used by every lifecycle phase (triage / intake / fix / resolve / stats). See [`tool.md`](tool.md) for the operation catalogue and the per-area files ([`issue-template.md`](issue-template.md), [`labels.md`](labels.md), [`operations.md`](operations.md), [`project-board.md`](project-board.md), [`status-rollup.md`](status-rollup.md)) for specifics.
diff --git a/tools/gmail/README.md b/tools/gmail/README.md
index d8e7214f..77f2b383 100644
--- a/tools/gmail/README.md
+++ b/tools/gmail/README.md
@@ -17,6 +17,8 @@
 
 **Kind:** implementation
 
+**MCP:** Gmail — claude.ai (mcp__claude_ai_Gmail__*)
+
 **Vendor:** Google
 
 Gmail API substrate. Read + draft-only — never sends. Provides two
diff --git a/tools/ponymail/README.md b/tools/ponymail/README.md
index a1262df5..cf9f391f 100644
--- a/tools/ponymail/README.md
+++ b/tools/ponymail/README.md
@@ -18,6 +18,8 @@
 
 **Kind:** implementation
 
+**MCP:** PonyMail — apache/comdev (mcp__ponymail__*)
+
 **Vendor:** ASF
 
 **Organization:** ASF