@pipeworx/mcp-index-constituents 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mojibake Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# @pipeworx/index-constituents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Current constituents, weights and sectors of six major US and developed-markets
+equity indexes, plus a dated history of S&P 500 additions and removals —
+point-in-time index membership built from a live ETF proxy, not a licensed
+index feed.
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1856+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
+
+## Tools
+
+- `index_constituents(index, limit?, offset?, sector?)` — current equity
+  constituents of one index (`sp500`, `sp400`, `sp600`, `russell1000`,
+  `russell2000`, `eafe`): ticker, name, GICS sector, weight, and the fund's
+  "as of" date. Sorted by weight descending. Cash/collateral/futures the
+  tracking ETF also holds are excluded here (see `ishares_etf_holdings`). Default
+  `limit` is 50; pass `limit: 600` (the max) to get the whole index in one
+  call — a ~503-row S&P 500 answer is available on request, not by default.
+- `ishares_etf_holdings(ticker, limit?, offset?, asset_class?)` — every reported
+  position of one of the six tracking ETFs (`IVV`, `IJH`, `IJR`, `IWB`, `IWM`,
+  `EFA`), including cash, collateral and futures, each labeled with its own
+  `asset_class` so they are never silently folded in with equities.
+- `constituent_changes(index, from?, to?, limit?)` — dated S&P 500 adds and
+  removes (`index` must be `sp500`; the other five indexes have no public,
+  dated changes table). `from`/`to` accept a bare year ("2024") or an ISO
+  date.
+
+## Auth
+
+Keyless. Both upstreams are public, unauthenticated pages.
+
+## Data sources
+
+- iShares (BlackRock) — the daily holdings file each fund publishes for its
+  own index-tracking ETF (IVV/S&P 500, IJH/S&P MidCap 400, IJR/S&P SmallCap
+  600, IWB/Russell 1000, IWM/Russell 2000, EFA/MSCI EAFE). This is a PROXY for
+  official index membership, not the index provider's own data: S&P and
+  Russell do not publish their constituent files for free, so the fund's
+  actual reported portfolio — which tracks its index closely — is the
+  nearest public point-in-time stand-in. Weights are the ETF's own portfolio
+  weights, not S&P/Russell's published index weights, and can differ slightly
+  (cash drag, sampling, corporate-action timing).
+- Wikipedia — "List of S&P 500 companies" and "Historical components of the
+  S&P 500" (the latter is this pack's source for `constituent_changes`: a
+  community-maintained, citation-backed table of every S&P-announced S&P 500
+  swap since 1963, with its effective date and stated reason).
+
+**Reuse note (checked 2026-10-12).** BlackRock's site terms
+(blackrock.com/corporate/compliance/terms-and-conditions) say website content
+is "solely for your personal, non-commercial use" and may not be "distribute[d],
+modif[ied], transmit[ted], reuse[d], repost[ed]... for public or commercial
+purposes... without BlackRock's written permission." This pack does not store,
+mirror or redistribute the holdings file: every call fetches the fund's current
+file live (cached at the edge for a day, the same way a normal browser would
+cache it) and returns the parsed rows for that one call. Per the proxy-vs-mirror
+rule (CLAUDE.md, fleet #1389 — "a live upstream call per request needs no
+explicit grant; only bulk-copying/mirroring does"), that is proxying, not
+redistribution; no dataset is baked into this pack or into Pipeworx's own
+storage. Wikipedia's content is CC BY-SA 4.0, which permits reuse including
+attribution-carrying commercial reuse — `source` on every response names
+Wikipedia and the page.
+
+## Notes
+
+- The iShares holdings file's column layout is not identical across funds:
+  IJH and IJR add a "Type" column and call the weight field "Market Weight"
+  instead of "Weight (%)". This pack reads the header by NAME, not by
+  position, so a reordered column does not silently misalign the data.
+- `data_as_of` on every response is the fund's own "Fund Holdings as of" date
+  from the file, not the time Pipeworx fetched it — use it to judge freshness.
+- The S&P 500 holdings file carries a handful of non-equity rows (cash,
+  collateral, a futures contract used to stay fully invested between
+  rebalances) even though the fund is "all-equity" by mandate; these are
+  excluded from `index_constituents` and labeled plainly in `ishares_etf_holdings`.
+- `constituent_changes` only covers `sp500` today. The other five indexes
+  have no equivalent free, dated, citation-backed changes table — adding one
+  would mean a different, likely paid, source.
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "index-constituents": {
+      "url": "https://gateway.pipeworx.io/index-constituents/mcp"
+    }
+  }
+}
+```
+
+### What this endpoint actually serves
+
+`tools/list` at `https://gateway.pipeworx.io/index-constituents/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
+{
+  "mcpServers": {
+    "pipeworx": {
+      "url": "https://gateway.pipeworx.io/mcp"
+    }
+  }
+}
+```
+
+Both URLs reach the same gateway and the same 1856+ data sources. The
+only difference is which pack's tools are listed **directly**; `ask_pipeworx`
+reaches all of them from either one.
+
+## No MCP client? Call it over HTTP
+
+```bash
+curl -X POST https://gateway.pipeworx.io/v1/tools/index_constituents \
+  -H 'Content-Type: application/json' \
+  -d '{"index":"sp500","limit":600}'
+```
+
+No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/index_constituents`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
+
+## Run it from npm
+
+`@pipeworx/mcp-index-constituents` is a local stdio bridge to the Pipeworx gateway: your MCP client
+starts it with `npx`, and it forwards every call to the same
+`https://gateway.pipeworx.io/index-constituents/mcp` endpoint shown above. It needs network access;
+there is no offline mode.
+
+```json
+{
+  "mcpServers": {
+    "index-constituents": {
+      "command": "npx",
+      "args": ["-y", "@pipeworx/mcp-index-constituents"]
+    }
+  }
+}
+```
+
+Without a key it calls anonymously, capped at 50 calls a day. A free account
+raises that to 200 a day: get a key at https://pipeworx.io/signup and add
+`"env": { "PIPEWORX_API_KEY": "<your key>" }` to the server entry.
+The key is sent as a Bearer token, the same way a hosted connection sends it,
+so calls are metered and billed exactly as they are there.
+
+It lists **only** this pack's tools by default. Set `PIPEWORX_META_TOOLS=1` to
+also list `ask_pipeworx` and the other gateway-wide tools.
+
+Behind an HTTPS proxy: Node's built-in `fetch` does not read `HTTPS_PROXY` by
+default. Newer Node releases honour it when `NODE_USE_ENV_PROXY=1` is set; check
+your Node version's documentation.
+
+## Using with ask_pipeworx
+
+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 Index Constituents data" })
+```
+
+The gateway picks the right tool and fills the arguments automatically.
+
+## More
+
+- [Docs and guides](https://pipeworx.io/docs)
+- [pipeworx.io](https://pipeworx.io)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Entry point for `npx @pipeworx/mcp-<slug>` in gateway mode (bin/cli.js).
+//
+// A stdio MCP server that relays every message to the Pipeworx gateway's
+// /<slug>/mcp endpoint -- fleet #3759, docs/standalone-via-gateway-plan.md.
+// It carries no pack code and has no local mode. The relay itself lives in
+// ../lib/index.js (copied from scripts/templates/standalone-gateway-lib.js);
+// this file only owns stdin/stdout.
+//
+// Copied VERBATIM into every gateway-mode package by scripts/publish-pack.sh.
+// Edit scripts/templates/standalone-gateway-cli.js in the monorepo, never a
+// per-pack copy. Zero dependencies, Node 18+.
+//
+// stdout carries newline-delimited JSON-RPC and nothing else; every diagnostic
+// goes to stderr, because a single stray line on stdout breaks the host's
+// parser.
+import { createInterface } from 'node:readline';
+import { relay, bridgeConfig } from '../lib/index.js';
+
+const cfg = bridgeConfig();
+const warn = (line) => process.stderr.write(`${line}\n`);
+const write = (msg) => { if (msg) process.stdout.write(`${JSON.stringify(msg)}\n`); };
+
+const pending = new Set();
+function track(p) {
+  pending.add(p);
+  p.finally(() => pending.delete(p));
+}
+
+async function handleLine(line) {
+  const text = line.trim();
+  if (!text) return;
+  let message;
+  try {
+    message = JSON.parse(text);
+  } catch {
+    write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    return;
+  }
+  // A JSON-RPC batch: relay each member, answer with the non-notification replies.
+  if (Array.isArray(message)) {
+    const replies = (await Promise.all(message.map((m) => relay(m, { cfg, warn })))).filter(Boolean);
+    if (replies.length) write(replies);
+    return;
+  }
+  write(await relay(message, { cfg, warn }));
+}
+
+// Requests are handled concurrently and answered as they finish: JSON-RPC ids
+// let the host match them, and a slow tool call must not hold up a ping.
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', (line) => {
+  track(handleLine(line).catch((err) => warn(`pipeworx-standalone: ${err && err.stack ? err.stack : err}`)));
+});
+rl.on('close', async () => {
+  // stdin closed: finish what is in flight, then exit.
+  while (pending.size) await Promise.allSettled([...pending]);
+  // Exit only once stdout has flushed: on a pipe that is not synchronous
+  // everywhere, and a bare exit can drop the last reply.
+  process.stdout.write('', () => process.exit(0));
+});

package/lib/index.js

@@ -0,0 +1,333 @@
+// @pipeworx/mcp-<slug> -- library half of the gateway bridge (lib/index.js).
+//
+// Copied VERBATIM into every gateway-mode pack package by scripts/publish-pack.sh
+// (fleet #3759, docs/standalone-via-gateway-plan.md section 1). There is no
+// per-pack templating: the slug and version are read from this package's own
+// package.json (`pipeworx.slug`, `version`) at load time, so the same bytes
+// ship in every package and the source hash can cover them once. Edit this
+// file in the monorepo (scripts/templates/standalone-gateway-lib.js), never a
+// per-pack copy.
+//
+// What it is: a relay. Every JSON-RPC message goes to
+// ${PIPEWORX_GATEWAY_URL:-https://gateway.pipeworx.io}/<slug>/mcp, the same
+// endpoint a hosted MCP client uses, so tiers, rate limits and credits apply
+// exactly as they do there. There is no local mode: the pack's code is not in
+// this package.
+//
+// Zero dependencies, plain ESM, Node 18+ (global fetch). Nothing here writes
+// to stdout -- bin/cli.js owns stdout and it carries JSON-RPC only.
+//
+// Environment:
+//   PIPEWORX_API_KEY      sent as `Authorization: Bearer <key>`. Never as
+//                         X-API-Key: the gateway reads a pwx_ key sent that way
+//                         as an unvalidated BYO string with no account.
+//   PIPEWORX_GATEWAY_URL  gateway base URL (no path), default the public gateway.
+//   PIPEWORX_META_TOOLS=1 list the gateway-wide tools (ask_pipeworx, ...) too.
+//   PIPEWORX_TIMEOUT_MS   per-request timeout, default 120000.
+
+import { readFileSync } from 'node:fs';
+
+const readJson = (rel) => JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8'));
+
+const PKG = readJson('../package.json');
+export const SLUG = PKG.pipeworx && PKG.pipeworx.slug;
+if (typeof SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(SLUG)) {
+  throw new Error(`${PKG.name}: package.json carries no valid pipeworx.slug -- this package was built wrong`);
+}
+/**
+ * The pack's slug on the GATEWAY: the /<slug>/mcp route and the `_meta.pack`
+ * every listed tool carries. Usually the same as `slug` (the npm/directory
+ * name), but 14 packs differ -- `hex-pm` is `hex_pm` on the gateway -- and
+ * filtering tools/list on the npm slug would match none of their tools
+ * (fleet #3761). publish-pack.sh stamps it from the gateway manifest.
+ */
+export const GATEWAY_SLUG = (PKG.pipeworx && PKG.pipeworx.gatewaySlug) || SLUG;
+if (typeof GATEWAY_SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(GATEWAY_SLUG)) {
+  throw new Error(`${PKG.name}: package.json carries an invalid pipeworx.gatewaySlug -- this package was built wrong`);
+}
+export const PACKAGE_NAME = PKG.name;
+export const VERSION = PKG.version;
+
+/** The pack's own tool definitions at publish time (the offline tools/list answer). */
+export const tools = readJson('../tools.json');
+
+const DEFAULT_GATEWAY = 'https://gateway.pipeworx.io';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const SIGNUP_URL = 'https://pipeworx.io/signup';
+const VIA = '(via pipeworx-standalone)';
+
+/** Resolve the bridge's settings. Exported for the tests and for callTool. */
+export function bridgeConfig(env = process.env, overrides = {}) {
+  const base = String(overrides.gatewayUrl || env.PIPEWORX_GATEWAY_URL || DEFAULT_GATEWAY).trim().replace(/\/+$/, '');
+  const apiKey = String(overrides.apiKey ?? env.PIPEWORX_API_KEY ?? '').trim();
+  const t = Number(overrides.timeoutMs ?? env.PIPEWORX_TIMEOUT_MS);
+  return {
+    endpoint: `${base}/${GATEWAY_SLUG}/mcp`,
+    apiKey,
+    timeoutMs: Number.isFinite(t) && t > 0 ? t : DEFAULT_TIMEOUT_MS,
+    metaTools: (overrides.metaTools ?? env.PIPEWORX_META_TOOLS) === '1' || overrides.metaTools === true,
+  };
+}
+
+function requestHeaders(cfg) {
+  const h = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    // Stable per package version: the gateway remembers a client's name by
+    // identifier + User-Agent (workers/gateway/src/client-identity.ts).
+    'User-Agent': `pipeworx-standalone/${VERSION} (${PACKAGE_NAME})`,
+    // Analytics label only (blob11 = 'standalone'). It never changes tier,
+    // limits or price -- anyone can send it.
+    'X-Pipeworx-Surface': 'standalone',
+  };
+  if (cfg.apiKey) h.Authorization = `Bearer ${cfg.apiKey}`;
+  return h;
+}
+
+/** Parse a gateway body: JSON, or the last JSON `data:` frame of an SSE stream. */
+function parseBody(text, contentType) {
+  if (/text\/event-stream/i.test(contentType || '')) {
+    let last = null;
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.startsWith('data:')) continue;
+      try { last = JSON.parse(line.slice(5).trim()); } catch { /* keep-alive or partial frame */ }
+    }
+    return last;
+  }
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/**
+ * POST one JSON-RPC message. Never throws: the outcome is one of
+ *   { kind: 'http', status, headers, body, text }   the gateway answered
+ *   { kind: 'network', detail }                      DNS, TLS, refused, reset
+ *   { kind: 'timeout' }                              no answer in cfg.timeoutMs
+ */
+export async function postToGateway(message, cfg) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), cfg.timeoutMs);
+  try {
+    const res = await fetch(cfg.endpoint, {
+      method: 'POST',
+      headers: requestHeaders(cfg),
+      body: JSON.stringify(message),
+      signal: ac.signal,
+    });
+    const text = await res.text();
+    return { kind: 'http', status: res.status, headers: res.headers, body: parseBody(text, res.headers.get('content-type')), text };
+  } catch (err) {
+    if (ac.signal.aborted || (err && (err.name === 'AbortError' || err.name === 'TimeoutError'))) return { kind: 'timeout' };
+    const cause = err && err.cause;
+    const detail = (cause && (cause.code || cause.message)) || (err && err.message) || String(err);
+    return { kind: 'network', detail };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── The key-not-accepted warning (one per process) ──────────────────
+
+let warnedKeyIgnored = false;
+const KEY_IGNORED = 'PIPEWORX_API_KEY was not accepted, calling anonymously.';
+
+/** True when a key was sent but the gateway still served the call as anonymous. */
+function keyIgnored(out, cfg) {
+  return !!cfg.apiKey && out.kind === 'http' && (out.headers.get('x-ratelimit-tier') || '').toLowerCase() === 'anonymous';
+}
+
+function noteTier(out, cfg, warn) {
+  if (!keyIgnored(out, cfg) || warnedKeyIgnored) return;
+  warnedKeyIgnored = true;
+  warn(`${PACKAGE_NAME}: ${KEY_IGNORED} Check the key at ${SIGNUP_URL}.`);
+}
+
+/** Test hook: forget that the warning was printed. */
+export function _resetWarnings() { warnedKeyIgnored = false; }
+
+// ── Results the host shows to the model ─────────────────────────────
+
+function errorResult(text, detail) {
+  const result = { content: [{ type: 'text', text }], isError: true };
+  if (detail) result._meta = { pipeworx_standalone: detail };
+  return result;
+}
+
+const rpcResult = (id, result) => ({ jsonrpc: '2.0', id, result });
+const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+function firstLine(text) {
+  const line = String(text || '').split(/\r?\n/).map((l) => l.trim()).find(Boolean) || '(empty body)';
+  return line.length > 200 ? `${line.slice(0, 200)}...` : line;
+}
+
+function unreachableText(cfg, out) {
+  if (out.kind === 'timeout') {
+    return `The Pipeworx gateway at ${cfg.endpoint} did not answer within ${Math.round(cfg.timeoutMs / 1000)}s, so this call timed out. `
+      + `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode. Try again; a call that keeps timing out is worth reporting.`;
+  }
+  return `Could not reach the Pipeworx gateway at ${cfg.endpoint} (${out.detail}). `
+    + `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode, so it needs network access.`;
+}
+
+function isAuthRequired(body) {
+  return !!body && (body.error_code === 'authentication_required'
+    || (body.error && body.error.data && body.error.data.reason === 'authentication_required'));
+}
+
+/** Map a tools/call outcome to the JSON-RPC response the host gets. */
+function toolsCallResponse(id, out, cfg) {
+  if (out.kind !== 'http') return rpcResult(id, errorResult(unreachableText(cfg, out), { reason: out.kind }));
+  const { status, body } = out;
+
+  // Anonymous daily cap: the gateway answers 401 with a JSON-RPC error whose
+  // message is the offer. Hosts often swallow protocol errors, so hand it over
+  // as a tool result the model actually reads.
+  if (status === 401 && isAuthRequired(body)) {
+    const data = (body.error && body.error.data) || {};
+    const parts = [body.error && body.error.message ? body.error.message : 'The anonymous daily allowance is used up.'];
+    if (data.resets_at) parts.push(`The anonymous allowance resets at ${data.resets_at}.`);
+    parts.push(cfg.apiKey
+      ? `${KEY_IGNORED} Check the key, or get a free one at ${SIGNUP_URL}.`
+      : `To keep going now, set PIPEWORX_API_KEY in this MCP server's environment; a free key is at ${SIGNUP_URL}.`);
+    return rpcResult(id, errorResult(parts.join('\n\n'), { status, reason: 'authentication_required', resets_at: data.resets_at ?? null }));
+  }
+
+  // A keyed tier over its cap: today the gateway answers 429 with a RESULT
+  // that has no isError, which reads as a success (fleet #3760). Mark it.
+  if (status === 429 && body && body.result && typeof body.result === 'object') {
+    const result = { ...body.result, isError: true };
+    if (cfg.apiKey && keyIgnored(out, cfg)) {
+      result.content = [...(Array.isArray(result.content) ? result.content : []), { type: 'text', text: KEY_IGNORED }];
+    }
+    return rpcResult(id, result);
+  }
+  if ((status === 401 || status === 429) && body && body.error) {
+    const extra = keyIgnored(out, cfg) ? ` ${KEY_IGNORED}` : '';
+    return rpcResult(id, errorResult(`${body.error.message || `HTTP ${status}`}${extra}`, { status }));
+  }
+
+  // A real JSON-RPC answer (result or protocol error): relay it verbatim,
+  // structuredContent and _meta (cost, tier, provenance) included.
+  if (body && body.jsonrpc === '2.0' && (body.result !== undefined || body.error !== undefined) && status < 500) {
+    return { ...body, id };
+  }
+
+  // 5xx, an HTML edge page, or anything else that is not JSON-RPC.
+  return rpcResult(id, errorResult(`The Pipeworx gateway returned HTTP ${status}: ${firstLine(out.text)}`, { status }));
+}
+
+function localInitialize(params) {
+  return {
+    protocolVersion: (params && params.protocolVersion) || '2025-06-18',
+    capabilities: { tools: {} },
+    serverInfo: { name: PACKAGE_NAME, version: VERSION },
+  };
+}
+
+const scopedInstructions = () =>
+  `${PACKAGE_NAME} forwards to the Pipeworx gateway and lists only the ${SLUG} pack's tools. `
+  + 'Set PIPEWORX_META_TOOLS=1 to also list ask_pipeworx and the other gateway-wide tools.';
+
+/** `<host name> (via pipeworx-standalone)`. The slug stays OUT of the name: the
+ *  gateway's scanner-name check substring-matches words like poll/watch/index. */
+export function bridgedClientName(name) {
+  const n = typeof name === 'string' && name.trim() ? name.trim() : 'unknown';
+  return n.includes(VIA) ? n : `${n} ${VIA}`;
+}
+
+/**
+ * Relay one JSON-RPC message to the gateway and return the response to write
+ * back, or null for a notification. Never throws.
+ *
+ * @param {object} message  a parsed JSON-RPC request or notification
+ * @param {{cfg?: object, warn?: (line: string) => void}} [opts]
+ */
+export async function relay(message, opts = {}) {
+  const cfg = opts.cfg || bridgeConfig();
+  const warn = opts.warn || ((line) => process.stderr.write(`${line}\n`));
+  if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+    const id = message && typeof message === 'object' && 'id' in message ? message.id : null;
+    return rpcError(id ?? null, -32600, 'Invalid Request');
+  }
+  const isNotification = !('id' in message) || message.id === undefined;
+  const id = message.id;
+
+  if (isNotification) {
+    const out = await postToGateway(message, cfg);
+    if (out.kind !== 'http') warn(`${PACKAGE_NAME}: notification ${message.method} not delivered: ${unreachableText(cfg, out)}`);
+    return null;
+  }
+
+  if (message.method === 'initialize') {
+    const params = { ...(message.params || {}) };
+    params.clientInfo = { ...(params.clientInfo || {}), name: bridgedClientName(params.clientInfo && params.clientInfo.name) };
+    if (!params.clientInfo.version) params.clientInfo.version = '0';
+    const out = await postToGateway({ ...message, params }, cfg);
+    noteTier(out, cfg, warn);
+    if (out.kind === 'http' && out.body && out.body.result && typeof out.body.result === 'object') {
+      const result = { ...out.body.result, serverInfo: { name: PACKAGE_NAME, version: VERSION } };
+      if (!cfg.metaTools) result.instructions = scopedInstructions();
+      return rpcResult(id, result);
+    }
+    // The host must still start: answer locally and let the calls report the
+    // gateway problem when they happen.
+    warn(`${PACKAGE_NAME}: initialize answered locally -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
+    return rpcResult(id, { ...localInitialize(message.params), instructions: scopedInstructions() });
+  }
+
+  if (message.method === 'tools/list') {
+    const out = await postToGateway(message, cfg);
+    noteTier(out, cfg, warn);
+    const listed = out.kind === 'http' && out.body && out.body.result && Array.isArray(out.body.result.tools)
+      ? out.body.result : null;
+    if (listed) {
+      if (cfg.metaTools) return rpcResult(id, listed);
+      const own = listed.tools.filter((t) => t && t._meta && (t._meta.pack === GATEWAY_SLUG || t._meta.pack === SLUG));
+      if (own.length > 0) return rpcResult(id, { ...listed, tools: own });
+      warn(`${PACKAGE_NAME}: the gateway listed no ${SLUG} tools; serving the tool list bundled with this package`);
+    } else {
+      warn(`${PACKAGE_NAME}: tools/list served from the snapshot bundled with this package -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
+    }
+    return rpcResult(id, { tools });
+  }
+
+  if (message.method === 'tools/call') {
+    const out = await postToGateway(message, cfg);
+    noteTier(out, cfg, warn);
+    return toolsCallResponse(id, out, cfg);
+  }
+
+  // Everything else (ping, resources/*, prompts/*, ...): relay as-is.
+  const out = await postToGateway(message, cfg);
+  noteTier(out, cfg, warn);
+  if (out.kind === 'http' && out.body && out.body.jsonrpc === '2.0') return { ...out.body, id };
+  if (message.method === 'ping') return rpcResult(id, {});
+  return rpcError(id, -32603, out.kind === 'http'
+    ? `The Pipeworx gateway returned HTTP ${out.status}: ${firstLine(out.text)}`
+    : unreachableText(cfg, out));
+}
+
+/**
+ * Call one of this pack's tools through the gateway -- the `{tools, callTool}`
+ * shape earlier versions of this package exported. Resolves with the tool's
+ * structured result; rejects with the gateway's message on any error.
+ *
+ * @param {string} name
+ * @param {Record<string, unknown>} [args]
+ * @param {{apiKey?: string, gatewayUrl?: string, timeoutMs?: number}} [opts]
+ *        apiKey defaults to process.env.PIPEWORX_API_KEY.
+ */
+export async function callTool(name, args = {}, opts = {}) {
+  const cfg = bridgeConfig(process.env, opts);
+  const res = await relay({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }, { cfg });
+  if (res.error) throw new Error(res.error.message);
+  const result = res.result || {};
+  const text = Array.isArray(result.content)
+    ? result.content.filter((c) => c && c.type === 'text').map((c) => c.text).join('\n')
+    : '';
+  if (result.isError) throw new Error(text || `${name} failed`);
+  if (result.structuredContent !== undefined) return result.structuredContent;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+export default { tools, callTool };

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@pipeworx/mcp-index-constituents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Index constituents and holdings, point-in-time.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./tools.json": "./tools.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "mcp-index-constituents": "bin/cli.js"
+  },
+  "files": ["bin/", "lib/", "tools.json", "server.json"],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "index-constituents"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pipeworx-io/mcp-index-constituents.git"
+  },
+  "mcpName": "io.github.pipeworx-io/index-constituents",
+  "pipeworx": {
+    "mode": "gateway",
+    "slug": "index-constituents",
+    "gatewaySlug": "index-constituents",
+    "sourceHash": "v1-2afb5477fd6d95659243b8be9c2b7e2f4240efb277f0af5abba8e485094d5cc3",
+    "sourceCommit": "4844029e402d6bd2fe735add8abf6d46735f8ed5"
+  }
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/index-constituents",
+  "title": "Index Constituents",
+  "description": "Index constituents and holdings, point-in-time.",
+  "version": "0.2.0",
+  "websiteUrl": "https://pipeworx.io/packs/index-constituents",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-index-constituents",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/index-constituents/mcp"
+    }
+  ]
+}

