@pipeworx/mcp-merriam-webster 0.1.0 → 0.1.1

package/.github/workflows/publish.yml

@@ -0,0 +1,152 @@
+name: Publish to npm
+
+# Trusted publishing (OIDC) — NO npm token anywhere in this repo.
+#
+# Why this file exists: npm is withdrawing the ability for access tokens to
+# bypass 2FA when publishing. Phase 1 (2026-07-31) already blocked token-driven
+# MANAGEMENT operations; Phase 2 (~January 2027) removes DIRECT PUBLISHING, and
+# when it lands no token you can create will publish this package. The
+# replacement is trusted publishing: GitHub Actions proves this repo's identity
+# to npm over OIDC, with no long-lived credential to leak or rotate.
+#
+# Provenance comes free and is why this workflow lives HERE rather than in the
+# pipeworx-core monorepo: npm will only attach a provenance attestation when the
+# source repo is PUBLIC, and pipeworx-core is private. This repo is public, and
+# package.json's `repository.url` already points at it, which is the match npm
+# checks (case-sensitive).
+#
+# Do NOT add `--provenance`: with trusted publishing npm generates the
+# attestation automatically, and passing the flag is redundant.
+#
+# The FILENAME matters. npm's trusted-publisher config names the org, the repo
+# and this file's name — `publish.yml`. Renaming this file silently breaks
+# publishing for this package until someone re-runs `npm trust` against the new
+# name. Keep it `publish.yml` across every pack repo so the bulk config loop in
+# pipeworx-core's scripts/npm-trust-bulk.sh stays a one-liner.
+#
+# This file is GENERATED by pipeworx-core's scripts/publish-pack.sh from
+# scripts/templates/publish-npm.yml. Edit it there — publish-pack.sh rebuilds
+# this repo from scratch and force-pushes, so local edits are erased on the next
+# publish.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'src/**'
+  workflow_dispatch:
+
+permissions:
+  id-token: write   # REQUIRED: lets Actions mint the OIDC token npm authenticates
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest   # must be GitHub-HOSTED; self-hosted runners are unsupported
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22   # trusted publishing needs Node >= 22.14.0
+        # Deliberately NO `registry-url:` — that option exists to inject a token
+        # into an .npmrc, writes a literal `_authToken=${NODE_AUTH_TOKEN}` line,
+        # and would trip the credential assertion below. npm publish already
+        # defaults to registry.npmjs.org.
+
+      - name: Upgrade npm to a trusted-publishing-capable version
+        # The runner image's bundled npm lags. Trusted publishing needs npm
+        # >= 11.5.1; installing `latest` rather than a pinned version keeps this
+        # from silently rotting, and the assertion below fails loudly rather
+        # than falling through to a publish that cannot authenticate.
+        run: |
+          set -euo pipefail
+          npm install -g npm@latest
+          v=$(npm --version)
+          echo "npm $v"
+          node -e 'const v=process.argv[1].split("-")[0].split(".").map(Number);
+            const min=[11,5,1];
+            for (let i=0;i<3;i++){ if(v[i]>min[i]) break; if(v[i]<min[i]){
+              console.error(`npm ${process.argv[1]} is below the 11.5.1 trusted-publishing floor`);
+              process.exit(1); } }' "$v"
+
+      - name: Assert no npm token is present
+        # The whole point of this workflow is that it publishes with NO
+        # credential. If a token ever appears, a publish could succeed for the
+        # wrong reason and hide a broken OIDC config until Phase 2 removes the
+        # token fallback and every pack breaks at once. Fail loudly instead.
+        run: |
+          set -euo pipefail
+          if [ -n "${NODE_AUTH_TOKEN:-}" ] || [ -n "${NPM_TOKEN:-}" ]; then
+            echo "::error::an npm token is in the environment; this workflow must publish over OIDC only"
+            exit 1
+          fi
+          tok=$(npm config get //registry.npmjs.org/:_authToken 2>/dev/null || echo "undefined")
+          if [ "$tok" != "undefined" ] && [ -n "$tok" ]; then
+            echo "::error::npm config carries an _authToken; refusing to publish"
+            exit 1
+          fi
+          echo "no npm credential present — publishing over OIDC"
+
+      - name: Skip if this version is already published
+        id: check
+        run: |
+          set -euo pipefail
+          name=$(node -p "require('./package.json').name")
+          version=$(node -p "require('./package.json').version")
+          published=$(npm view "$name" version 2>/dev/null || echo "")
+          echo "name=$name"       >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          if [ "$published" = "$version" ]; then
+            # Not an error: most pushes here are README/metadata refreshes from
+            # publish-pack.sh, which force-pushes the whole repo. Publishing is
+            # the exception, so a same-version push is the normal case.
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::$name@$version already published — nothing to do"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::publishing $name@$version (registry has ${published:-none})"
+          fi
+
+      - name: Publish
+        if: steps.check.outputs.skip == 'false'
+        # Do NOT add --provenance: with trusted publishing npm generates the
+        # attestation automatically.
+        #
+        # The error translation below is not decoration. When no trusted
+        # publisher is configured for this package, npm does not say so — it
+        # returns a generic `ENEEDAUTH / You need to authorize this machine
+        # using npm login`, which reads exactly like a forgotten credential and
+        # sends you looking for a token. There is no token to find; that is the
+        # point. The ENEEDAUTH text itself was seen live in mcp-opentargets run
+        # 33261239541 — but note that run executed a plain `npm publish`, so the
+        # capture-and-translate below was NOT what produced it.
+        #
+        # `set -e` IS ON here: GitHub's default `run:` shell is `bash -e {0}` —
+        # visible in that run's own step header — and `set -uo pipefail` does not
+        # clear it. A bare `out=$(npm publish ...)` therefore aborts the step AT
+        # THE ASSIGNMENT the instant publish fails, swallowing npm's output AND
+        # skipping the translation, leaving a red step with an EMPTY log. Since
+        # every pack fails this way until its trusted publisher exists, that is
+        # the common path, not the edge case. `|| rc=$?` keeps the failure
+        # in-band. Do not "simplify" it back to a bare assignment.
+        run: |
+          set -uo pipefail
+          out=$(npm publish --access public 2>&1) && rc=0 || rc=$?
+          echo "$out"
+          if [ $rc -ne 0 ] && echo "$out" | grep -q 'ENEEDAUTH'; then
+            # npm-trust-bulk.sh --only matches pack SLUGS, and the repo name is
+            # mcp-<slug> — strip the prefix or the suggested command matches
+            # nothing (seen live: "--only mcp-csv" → "matched no outstanding
+            # published pack").
+            repo='${{ github.event.repository.name }}'
+            echo "::error::npm returned ENEEDAUTH. This almost certainly means no trusted publisher is configured for this package yet, NOT that a token is missing — this workflow publishes over OIDC and deliberately has no credential. Fix: from pipeworx-core, npm login (interactive, 2FA) then ./scripts/npm-trust-bulk.sh --only ${repo#mcp-}. See docs/npm-trusted-publishing.md."
+          fi
+          exit $rc
+
+      - name: Report
+        if: steps.check.outputs.skip == 'false'
+        run: |
+          echo "published ${{ steps.check.outputs.name }}@${{ steps.check.outputs.version }}"
+          echo "verify: npm view ${{ steps.check.outputs.name }} dist.attestations"

package/README.md

@@ -2,12 +2,14 @@
 
 Merriam-Webster MCP — wraps the Merriam-Webster Collegiate Dictionary and
 
-Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 764+ live data sources.
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1481+ live data sources.
 
 ## Tools
 
 | Tool | Description |
 |------|-------------|
+| `define` | Look up a word in the Merriam-Webster dictionary — the authoritative American English dictionary. Returns word definitions (short definitions), part of speech (noun, verb, adjective, etc.), pronunciation, and etymology (word origin). When the word is not found, returns close spelling suggestions instead. Example: define({ word: "ephemeral" }) |
+| `thesaurus` | Look up a word in the Merriam-Webster thesaurus — the authoritative American English thesaurus. Returns synonyms and antonyms grouped by sense, along with part of speech (noun, verb, adjective, etc.) and short definitions. When the word is not found, returns close spelling suggestions instead. Example: thesaurus({ word: "happy" }) |
 
 ## Quick Start
 
@@ -16,14 +18,32 @@ Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
 ```json
 {
   "mcpServers": {
-    "merriam-webster": {
-      "url": "https://gateway.pipeworx.io/merriam-webster/mcp"
+    "merriam_webster": {
+      "url": "https://gateway.pipeworx.io/merriam_webster/mcp"
     }
   }
 }
 ```
 
-Or connect to the full Pipeworx gateway for access to all 764+ data sources:
+### What this endpoint actually serves
+
+`tools/list` at `https://gateway.pipeworx.io/merriam_webster/mcp` returns the tools in the table
+above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
+`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
+gateway-wide set. So the tool count you see is larger than this table: a
+single-pack endpoint currently lists roughly 30 shared tools alongside the
+pack's own. The connection's `initialize` response states its exact scope, and
+is the authoritative answer for a given day.
+
+This is deliberate, not multiplexing by accident. The meta-tools are what let a
+scoped connection answer a question this pack does not cover — via
+`ask_pipeworx`, which routes across the whole catalog — without you adding a
+second MCP server. There is currently no way to mount a pack endpoint without
+them; if the extra schemas cost you more context than the routing is worth,
+connect to the full gateway once rather than to several pack endpoints.
+
+Or connect to the full Pipeworx gateway to get every pack's tools listed
+directly, instead of just this one's:
 
 ```json
 {
@@ -35,9 +55,14 @@ Or connect to the full Pipeworx gateway for access to all 764+ data sources:
 }
 ```
 
+Both URLs reach the same gateway and the same 1481+ data sources. The
+only difference is which pack's tools are listed **directly**; `ask_pipeworx`
+reaches all of them from either one.
+
 ## Using with ask_pipeworx
 
-Instead of calling tools directly, you can ask questions in plain English:
+Instead of calling tools directly, you can ask questions in plain English —
+this works on the pack endpoint above as well as on the full gateway:
 
 ```
 ask_pipeworx({ question: "your question about Merriam Webster data" })
@@ -47,7 +72,7 @@ The gateway picks the right tool and fills the arguments automatically.
 
 ## More
 
-- [All tools and guides](https://github.com/pipeworx-io/examples)
+- [Docs and guides](https://pipeworx.io/docs)
 - [pipeworx.io](https://pipeworx.io)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipeworx/mcp-merriam-webster",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Merriam-Webster MCP — wraps the Merriam-Webster Collegiate Dictionary and",
   "type": "module",
   "main": "src/index.ts",