@pipeworx/mcp-mic 0.0.0-stage → 0.1.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,126 @@
-# Temporary Holding Version
+# @pipeworx/mic
 
-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.
+ISO 10383 Market Identifier Code (MIC) decoder — venue name, operator, country and status behind the 4-character exchange code, no auth.
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1831+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
+
+## Tools
+
+- `decode_mic(code)` — decode one MIC (e.g. `"XNYS"`, `"XLON"`) to the venue's market name, legal operator, LEI, country, city, website and registry status. Reports whether the code is an **operating MIC** (the venue operator as a whole, e.g. `"XNYS"` for the New York Stock Exchange) or a **segment MIC** (one specific market/order book under an operator, e.g. `"ARCX"`, NYSE Arca, under `"XNYS"`). An operating MIC also carries `segment_count` — call `search_mics` with `operating_mic` to list them.
+- `search_mics(country?, operating_mic?, status?, name_contains?, limit?, offset?)` — filter the registry. Returns aggregate counts first (`total`, `by_status`, `by_country`) and a page of rows after. Pass `operating_mic` to list every market under one venue operator; a zero-match combination names the filters tried rather than returning a bare empty array.
+
+**Complements `openfigi`**: openfigi returns `exchCode` on a security's exchange listing with no decoder for it — `decode_mic` is that decoder.
+
+## Data source
+
+Publisher: ISO, delegated to ANNA (the Association of National Numbering Agencies) as the Registration Authority for ISO 10383 — the Market Identifier Code list, ~2,900 codes. The registry is published as a downloadable file only (no query API), so this pack answers from a baked table refreshed on a schedule rather than a live per-call fetch. `data_as_of` in every response is the capture time the answer reflects.
+
+**Licence.** ISO 10383 is a published international standard; ANNA distributes the current MIC list for public reference use.
+
+## Two kinds of MIC
+
+ISO 10383 itself distinguishes an **operating MIC** (the venue operator, e.g. `"XNYS"`) from a **segment MIC** (one market under that operator, e.g. `"ARCX"` under `"XNYS"`, or `"XCHI"`, NYSE Texas, also under `"XNYS"`). A security's `exchCode` can be either kind — `decode_mic` reports which, and for an operating MIC, how many segments sit under it.
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "mic": {
+      "url": "https://gateway.pipeworx.io/mic/mcp"
+    }
+  }
+}
+```
+
+### What this endpoint actually serves
+
+`tools/list` at `https://gateway.pipeworx.io/mic/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 1831+ 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/decode_mic \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"XNYS"}'
+```
+
+No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/decode_mic`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
+
+## Standalone (no gateway account)
+
+This package also runs as a local stdio MCP server — no Pipeworx account, no
+gateway round-trip:
+
+```json
+{
+  "mcpServers": {
+    "mic": {
+      "command": "npx",
+      "args": ["-y", "@pipeworx/mcp-mic"]
+    }
+  }
+}
+```
+
+Or run it directly to confirm it starts:
+
+```bash
+npx -y @pipeworx/mcp-mic
+```
+
+It speaks MCP over stdin/stdout and answers `initialize`/`tools/list`/`tools/call`
+for **only** this pack's tools — none of the shared meta-tools the gateway
+connection above adds. Same source, same tools, no ask_pipeworx routing.
+
+## 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 Mic 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,17 @@
+#!/usr/bin/env node
+//
+// Entry point for `npx @pipeworx/mcp-<slug>`.
+//
+// Packs ship as raw TypeScript (no build step — see publish-pack.sh for why:
+// tsx sidesteps every extensionless-import / bare-JSON-import edge case a
+// per-pack tsc build would have to solve one pack at a time). This file
+// registers tsx's ESM loader programmatically, then hands off to src/server.ts,
+// which wraps the pack's {tools, callTool} export in a stdio MCP server.
+//
+// Copied verbatim into every published pack repo by scripts/publish-pack.sh —
+// edit this file, not a per-pack copy.
+import { register } from 'tsx/esm/api';
+
+register();
+
+await import('../src/server.ts');

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@pipeworx/mcp-mic",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MIC — ISO 10383 Market Identifier Code decoder (fleet #3261)",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "mcp-mic": "bin/cli.js"
+  },
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "mic"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pipeworx-io/mcp-mic.git"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@cloudflare/workers-types": "^4.20260405.1"
+  },
+  "pipeworx": {
+    "sourceHash": "v1-06db289850363c6fc75c46c9134af215aa4f0d19ac76a83b95bcfc3c0a59cd4b",
+    "sourceCommit": "514e3efb42b8d81082c07e01d3ae7654bbf91f52"
+  }
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/mic",
+  "title": "Mic",
+  "description": "MIC — ISO 10383 Market Identifier Code decoder (fleet #3261)",
+  "version": "0.1.0",
+  "websiteUrl": "https://pipeworx.io/packs/mic",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-mic",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/mic/mcp"
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,261 @@
+interface McpToolDefinition {
+  name: string;
+  description: string;
+  /** Human-facing one-liner (fleet #1967). Optional; consumers fall back to
+   *  description. Kept in step with shared/src/types.ts — scripts/lib/
+   *  check-inlined-types.mjs reports drift at publish time. */
+  summary?: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+    anyOf?: Array<{ required: string[] }>;
+    oneOf?: Array<{ required: string[] }>;
+    allOf?: Array<{ required: string[] }>;
+  };
+  outputSchema?: Record<string, unknown>;
+}
+
+interface McpToolExport {
+  tools: McpToolDefinition[];
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+  meter?: { credits: number };
+  cost?: Record<string, unknown>;
+  provider?: string;
+}
+
+/**
+ * MIC — ISO 10383 Market Identifier Code decoder (fleet #3261)
+ *
+ * Decodes the 4-character venue code openfigi returns as `exchCode` on a
+ * security's exchange listing (and that most market-data feeds use the same
+ * way) to the trading venue's own name, legal operator, country, city and
+ * status, per ANNA's Market Identifier Code registry — the Registration
+ * Authority for ISO 10383.
+ *
+ * SHAPE. ANNA publishes the registry as a downloadable file only (checked
+ * live 2026-10-17: the registry's own listing page links straight to the
+ * file; there is no query API, keyed or otherwise), so this pack answers
+ * from a baked table rather than a live per-call fetch — the same "local
+ * copy when live fails" shape as every other baked-index pack in this repo
+ * (mcps/south-dakota-code is the worked example). The table is uploaded to
+ * KV at deploy and injected by the gateway as `args._bakedIndex` on the
+ * first call into this pack — see ensureIndex() below and
+ * workers/gateway/src/pack-baked-indexes.json. Refresh path:
+ * scripts/bake-index.mjs, re-run on a schedule (ANNA updates the registry on
+ * an ongoing basis).
+ *
+ * Two MIC "kinds" (per ISO 10383 itself): an OPERATING MIC names the venue
+ * operator as a whole (e.g. "XNYS", the New York Stock Exchange); a SEGMENT
+ * MIC names one specific market/order book under that operator (e.g.
+ * "ARCX", NYSE Arca, operates under XNYS). decode_mic reports which kind a
+ * code is and, for an operating MIC, how many segments sit under it.
+ *
+ * Tools:
+ * - decode_mic:   one MIC -> venue name, operator, country, city, status
+ * - search_mics:  filter the registry by country, operator, status, name
+ */
+import type { MicRow } from './mic-index-data.js';
+
+const tools: McpToolExport['tools'] = [
+  {
+    name: 'decode_mic',
+    description:
+      'Decode an ISO 10383 Market Identifier Code (MIC) — the 4-character venue code openfigi returns as `exchCode` ' +
+      'on an exchange listing, and the code most market-data feeds use the same way — to the trading venue\'s own ' +
+      'name, legal operator, country, city, website and registry status. Reports whether the code is an OPERATING ' +
+      'MIC (the operator as a whole, e.g. "XNYS") or a SEGMENT MIC (one specific market under an operator, e.g. ' +
+      '"ARCX" under "XNYS"); an operating MIC also carries segment_count — call search_mics with operating_mic to list them.',
+    summary: 'The venue name, operator, country and status behind an ISO 10383 Market Identifier Code.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: { type: 'string', description: '4-character ISO 10383 MIC, e.g. "XNYS" (NYSE) or "XLON" (London Stock Exchange).' },
+      },
+      required: ['code'],
+    },
+  },
+  {
+    name: 'search_mics',
+    description:
+      'Filter the ISO 10383 Market Identifier Code registry by country, operating MIC, status and/or a name fragment. ' +
+      'Returns aggregate counts first (total matched, by_status, by_country) and a page of rows after. Use operating_mic ' +
+      'to list every segment market under one venue operator (e.g. every segment under "XNYS").',
+    summary: 'Trading venues in the ISO 10383 Market Identifier Code registry, filtered by country, operator, status or name.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        country: { type: 'string', description: 'ISO 3166-1 alpha-2 country code of the venue, e.g. "US", "GB", "JP".' },
+        operating_mic: { type: 'string', description: 'List every market (segment or operating) under this operating MIC, e.g. "XNYS" to list NYSE\'s own segments.' },
+        status: { type: 'string', description: 'Registry status.', enum: ['ACTIVE', 'UPDATED', 'EXPIRED'] },
+        name_contains: { type: 'string', description: 'Case-insensitive fragment of the market name, legal entity name or acronym, e.g. "nasdaq".' },
+        limit: { type: 'number', description: 'Rows per page, 1-500 (default 50).' },
+        offset: { type: 'number', description: 'Rows to skip for paging (default 0).' },
+      },
+    },
+  },
+];
+
+// fleet #2754: a pack registered in pack-baked-indexes.json must never VALUE
+// import its data module — the whole table would then be evaluated at
+// module scope in every gateway isolate, including ones that never serve
+// this pack. `MicRow` above is a type-only import (erased at build time);
+// the actual rows arrive at runtime via args._bakedIndex, injected by the
+// gateway from KV on the first call into this pack and adopted for the
+// isolate's life.
+let MIC_ROWS: MicRow[] = [];
+let MIC_INDEX_CAPTURED_AT = '';
+
+function ensureIndex(args: Record<string, unknown>): void {
+  if (MIC_ROWS.length) return;
+  const idx = args._bakedIndex as Record<string, unknown> | null | undefined;
+  const rows = idx?.MIC_ROWS;
+  const capturedAt = idx?.MIC_INDEX_CAPTURED_AT;
+  if (!Array.isArray(rows) || rows.length === 0 || typeof capturedAt !== 'string') {
+    // Loud on purpose: answering from an empty table would read as "no such
+    // MIC" / "no match" — a silent wrong answer indistinguishable from a
+    // real miss (docs/silent-zero-policy.md).
+    throw new Error(
+      `mic: the baked MIC index is unavailable (${idx == null ? 'not injected' : 'malformed'}). ` +
+        'The gateway loads it from KV on the first call into this pack; this is a server-side fault, not an unknown code — retry shortly.',
+    );
+  }
+  MIC_ROWS = rows as MicRow[];
+  MIC_INDEX_CAPTURED_AT = capturedAt;
+}
+
+// Tuple field indices — see mic-index-data.ts's own header for the full list.
+const F = {
+  mic: 0, operatingMic: 1, type: 2, marketName: 3, legalEntityName: 4, lei: 5,
+  marketCategoryCode: 6, acronym: 7, countryCode: 8, city: 9, website: 10,
+  status: 11, creationDate: 12, lastUpdateDate: 13, lastValidationDate: 14,
+  expiryDate: 15, comments: 16,
+} as const;
+
+function toRecord(r: MicRow) {
+  return {
+    mic: r[F.mic],
+    operating_mic: r[F.operatingMic] || null,
+    type: r[F.type] === 'OPRT' ? 'operating' : r[F.type] === 'SGMT' ? 'segment' : r[F.type] || null,
+    market_name: r[F.marketName] || null,
+    legal_entity_name: r[F.legalEntityName] || null,
+    lei: r[F.lei] || null,
+    market_category_code: r[F.marketCategoryCode] || null,
+    acronym: r[F.acronym] || null,
+    country_code: r[F.countryCode] || null,
+    city: r[F.city] || null,
+    website: r[F.website] || null,
+    status: r[F.status] || null,
+    creation_date: r[F.creationDate] || null,
+    last_update_date: r[F.lastUpdateDate] || null,
+    last_validation_date: r[F.lastValidationDate] || null,
+    expiry_date: r[F.expiryDate] || null,
+    comments: r[F.comments] || null,
+  };
+}
+
+function decodeMic(args: Record<string, unknown>) {
+  ensureIndex(args);
+  const raw = args.code;
+  if (typeof raw !== 'string' || !raw.trim()) {
+    throw new Error('Required argument "code" is missing or empty. Pass a 4-character MIC like "XNYS" or "XLON".');
+  }
+  const code = raw.trim().toUpperCase();
+  const row = MIC_ROWS.find((r) => r[F.mic] === code);
+  if (!row) {
+    throw new Error(
+      `user_error: "${code}" is not a MIC in the ISO 10383 registry (${MIC_ROWS.length} codes, as of ${MIC_INDEX_CAPTURED_AT}). ` +
+        'Verify the code, or use search_mics to browse by name or country rather than guessing one.',
+    );
+  }
+  const decoded = toRecord(row);
+  const segments =
+    decoded.type === 'operating'
+      ? MIC_ROWS.filter((r) => r[F.operatingMic] === code && r[F.mic] !== code)
+      : [];
+  return {
+    found: true,
+    data_as_of: MIC_INDEX_CAPTURED_AT,
+    ...decoded,
+    ...(decoded.type === 'operating'
+      ? {
+          segment_count: segments.length,
+          ...(segments.length
+            ? { note: `This is an operating MIC with ${segments.length} segment market(s) under it — call search_mics with operating_mic: "${code}" to list them.` }
+            : {}),
+        }
+      : {}),
+  };
+}
+
+function searchMics(args: Record<string, unknown>) {
+  ensureIndex(args);
+  const country = typeof args.country === 'string' && args.country.trim() ? args.country.trim().toUpperCase() : null;
+  const operatingMic = typeof args.operating_mic === 'string' && args.operating_mic.trim() ? args.operating_mic.trim().toUpperCase() : null;
+  const status = typeof args.status === 'string' && args.status.trim() ? args.status.trim().toUpperCase() : null;
+  const nameContains = typeof args.name_contains === 'string' && args.name_contains.trim() ? args.name_contains.trim().toLowerCase() : null;
+  const limit = Math.min(500, Math.max(1, Math.round((args.limit as number) ?? 50)));
+  const offset = Math.max(0, Math.round((args.offset as number) ?? 0));
+
+  if (status && status !== 'ACTIVE' && status !== 'UPDATED' && status !== 'EXPIRED') {
+    throw new Error(`user_error: unknown status "${args.status}". Use ACTIVE, UPDATED or EXPIRED.`);
+  }
+
+  const filtersTried: string[] = [];
+  if (country) filtersTried.push(`country=${country}`);
+  if (operatingMic) filtersTried.push(`operating_mic=${operatingMic}`);
+  if (status) filtersTried.push(`status=${status}`);
+  if (nameContains) filtersTried.push(`name_contains="${nameContains}"`);
+
+  const matched = MIC_ROWS.filter((r) => {
+    if (country && r[F.countryCode] !== country) return false;
+    if (operatingMic && r[F.operatingMic] !== operatingMic) return false;
+    if (status && r[F.status] !== status) return false;
+    if (nameContains) {
+      const hay = `${r[F.marketName]} ${r[F.legalEntityName]} ${r[F.acronym]}`.toLowerCase();
+      if (!hay.includes(nameContains)) return false;
+    }
+    return true;
+  });
+
+  const byStatus: Record<string, number> = {};
+  const byCountry: Record<string, number> = {};
+  for (const r of matched) {
+    byStatus[r[F.status]] = (byStatus[r[F.status]] ?? 0) + 1;
+    if (r[F.countryCode]) byCountry[r[F.countryCode]] = (byCountry[r[F.countryCode]] ?? 0) + 1;
+  }
+
+  const page = matched.slice(offset, offset + limit).map(toRecord);
+
+  return {
+    found: matched.length > 0,
+    data_as_of: MIC_INDEX_CAPTURED_AT,
+    total: matched.length,
+    by_status: byStatus,
+    by_country: byCountry,
+    returned: page.length,
+    offset,
+    ...(offset + page.length < matched.length ? { next_offset: offset + page.length } : {}),
+    ...(matched.length === 0
+      ? {
+          note: filtersTried.length
+            ? `No MIC in the registry (${MIC_ROWS.length} codes, as of ${MIC_INDEX_CAPTURED_AT}) matches: ${filtersTried.join(', ')}. That is a real zero, not an error.`
+            : `No filters were given and the registry is unexpectedly empty — this should never happen; treat as a server fault.`,
+        }
+      : {}),
+    rows: page,
+  };
+}
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  switch (name) {
+    case 'decode_mic':
+      return decodeMic(args);
+    case 'search_mics':
+      return searchMics(args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+export default { tools, callTool } satisfies McpToolExport;