@cyanheads/secedgar-mcp-server 0.1.9

package/dist/services/edgar/filing-to-text.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Convert SEC filing HTML to readable plain text.
+ * @module services/edgar/filing-to-text
+ */
+import { convert } from 'html-to-text';
+const CONVERT_OPTIONS = {
+    wordwrap: false,
+    selectors: [
+        { selector: 'a', options: { ignoreHref: true } },
+        { selector: 'img', format: 'skip' },
+        { selector: 'table', options: { uppercaseHeaderCells: false } },
+    ],
+};
+/** Strip Inline XBRL markup that produces noise in text conversion. */
+function stripInlineXbrl(html) {
+    // Remove <ix:header>...</ix:header> block (hidden XBRL metadata, context, references)
+    let cleaned = html.replace(/<ix:header\b[\s\S]*?<\/ix:header>/gi, '');
+    // Unwrap remaining ix:* tags (nonFraction, nonNumeric, continuation) — keep their text content
+    cleaned = cleaned.replace(/<\/?ix:[^>]*>/gi, '');
+    return cleaned;
+}
+/** Convert filing HTML to plain text, optionally truncating to a character limit. */
+export function filingToText(html, limit) {
+    const full = convert(stripInlineXbrl(html), CONVERT_OPTIONS);
+    const totalLength = full.length;
+    if (!limit || totalLength <= limit) {
+        return { text: full, truncated: false, totalLength };
+    }
+    // Truncate at a word boundary
+    let end = limit;
+    while (end > 0 && full[end] !== ' ' && full[end] !== '\n') {
+        end--;
+    }
+    if (end === 0)
+        end = limit;
+    return { text: full.slice(0, end), truncated: true, totalLength };
+}
+//# sourceMappingURL=filing-to-text.js.map

package/dist/services/edgar/filing-to-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filing-to-text.js","sourceRoot":"","sources":["../../../src/services/edgar/filing-to-text.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,eAAe,GAAsB;IACzC,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE;QACT,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE;QAChD,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE;QACnC,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE,EAAE;KAChE;CACF,CAAC;AAEF,uEAAuE;AACvE,SAAS,eAAe,CAAC,IAAY;IACnC,sFAAsF;IACtF,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,qCAAqC,EAAE,EAAE,CAAC,CAAC;IACtE,+FAA+F;IAC/F,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;IACjD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,KAAc;IAEd,MAAM,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC,CAAC;IAC7D,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC;IAEhC,IAAI,CAAC,KAAK,IAAI,WAAW,IAAI,KAAK,EAAE,CAAC;QACnC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACvD,CAAC;IAED,8BAA8B;IAC9B,IAAI,GAAG,GAAG,KAAK,CAAC;IAChB,OAAO,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;QAC1D,GAAG,EAAE,CAAC;IACR,CAAC;IACD,IAAI,GAAG,KAAK,CAAC;QAAE,GAAG,GAAG,KAAK,CAAC;IAE3B,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AACpE,CAAC"}

