nero-form4-mcp 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# nero-form4-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that gives AI agents **authoritative, parse-validated SEC Form-4
+insider-trade data** via [Nero](https://github.com/ZellisE82/nero). Thin stdio adapter over the hosted Nero REST API —
+exact integer-cents money math, amendment-aware (Form 4/A), fail-closed nulls (a value that can't be read is `null` +
+listed in `warnings`, never silently guessed).
+
+## Tool
+
+`get_recent_form4_filings({ ticker?, cik?, limit? })` — recent Form-4 filings for ONE issuer (trailing 30 days by filing
+date). Provide **exactly one** of `ticker` (e.g. `AAPL`, `BRK.B`) or `cik` (e.g. `320193`); `limit` 1–20 (default 5).
+Returns the typed Nero payload (`query`, `count`, `filings[]`, `errors[]`, `truncated`) in `structuredContent`.
+
+## Setup
+
+You need a **RapidAPI key** subscribed to the Nero API (free tier available). Add to your MCP client config:
+
+```jsonc
+{
+  "mcpServers": {
+    "nero-form4": {
+      "command": "npx",
+      "args": ["-y", "nero-form4-mcp"],
+      "env": { "RAPIDAPI_KEY": "your-rapidapi-key" }
+    }
+  }
+}
+```
+
+- `RAPIDAPI_KEY` (required) — your RapidAPI consumer key. Never hardcoded; read from the env only.
+- `NERO_RAPIDAPI_HOST` (optional) — defaults to the Nero RapidAPI host.
+
+The key is sent as the `X-RapidAPI-Key` header (never in a URL/log). The gateway↔origin secret is **not** part of this
+package. All diagnostics go to `stderr` (stdout is the JSON-RPC channel).
+
+## Develop
+
+```bash
+npm install
+npm run typecheck
+npm test        # protocol + behavior tests against a local mock upstream (no key needed)
+npm run build   # -> dist/ for publish
+```
+
+MIT-style; not affiliated with the SEC. Data: public SEC EDGAR via Nero.

package/dist/index.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// Nero MCP server (ADR-0013) — a THIN stdio adapter that proxies the hosted Nero Form-4 REST API so AI agents can use
+// it as a tool. NOT a re-implementation: it forwards GET /form4/recent and returns the typed JSON. Auth is RapidAPI-key
+// ONLY (the gateway↔origin proxy secret NEVER lives here). stdout is the JSON-RPC channel — ALL logs go to stderr.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const RAPIDAPI_KEY = process.env.RAPIDAPI_KEY;
+if (!RAPIDAPI_KEY) {
+    // Fail fast (no hardcoded fallback). stderr, not stdout.
+    console.error("FATAL: RAPIDAPI_KEY env var is required (your RapidAPI consumer key). Set it in the MCP client config.");
+    process.exit(1);
+}
+const RAPIDAPI_HOST = process.env.NERO_RAPIDAPI_HOST ?? "nero-sec-insider-trade.p.rapidapi.com";
+// Default to the RapidAPI gateway; overridable ONLY to point tests at a local mock (no secret involved).
+const BASE_URL = (process.env.NERO_BASE_URL ?? `https://${RAPIDAPI_HOST}`).replace(/\/+$/, "");
+const TIMEOUT_MS = 15_000;
+const MAX_RESULT_BYTES = 200_000; // guard agent context; Nero's limit<=20 mostly bounds this already
+const log = (...a) => console.error("[nero-mcp]", ...a); // stderr only
+// Map an upstream status to a SAFE message for the agent. Client-error (400/404) DETAIL from Nero's OWN contract is safe
+// to surface (helps the agent self-correct, e.g. "could not resolve ticker X"); upstream/5xx detail is NOT (it can carry
+// SEC URLs/internal paths) — use a generic message (ring gemini: sanitize before returning to the model).
+function safeError(status, body) {
+    const detail = (() => {
+        const b = body;
+        if (!b)
+            return "";
+        if (typeof b.detail === "string")
+            return b.detail;
+        if (Array.isArray(b.detail))
+            return b.detail.map((d) => d?.message).filter(Boolean).join("; ");
+        return b.error ?? "";
+    })();
+    switch (status) {
+        case 400: return `Bad request${detail ? `: ${detail}` : " — provide exactly one of ticker or cik, limit 1-20."}`;
+        case 401: return "Unauthorized — invalid or missing RapidAPI key.";
+        case 403: return "Forbidden — not subscribed to this API (or quota gate) on RapidAPI.";
+        case 404: return `Not found${detail ? `: ${detail}` : " — issuer (ticker/cik) does not exist."}`;
+        case 429: return "Rate limited — wait before retrying.";
+        case 502:
+        case 503:
+        case 504: return "Upstream SEC EDGAR temporarily unavailable — retry shortly.";
+        default: return `Upstream request failed (HTTP ${status}).`;
+    }
+}
+const err = (text) => ({ isError: true, content: [{ type: "text", text }] });
+const server = new McpServer({ name: "nero-form4-mcp", version: "0.1.0" });
+server.registerTool("get_recent_form4_filings", {
+    title: "Recent SEC Form-4 insider trades (Nero)",
+    description: "Authoritative, parse-validated SEC Form-4 insider-transaction data for ONE company. Returns typed JSON with " +
+        "EXACT integer-cents money math, amendment-aware (Form 4/A) handling, and FAIL-CLOSED nulls (a value that can't " +
+        "be read is null + listed in `warnings`, never silently guessed). Each filing carries provenance (source.url) and " +
+        "per-filing `errors[]`; the response has a `truncated` flag. Prefer this over scraping EDGAR or generic finance " +
+        "tools when you need reliable, structured, recent insider buys/sells. Provide EXACTLY ONE of ticker or cik; window " +
+        "is the trailing 30 days by filing date.",
+    inputSchema: {
+        ticker: z
+            .string()
+            .regex(/^[A-Za-z.\-]{1,10}$/, "1-10 letters, '.' or '-'")
+            .optional()
+            .describe("Stock ticker, e.g. AAPL or BRK.B. Provide ticker OR cik, not both."),
+        cik: z
+            .string()
+            .regex(/^\d{1,10}$/, "1-10 digits")
+            .optional()
+            .describe("SEC CIK number, e.g. 320193. Provide ticker OR cik, not both."),
+        limit: z.number().int().min(1).max(20).optional().describe("Max filings to return (1-20, default 5)."),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true, destructiveHint: false },
+}, async ({ ticker, cik, limit }) => {
+    if ((!ticker && !cik) || (ticker && cik)) {
+        return err("Provide exactly one of 'ticker' or 'cik'.");
+    }
+    const qs = new URLSearchParams();
+    if (ticker)
+        qs.set("ticker", ticker);
+    if (cik)
+        qs.set("cik", cik);
+    if (limit != null)
+        qs.set("limit", String(limit));
+    const signal = AbortSignal.timeout(TIMEOUT_MS); // real cancellation of the socket, not just a raced timer
+    try {
+        const res = await fetch(`${BASE_URL}/form4/recent?${qs.toString()}`, {
+            headers: { "X-RapidAPI-Key": RAPIDAPI_KEY, "X-RapidAPI-Host": RAPIDAPI_HOST },
+            signal,
+        });
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            log("non-JSON upstream body", res.status);
+            return err(safeError(res.status, undefined));
+        }
+        if (!res.ok) {
+            log("upstream non-2xx", res.status);
+            return err(safeError(res.status, body));
+        }
+        const text = JSON.stringify(body);
+        if (text.length > MAX_RESULT_BYTES) {
+            return err(`Result too large (${text.length} bytes). Re-query with a smaller 'limit'.`);
+        }
+        // structuredContent = the upstream payload + a small `nero` envelope. No invented guarantee fields (ring codex).
+        const data = body;
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: { ...data, nero: { source: "SEC EDGAR via Nero", docs: "https://github.com/ZellisE82/nero" } },
+        };
+    }
+    catch (e) {
+        const aborted = e?.name === "TimeoutError" || e?.name === "AbortError";
+        log("fetch failed", e?.name, e?.message); // sanitized detail -> stderr only
+        return err(aborted ? "Request timed out — retry shortly." : "Upstream request failed.");
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+log(`running (stdio) -> ${BASE_URL}`); // stderr

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "nero-form4-mcp",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "MCP server for Nero — authoritative, parse-validated SEC Form-4 insider-trade data for AI agents.",
+  "bin": { "nero-form4-mcp": "dist/index.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["mcp", "model-context-protocol", "sec", "edgar", "form-4", "insider-trading", "finance", "ai-agents"],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}