package/tools.json

@@ -0,0 +1,105 @@
+[
+  {
+    "name": "index_constituents",
+    "description": "Current constituents of a major US or developed-markets equity index — ticker, name, GICS sector, and weight — sourced from the matching iShares index-tracking ETF's daily holdings file (the closest free, point-in-time proxy for official index membership and weights; S&P/Russell do not publish those for free). Answers \"what's in the S&P 500 right now\", \"top holdings of the Russell 2000 by weight\", \"which sectors make up the S&P MidCap 400\". Cash, collateral and futures positions the ETF holds are excluded here — use ishares_etf_holdings for those.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "index": {
+          "type": "string",
+          "description": "Which index. One of: sp500, sp400, sp600, russell1000, russell2000, eafe.",
+          "enum": [
+            "sp500",
+            "sp400",
+            "sp600",
+            "russell1000",
+            "russell2000",
+            "eafe"
+          ]
+        },
+        "limit": {
+          "type": "number",
+          "description": "Max rows to return, sorted by weight descending (default 50, max 600 — pass the max to get the full index in one call)."
+        },
+        "offset": {
+          "type": "number",
+          "description": "Rows to skip, for paging past `limit` (default 0)."
+        },
+        "sector": {
+          "type": "string",
+          "description": "Optional GICS sector filter, case-insensitive substring match (e.g. \"Health Care\", \"Energy\")."
+        }
+      },
+      "required": [
+        "index"
+      ]
+    }
+  },
+  {
+    "name": "ishares_etf_holdings",
+    "description": "Full reported holdings of one of six iShares index-tracking ETFs (IVV, IJH, IJR, IWB, IWM, EFA) as of the fund's own \"as of\" date — every position including cash, collateral and futures, each labeled with its asset class so they are never silently mixed in with equities. Answers \"what does IVV actually hold today\", \"how much cash does this ETF carry\". For just the equity index membership, use index_constituents instead.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "ticker": {
+          "type": "string",
+          "description": "One of the supported iShares ETFs: IVV, IJH, IJR, IWB, IWM, EFA.",
+          "enum": [
+            "IVV",
+            "IJH",
+            "IJR",
+            "IWB",
+            "IWM",
+            "EFA"
+          ]
+        },
+        "limit": {
+          "type": "number",
+          "description": "Max rows to return, sorted by market value descending (default 50, max 600)."
+        },
+        "offset": {
+          "type": "number",
+          "description": "Rows to skip, for paging past `limit` (default 0)."
+        },
+        "asset_class": {
+          "type": "string",
+          "description": "Optional filter, case-insensitive exact match against the fund's own asset-class label (e.g. \"Equity\", \"Cash\", \"Futures\", \"Cash Collateral and Margins\", \"Money Market\")."
+        }
+      },
+      "required": [
+        "ticker"
+      ]
+    }
+  },
+  {
+    "name": "constituent_changes",
+    "description": "Dated additions and removals from the S&P 500, sourced from Wikipedia's maintained \"Historical components of the S&P 500\" table (every S&P-announced swap since 1963, each with its effective date, the ticker/company added, the ticker/company removed, and the stated reason). Answers \"what changed in the S&P 500 in 2024\", \"when was X removed from the S&P 500 and what replaced it\". Only sp500 is covered — the iShares-backed indexes above have no equivalent public, dated changes table.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "index": {
+          "type": "string",
+          "description": "Only \"sp500\" is supported.",
+          "enum": [
+            "sp500"
+          ]
+        },
+        "from": {
+          "type": "string",
+          "description": "Earliest effective date to include, as a year (\"2024\") or ISO date (\"2024-01-01\"). Omit for no lower bound."
+        },
+        "to": {
+          "type": "string",
+          "description": "Latest effective date to include, as a year (\"2024\") or ISO date (\"2024-12-31\"). Omit for no upper bound."
+        },
+        "limit": {
+          "type": "number",
+          "description": "Max rows to return, most recent first (default 50, max 600)."
+        }
+      },
+      "required": [
+        "index"
+      ]
+    }
+  }
+]