package/dist/services/edgar/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Domain types for SEC EDGAR API responses and internal data structures.
+ * @module services/edgar/types
+ */
+/** CIK resolution result from company_tickers.json lookup. */
+export interface CikMatch {
+    cik: string;
+    exchange?: string;
+    name: string;
+    ticker: string;
+}
+/** Raw entry from SEC's company_tickers.json. */
+export interface TickerEntry {
+    cik_str: number;
+    ticker: string;
+    title: string;
+}
+/** Submissions API response (data.sec.gov/submissions/CIK*.json). */
+export interface SubmissionsResponse {
+    cik: string;
+    entityType: string;
+    exchanges: string[];
+    filings: {
+        recent: FilingsRecent;
+        files: Array<{
+            name: string;
+            filingCount: number;
+            filingFrom: string;
+            filingTo: string;
+        }>;
+    };
+    fiscalYearEnd: string;
+    name: string;
+    sic: string;
+    sicDescription: string;
+    stateOfIncorporation?: string;
+    tickers: string[];
+}
+/** Parallel arrays from the submissions API recent filings. */
+export interface FilingsRecent {
+    accessionNumber: string[];
+    filingDate: string[];
+    form: string[];
+    primaryDocDescription: string[];
+    primaryDocument: string[];
+    reportDate: string[];
+}
+/** EFTS full-text search response. */
+export interface EftsResponse {
+    aggregations?: {
+        form_filter?: {
+            buckets: Array<{
+                key: string;
+                doc_count: number;
+            }>;
+        };
+    };
+    hits: {
+        hits: EftsHit[];
+        total: {
+            value: number;
+            relation: string;
+        };
+    };
+    query: {
+        from: number;
+        size: number;
+        query: string;
+    };
+}
+export interface EftsHit {
+    _id: string;
+    _source: {
+        adsh: string;
+        ciks?: string[];
+        display_names?: string[];
+        file_date: string;
+        file_description?: string;
+        file_num?: string[];
+        file_type?: string;
+        film_num?: string[];
+        form?: string;
+        biz_locations?: string[];
+        inc_states?: string[];
+        items?: string[];
+        period_ending?: string | null;
+        root_forms?: string[];
+        sequence?: number;
+        sics?: string[];
+        xsl?: string | null;
+    };
+}
+/** Filing index JSON response. */
+export interface FilingIndex {
+    directory: {
+        name: string;
+        item: Array<{
+            name: string;
+            type: string;
+            size: string;
+            'last-modified': string;
+        }>;
+    };
+}
+/** XBRL companyconcept API response. */
+export interface CompanyConceptResponse {
+    cik: number;
+    description?: string;
+    entityName: string;
+    label: string;
+    tag: string;
+    taxonomy: string;
+    units: Record<string, CompanyConceptUnit[]>;
+}
+export interface CompanyConceptUnit {
+    accn: string;
+    end: string;
+    filed: string;
+    form: string;
+    fp: string;
+    frame?: string;
+    fy: number;
+    start?: string;
+    val: number;
+}
+/** XBRL frames API response. */
+export interface FramesResponse {
+    ccp: string;
+    data: FrameEntry[];
+    description?: string;
+    label: string;
+    pts: number;
+    tag: string;
+    taxonomy: string;
+    uom: string;
+}
+export interface FrameEntry {
+    accn: string;
+    cik: number;
+    end: string;
+    entityName: string;
+    loc: string;
+    val: number;
+}
+/** Friendly concept name mapping. */
+export interface ConceptMapping {
+    label: string;
+    tags: string[];
+    taxonomy: string;
+    unit: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/edgar/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/edgar/types.ts"],"names":[],"mappings":"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"}

package/dist/services/edgar/types.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Domain types for SEC EDGAR API responses and internal data structures.
+ * @module services/edgar/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/edgar/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/edgar/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@cyanheads/secedgar-mcp-server",
+  "version": "0.1.9",
+  "description": "Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.",
+  "mcpName": "io.github.cyanheads/secedgar-mcp-server",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "secedgar-mcp-server": "dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": ["dist/", "README.md", "LICENSE", "Dockerfile", "server.json"],
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "rebuild": "bun scripts/clean.ts && bun scripts/build.ts",
+    "clean": "bun scripts/clean.ts",
+    "devcheck": "bun scripts/devcheck.ts",
+    "tree": "bun scripts/tree.ts",
+    "format": "biome check --write --unsafe .",
+    "lint:mcp": "bun scripts/lint-mcp.ts",
+    "test": "vitest run",
+    "dev:stdio": "MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts",
+    "dev:http": "MCP_TRANSPORT_TYPE=http bun --watch src/index.ts",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "sec",
+    "edgar",
+    "sec-edgar",
+    "xbrl",
+    "filings",
+    "financial-data",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyanheads/secedgar-mcp-server.git"
+  },
+  "homepage": "https://github.com/cyanheads/secedgar-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/cyanheads/secedgar-mcp-server/issues"
+  },
+  "author": "cyanheads (https://github.com/cyanheads)",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.3.0"
+  },
+  "packageManager": "bun@1.3.11",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cyanheads/mcp-ts-core": "^0.1.28",
+    "html-to-text": "^9.0.5",
+    "pino-pretty": "^13.1.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@types/html-to-text": "^9.0.4",
+    "@types/node": "^25.5.0",
+    "depcheck": "^1.4.7",
+    "ignore": "^7.0.5",
+    "tsc-alias": "^1.8.16",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  }
+}

package/server.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.cyanheads/secedgar-mcp-server",
+  "description": "Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.",
+  "repository": {
+    "url": "https://github.com/cyanheads/secedgar-mcp-server",
+    "source": "github"
+  },
+  "version": "0.1.9",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/secedgar-mcp-server",
+      "runtimeHint": "bun",
+      "version": "0.1.9",
+      "environmentVariables": [
+        {
+          "name": "EDGAR_USER_AGENT",
+          "description": "User-Agent header for SEC compliance. Format: \"AppName contact@email.com\".",
+          "format": "string",
+          "isRequired": true
+        },
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    },
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/secedgar-mcp-server",
+      "runtimeHint": "bun",
+      "version": "0.1.9",
+      "environmentVariables": [
+        {
+          "name": "EDGAR_USER_AGENT",
+          "description": "User-Agent header for SEC compliance. Format: \"AppName contact@email.com\".",
+          "format": "string",
+          "isRequired": true
+        },
+        {
+          "name": "MCP_HTTP_HOST",
+          "description": "The hostname for the HTTP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "127.0.0.1"
+        },
+        {
+          "name": "MCP_HTTP_PORT",
+          "description": "The port to run the HTTP server on.",
+          "format": "string",
+          "isRequired": false,
+          "default": "3010"
+        },
+        {
+          "name": "MCP_HTTP_ENDPOINT_PATH",
+          "description": "The endpoint path for the MCP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "/mcp"
+        },
+        {
+          "name": "MCP_AUTH_MODE",
+          "description": "Authentication mode to use: 'none', 'jwt', or 'oauth'.",
+          "format": "string",
+          "isRequired": false,
+          "default": "none"
+        },
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        }
+      ],
+      "transport": {
+        "type": "streamable-http",
+        "url": "http://localhost:3010/mcp"
+      }
+    }
+  ]
+}