secedgar-mcp-server

---

概述

SEC EDGAR 文件、财务数据和所有权数据。可按股票代码、名称或 CIK 查询公司，搜索自 1993 年以来的文件，比较不同公司的财务数据，并通过内幕交易、13F 持仓、13D/13G 大额持仓者和基金投资组合追踪所有权。无需 API 密钥。

工具

工具	描述
secedgar_company_search	查找公司并获取实体信息，可选包含近期文件
secedgar_search_filings	搜索自 1993 年以来的 EDGAR 文件：2001 年起支持全文搜索，此前可浏览档案
secedgar_get_filing	获取文件的元数据和文档文本，可分页或按章节获取
secedgar_get_financials	获取一家公司的某项历史 XBRL 财务数据
secedgar_get_snapshot	一次调用获取财务概况：每个受支持概念的最新值
secedgar_get_material_events	获取 8-K 文件，解码并可筛选项目代码
secedgar_get_insider_transactions	从所有权 XML 中解析 Form 4 / 4-A 内部人交易
secedgar_get_institutional_holdings	获取一家机构管理者的 13F-HR 季度持仓
secedgar_find_holders	反向查询 13F：哪些管理者申报持有某发行人的证券
secedgar_get_beneficial_owners	从结构化 SCHEDULE 13D / 13G 文件中获取某发行人持股 5% 以上的主要股东
secedgar_get_fund_holdings	从季度 NPORT-P 报告中获取 ETF 和共同基金的投资组合持仓
secedgar_fetch_frames	跨所有申报公司获取一项 XBRL 概念 × 一个期间的数据
secedgar_compare_companies	按财年或日历季度对齐，比较指定公司在多个概念上的数据
secedgar_search_concepts	查找受支持的 XBRL 概念名称，或反向查询原始标签
secedgar_dataframe_describe	列出画布数据框及其来源、TTL 和架构
secedgar_dataframe_query	跨数据框执行单条 SELECT 语句
secedgar_dataframe_drop	按名称删除画布数据框；需通过 EDGAR_DATAFRAME_DROP_ENABLED=true 显式启用

资源

资源	描述
secedgar://concepts	按报表分组的 XBRL 财务概念，将易读名称映射到 XBRL 标签
secedgar://filing-types	常见 SEC 文件类型，以及两种编号规则下的 8-K 项目代码表

secedgar_search_concepts 会向仅支持工具的客户端提供相同的概念目录。

提示词

提示词	描述
secedgar_company_analysis	对公司的 SEC 文件进行结构化分析：财务趋势、风险因素、重大事件

技能

技能	描述
secedgar-guide	说明每个工具可回答哪些所有权问题、如何获取 CIK、accession number、CUSIP 和基金系列 ID，以及报告数据缺失前应检查哪些覆盖范围限制

该技能随包提供，文件位于 skills/secedgar-guide/SKILL.md。插件宿主会从软件包加载该技能；支持 Skills 扩展的 MCP 客户端则会从服务读取该技能，路径为 skill://secedgar-guide/SKILL.md。

功能参考

secedgar_company_search _工具

• query 接受股票代码（股票、ETF、共同基金）、当前或曾用公司名称，或 CIK；include_filings（默认开启）会添加最多 filing_limit 份文件（默认 10；最高可设为 1,000，但内联上限为 50），并可通过 forms、filed_after 和 filed_before 筛选
• 返回 SIC 代码、交易所、财年结束日期和注册州；若查询的是基金股票代码，还会返回 series_id / class_id；未找到匹配项时返回 no_match（data.suggestions 中包含相近匹配项），有多个匹配项时返回 multiple_matches
• 日期或表格类型筛选条件可扩展到档案（最多 10 页）；history_scanned_through 会报告扫描到的范围

---

secedgar_search_filings _工具

• 全文 query（短语、OR、-exclusion、wildcard*、按 ticker: / cik: 限定范围），或不带查询，按 forms 和／或实体浏览；filed_after / filed_before 可单独使用（单独使用 filed_after 时搜索范围截至今天，单独使用 filed_before 时从 2001-01-01 开始，或在 2001 年之前从 1993-01-01 开始）；limit 最高为 100（默认值为 20；超过 100、最高为 1,000 的值会按 100 提供）；offset 最高为 9,999（仅适用于 sort: "relevance" 的 2001 年起始搜索）
• 全文覆盖 2001 年及之后；更早的范围可追溯至 1993 年，数据来自档案，其中自由文本查询需要用 ticker: / cik: 限定范围，且最多读取 50 份文件（scan 会报告计数）
• 每份文件一行，并标记 source（efts、submissions、full-index）；全文搜索的行会列出 matched_documents（供 secedgar_get_filing 使用的文件名）；响应包含 total、form_distribution、total_is_exact，以及全文搜索的 total_documents

---

secedgar_get_filing _工具

• accession_number 可使用带连字符或 18 位数字的格式；可选的 cik 可加快查找，document 用于指定附件，include_xbrl 用于包含 XBRL 文件；每页 content_limit 为 1,000–200,000 个字符（默认值为 50,000；超过 200,000、最高为 1,000,000 的值会按 200,000 提供）
• 使用 offset / next_offset 翻页，直到 content_truncated 为 false；也可使用 section 跳转（例如 item 1 或 part i 这样的标题），之后移除 section 继续翻页，因为它的优先级高于 offset；被截断文档的第一页会提供最多 50 个标题及其偏移量组成的 outline
• documents 会将文件拆分为主要文件、附件和辅助文件；binary 条目（扫描件、PDF、档案文件）会以 binary_document 失败；找不到 section 时会返回 section_not_found 和 outline
• 如果档案未提供某份文件的主要文档（常见于 2000–2001 年），则会改为读取完整提交文件 <accession>.txt，并在通知中说明

---

secedgar_get_financials _工具

• company（股票代码或 CIK）以及 concept（友好名称或原始 XBRL 标签）；taxonomy 可选 us-gaap（默认值）、ifrs-full 或 dei；period_type 可选 annual、quarterly 或 all；如果某个概念以多个单位报告，unit 可选择一个 SEC 单位键（ZAR、USD、USD/EUR）；limit 为 1–100，用于截取内联序列
• 返回去重后的序列，按时间从新到旧排列，每个日历期间一个值，并包含 form、filed、accession_number 和 tag，且统一使用一个 unit（其他单位会在 caveats 中列出）；tags_tried 会列出尝试过的标签；结果为空时会以 no_concept_data、no_frame_data、no_period_data 或 no_unit_data 失败
• 如果 concept 既不是友好名称，也不是 UpperCamelCase 标签，则会以 unknown_concept 失败，并提供标准组合（free_cash_flow、ebitda、working_capital）的公式，或最多三个最接近的友好名称

---

secedgar_get_snapshot _工具

• company、taxonomy（us-gaap（默认值）或 ifrs-full）以及 period_type（annual、quarterly 或 both（默认值））；一次 companyfacts 读取即可涵盖所有受支持的概念，不会暂存为 dataframe
• 每个 lines 条目会报告期间型概念最新的 annual 和 quarterly 值，或资产负债表和实体信息概念最新的 instant 值，并注明对应的 tag，归入该行的 taxonomy；申报人未报告的概念会列入 gaps，并附上 tags_tried

---

secedgar_get_material_events _工具

• company 加上最多 20 个 items 代码：自 2004-08-23 起使用带点号的代码（2.02），此前使用单个整数（12）；这两种代码体系没有重叠，因此可在切换日期前后配对查询；filed_after / filed_before 可单独使用，并可查询存档；limit 为 1–1,000，实际最多返回 100 条（默认 20）
• 每份申报都会将其 items 解码为 code、label 和 regime（current / legacy）；item_distribution 统计时间范围内每个代码的出现次数，total_8k_scanned 与 total_matched 的对比可显示筛选器排除了多少结果
• 日期范围查询最多读取 10 页存档；history_scanned_through 和 dataset.truncated 会报告未读取到的内容

---

secedgar_get_insider_transactions _工具

• company 是发行方；transaction_type 可设为 purchase（代码 P）、sale（代码 S）或 all（默认）；limit 为 1–1,000，实际最多返回 100 条（默认 20）；不包括 Form 3 或 Form 5
• 未设置日期范围时，最多扫描最新的 100 份 Form 4 / 4-A 申报；filed_after / filed_before（含边界，可单独使用）可查询 2003 年年中以来的任意时期，最多读取 100 份申报；history_scanned_through 列出已解析申报中最早的一份
• 每笔交易都包含申报人、关系、transaction_code 和 transaction_type、is_derivative、未带符号的 shares_traded 及其 direction（acquire / dispose）、每股价格，以及交易后的持股数；dataset.truncated 标记未解析的申报，filings_other_issuer 统计公司以另一发行方申报所有人身份提交的 Form 4，这些申报不会增加数据行。价格文本保留定点表示法中的数字，且至少有两位小数。

---

secedgar_get_institutional_holdings _工具

• company 是 13F 申报人（使用 CIK 最可靠），而非投资组合公司；查找投资组合公司应使用 secedgar_find_holders；quarter 格式为 YYYY-QN，默认使用最新申报；limit 为 1–500（默认 20；请求最多 1,000 条时，实际最多返回 500 条），并支持 offset / next_offset；consolidate（默认 true）会将子行合并为按价值排序的持仓
• 较早季度可在存档中查找（最多 10 页）；如果某季度只有 13F-NT 通知，则会以 no_filings_found 失败，并列出该通知的 accession 编号和期间
• 持仓、分页、合并结果和 dataframe 均基于原始 13F-HR 及其同一期间的 13F-HR/A 修正文件组成；修正文件按 acceptanceDateTime 顺序应用：RESTATEMENT 会替换此前组成的全部内容（包括较早的 NEW HOLDINGS）；NEW HOLDINGS 修正文件会追加其行，除非其表格重复了已组成的每一行（CUSIP、类别、看涨/看跌、裁量权、股份数、股份类型），此时会按重述处理。数值会根据每个 accession 各自的申报日期进行标准化。只读取最后一次可读取重述之后的表格
• amendments（按申报时间从新到旧）会列出每个 accession、申报日期和封面类型（无法读取时标为 UNAVAILABLE 并说明原因），以及 applied_as：restatement、new_holdings、superseded 或 not_applied（类型或表格无法读取，原因会在通知中说明）；可使用 secedgar_get_filing 检查任何一份申报。composed_accessions 按应用顺序列出行所来源的申报。amendment_search_complete=false 表示存档搜索范围有限或不可用，可能遗漏了修正文件
• 持仓包含发行方、CUSIP、以整美元计的 market_value_usd、股份数或本金、put_call 以及 source_accession_numbers（合并后的持仓会列出其来源申报；此字段也会作为 dataframe 列）；total_holdings_in_filing 统计原始 13F-HR 的原始行数，total_holdings_composed 统计组成后的原始行数，total_positions 统计组成后的不同持仓数；accession_number 和 filing_date 列出原始 13F-HR 的信息；如果法定名称相同，则会以 ambiguous_entity 失败

---

secedgar_find_holders _工具

• issuer 可以是股票代码、CIK 或名称，也可选填 9 个字符的 cusip，这是精确匹配键（按名称短语匹配可能出现过度或不足匹配）；quarter 格式为 YYYY-QN，默认选择已过 45 天申报期限的最新季度；limit 为 1–100（默认 20；实际最多返回 1,000 条，每次最多 100 条），数据来自最多 500 份已获取的申报文件
• 每行包含 filer_cik、accession_number 和 form；search_mode（cusip / name）、total_filings、fetched 和 holders_in_quarter 用于说明结果规模。列表未排序，因此请传入 filer_cik 调用 secedgar_get_institutional_holdings 以查看持仓
• 当匹配的文件数超过获取上限时，提示会给出可精确续查的 secedgar_search_filings 请求，包括查询条件、日期和文件偏移量。将 results.period_ending 筛选为季度末日期，然后根据样本中的 filer_cik 和搜索结果中的 cik 去重，并保留最新的 filing_date。每获取完一整页就将偏移量增加 100；EDGAR 的分页上限为 10,000 份文件，较低的总数可能会掩盖超出该上限的更多文件

---

secedgar_get_beneficial_owners _工具

• issuer 为被持有的公司；form_kind 可为 all（默认）、13D 或 13G；include_amendments（默认 true）；limit 为 1–20 份匹配的已解析申报文件（默认 10；实际最多返回 1,000 份，每次最多 20 份）。按时间从新到旧的扫描最多检查 50 份文件，并排除列出其他发行方的附表；排除的文件和解析失败的文件不计入 limit
• 每份申报文件都会列出 reporting_persons，以及每位申报人的投票权、处置权和 percent_of_class。联合申报人针对同一批股份报告这些数据，因此不能相加；13D 包含 purpose_of_transaction，13G 则不包含
• 结构化 XML 附表的覆盖范围从 2024-12-18 开始；legacy_filings_before_coverage 统计该发行方更早的 SC 13D / SC 13G 文本申报文件
• total_structured_filings 分为 filings_examined + filings_not_examined；已检查的文件分为 filings_parsed + filings_excluded_other_issuer + filings_failed.length。解析失败的申报文件会标记为 document_not_found（404）或 unparseable（包括缺少发行方身份信息），并设置 partial。truncated 表示达到结果数量上限或扫描上限后，索引中的附表仍未检查；此状态与解析失败无关

---

secedgar_get_fund_holdings _工具

• fund 可以是股票代码（VOO）、系列 ID（S000002839）或 CIK；包含多个系列的信托会以 series_required 失败，并列出其系列，因此请传入 series_id；report_date 用于从 available_report_periods 中选择期间；limit 为 1–100（默认 20；实际最多返回 1,000 条，每次最多 100 条），并支持 offset / next_offset
• 持仓按 percent_of_net_assets 从高到低排列，包含名称、CUSIP / ISIN / LEI、balance 和 units、value_usd，以及资产类别和发行方类别；此外还提供基金净资产、总资产和总负债。持仓的 currency 表示计价货币；估值始终以 USD 表示。百分比文本会以定点表示法保留数值中的数字。
• 持仓截至 report_period_date，该日期大约比 filing_date 早两个月；publication_lag_days 表示两者间隔的天数

---

secedgar_fetch_frames _工具

• concept 可以是易读名称或原始标签；period 格式如 CY2023、CY2024Q2 或 CY2023Q4I；taxonomy 可为 us-gaap（默认）或 dei；unit（默认 USD）；sort 可为 desc / asc；limit 为 1–100（默认 25；实际最多返回 1,000 条，每次最多 100 条），并支持 offset / next_offset
• 每次调用只查询一个标签：unqueried_tags 和 related_tags 会列出其他变体，需分别获取；value_distribution.max_to_p95_ratio 用于标记规模异常值，period_end_range 显示是否混入不同财年的数据，caveats 会提示财年第四季度数据缺失
• concept 既不是易读名称也不是 UpperCamelCase 标签时，会以 unknown_concept 失败；格式正确但没有数据框架的标签会返回 no_data

---

secedgar_compare_companies _工具

• 2–10 个 companies × 1–8 个 concepts；taxonomy 为 us-gaap（默认）或 ifrs-full；period_type 为 annual（默认）或 quarterly；periods 为 1–12（默认 4；设为 12 时最多提供 1,000 个），当内联矩阵过大时会进一步缩减
• cells 会按日历 period 对齐每个值，并保留其 frame、period_end 和源 tag；若调用没有可比较的年度数据，则会以 no_comparable_data 失败
• failed_companies（原因包括 not_found、ambiguous 或 no_company_facts）和 gaps 会报告缺失内容；caveats 会标示公司间不同的期间结束日期和单位不匹配
• 无法识别的概念会列在 unknown_concepts 中并附上提示；仅当所有概念都无法识别时，调用才会以 unknown_concept 失败

---

secedgar_search_concepts _工具

• search 会在友好名称、标签和标记中进行子字符串搜索，因此原始标签（如 NetIncomeLoss）会反向匹配到其友好名称；group 和 taxonomy 可用于筛选；不带参数时返回完整目录
• 每个概念都会列出 tags、ifrs_tags（仅包含在实时 20-F 文件中确认过的 IFRS 元素）、related_tags、unit 和 group

---

secedgar_dataframe_describe _工具

• 可选的 name 用于指定一个 dataframe；省略时会按从新到旧的顺序列出租户的活动 dataframes
• 每个条目包含 source_tool、query_params、created_at / expires_at、row_count、truncated，以及 secedgar_dataframe_query 的 SQL 必须匹配的 column_schema

---

secedgar_dataframe_query _工具

• 在 sql 中执行一条 DuckDB SELECT（支持联接、聚合、窗口函数和 CTE）；row_limit 为 1–10,000（默认 1,000），preview 可减少内联行数；每次最多提供 10,000 行，最高可达 100,000 行；使用 register_as（df_XXXXX_XXXXX）将结果保存为新的 dataframe
• 返回 columns、rows、row_count 和 row_count_capped；当 row_count_capped 为 true 时，表示 row_count 是上限值，而非总数；BIGINT 列会序列化为字符串
• 写入操作、DDL、文件读取函数、多条语句和系统目录会因类型化原因而被拒绝（non_select_statement、denied_function、multi_statement、system_catalog_access 等）；即使未限定的 current_schema 是列名，也会以 denied_function 拒绝，因此读取此类列时请使用 <table>.current_schema

---

secedgar_dataframe_drop _工具

• 要删除的 dataframe 的 name；操作幂等，未匹配到任何内容时返回 dropped: false
• 默认关闭；只有在 EDGAR_DATAFRAME_DROP_ENABLED=true 时才启用；禁用时不会出现在 tools/list 中

---

secedgar://concepts _资源

• 按报表分组的友好名称目录，格式为 text/markdown，包含每个概念对应的 us-gaap、IFRS 和替代定义标签
• secedgar_get_financials、secedgar_compare_companies 和 secedgar_fetch_frames 接受这些名称作为概念

---

secedgar://filing-types _资源

• 常见 SEC 表格及其提交频率和使用场景，格式为 text/markdown
• 包含两种编号规则下的 8-K 项目代码表，即 secedgar_get_material_events 的 items 筛选词汇表

---

secedgar_company_analysis _提示词

• 参数：必填 company；可选自由文本 focus_areas
• 返回一条用户消息，其中包含编号工作流（公司搜索、通过 secedgar_get_snapshot 获取财务概况并通过 secedgar_get_financials 查看趋势、文件审查、重大事件，以及通过 secedgar_compare_companies 进行同业比较，并使用 secedgar_fetch_frames 进行全市场排名）和发现模板；若 focus_areas 中包含内幕人士、机构或大股东相关术语，则会添加相应的所有权分析步骤；若包含 “ownership”，则会添加全部三项

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志。

EDGAR 专属功能：

• 请求速率控制在 SEC 的 10 req/s 限制以内；收到 429 后，调用会在本地以 rate_limited 状态失败，并显示 EDGAR_RATE_LIMIT_COOLDOWN_SECONDS 的倒计时，之后发出一次探测请求
• 支持通过股票代码（包括基金代码）、公司当前和曾用名称或原始 CIK 解析 CIK；未匹配时会提供近似匹配建议
• 友好的 XBRL 概念名称可处理历史标签变更；secedgar_get_financials、secedgar_get_snapshot 和 secedgar_compare_companies 使用相同的去重逻辑和标签优先级，因此数值一致；caveats 会标示数据序列中的缺口
• 将申报文件从 HTML 转换为文本，支持标题检测，并可对超大申报文件按偏移量分页
• 可选择启用本地 SQLite 镜像，保存公司股票代码和 XBRL company-facts（EDGAR_MIRROR_ENABLED），从磁盘提供 CIK 解析和财务数据

便于 Agent 使用的输出：

• 对话内 SQL：响应中包含 dataset 字段的任何工具，都会将完整结果暂存为 DuckDB dataframe（df_<id>），而内联列表仍受 limit 限制；使用 secedgar_dataframe_describe 检查，再用 secedgar_dataframe_query 查询
• 使用可区分的输出并明确标示缺口：申报文件搜索结果行中的 source、search_mode、8-K 条目 regime、带类型的 failed_companies 原因，以及包含 tags_tried 的 gaps，用于替代填充为零的值
• 完整性说明：history_scanned_through、total_is_exact、publication_lag_days 和 dataset.truncated 会告知 Agent 扫描范围及遗漏内容
• 每个概念使用一个参数名：company、filed_after / filed_before 和 forms 在所有工具中含义相同；也接受常见的其他拼写形式（ticker、cik、start_date、end_date、form_types 等）作为别名

开始使用

连接到托管实例，无需安装：

claude mcp add --transport http secedgar-mcp-server https://secedgar.caseyjhand.com/mcp

或在本地运行：

claude mcp add secedgar-mcp-server -e EDGAR_USER_AGENT="YourAppName [email protected]" -- npx -y @cyanheads/secedgar-mcp-server

对于其他客户端，请将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/secedgar-mcp-server"],
      "env": { "EDGAR_USER_AGENT": "YourAppName [email protected]" }
    }
  }
}

SEC 要求每个请求都使用 "AppName [email protected]" 格式的 User-Agent；无需账户或密钥。Docker 或源码构建说明请参阅运行服务。

配置

变量	描述	默认值
EDGAR_USER_AGENT	**必需。**发送给 SEC 的 User-Agent，格式为 "AppName [email protected]"。SEC 会屏蔽未提供该值的 IP。若值无法作为 HTTP 标头发送（例如包含长破折号或弯引号、内部换行符），服务器会在启动时停止，并报错指出此变量。	—
EDGAR_RATE_LIMIT_RPS	对 SEC 的每秒最大请求数（1–10）。	10
EDGAR_RATE_LIMIT_COOLDOWN_SECONDS	收到 429 后，在发出一次探测请求前于本地拒绝调用的秒数。	600
EDGAR_TICKER_CACHE_TTL	公司和基金代码文件的缓存秒数。	3600
EDGAR_DATASET_TTL_SECONDS	Canvas 数据框的 TTL；每次数据框操作都会续期。	86400
EDGAR_DATAFRAME_DROP_ENABLED	设为 true 可启用 secedgar_dataframe_drop，这是唯一具有破坏性的工具。	false
EDGAR_CLAMP_OVERSIZED_LIMITS	将超出上限的 limit、content_limit、periods、preview 或 row_limit 按上限处理，而不是拒绝。设为 false 可拒绝超出上限的值。	true
EDGAR_MIRROR_ENABLED	启用公司代码和 XBRL 公司事实的本地 SQLite 镜像。仅支持 Node/Bun；使用 bun run mirror:init 初始化一次。	false
EDGAR_MIRROR_PATH	存放镜像数据库的目录。	./data/edgar-mirror
EDGAR_MIRROR_REFRESH_CRON	进程内刷新 cron（仅限 HTTP 传输），例如 0 9 * * *。省略时，使用 bun run mirror:refresh 刷新。	—
EDGAR_MIRROR_FALLBACK_LIVE	镜像未命中时回退到实时 SEC API。设为 false 可仅从镜像读取。	true
CANVAS_PROVIDER_TYPE	Canvas 引擎；none 会禁用数据框。	duckdb
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果；按键名进行脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）以内。自由格式值中的机密不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 埋点（跨度、指标、完成日志）。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于导出跟踪和指标的 OTLP 基础 URL。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP 日志导出端点（例如 http://localhost:4318/v1/logs）。	—

完整的可选覆盖项列表请参见 .env.example。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+）。

• 克隆并安装：

  git clone https://github.com/cyanheads/secedgar-mcp-server.git
  cd secedgar-mcp-server && bun install
  cp .env.example .env   # set EDGAR_USER_AGENT
  

• 构建并运行：

  bun run rebuild
  bun run start:http   # or start:stdio; HTTP listens at http://localhost:3010/mcp
  

• 运行检查和测试：

  bun run devcheck     # Lint, format, typecheck, security
  bun run test         # Vitest test suite
  bun run lint:mcp     # Validate MCP definitions against spec
  

Docker

docker run --rm -e EDGAR_USER_AGENT="YourAppName [email protected]" -p 3010:3010 ghcr.io/cyanheads/secedgar-mcp-server:latest

镜像默认使用端口 3010 上的 HTTP 传输、无状态会话模式，并将日志写入 /var/log/secedgar-mcp-server。若要通过 MCP 客户端使用 stdio 运行，请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "EDGAR_USER_AGENT=YourAppName [email protected]", "ghcr.io/cyanheads/secedgar-mcp-server:latest"]。若要在本地构建，请运行 docker build -t secedgar-mcp-server .；默认会安装 OpenTelemetry 对等依赖项——构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

镜像内含镜像 CLI，因此运行中的容器可以初始化并刷新自身的镜像：

docker exec <container> bun run mirror:verify    # sync status + sample reads
docker exec <container> bun run mirror:init      # one-time bootstrap from the SEC bulk archive
docker exec <container> bun run mirror:refresh   # re-ingest after SEC rebuilds the archive

项目结构

目录	用途
src/index.ts	createApp() 入口：注册资源和提示词，启动 SEC 客户端、canvas 和可选的镜像。
src/config	使用 Zod 解析并验证服务环境变量。
src/mcp-server/tools/definitions	工具定义（*.tool.ts）和 buildToolDefinitions() 注册列表。
src/mcp-server/resources/definitions	资源定义：XBRL 概念和申报类型。
src/mcp-server/prompts/definitions	提示词定义：公司分析。
src/services/edgar	节奏受控的 SEC 客户端、CIK 解析、XBRL 概念映射和序列去重、所有权 / 13D / 13G / NPORT-P 解析器、8-K 条目表、HTML 转文本。
src/services/edgar/mirror	可选启用的本地 SQLite 镜像，包含公司股票代码和 XBRL company-facts。
src/services/canvas-bridge	基于框架 DataCanvas 的适配器：df_<id> 命名、每表 TTL、禁止访问系统目录的 SQL。
scripts	构建、devcheck 和 lint 工具，以及 mirror:* 命令。
tests	单元测试和集成测试，与 src/ 结构对应。

开发指南

开发指南和架构规则见 CLAUDE.md 和 AGENTS.md。简而言之：

• 由处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 buildToolDefinitions()（src/mcp-server/tools/definitions/index.ts）中注册新工具，并在 src/index.ts 的 createApp() 数组中注册资源和提示词
• 包装外部 SEC EDGAR 调用：验证原始响应 → 规范化为领域类型 → 返回输出架构；切勿伪造缺失的 XBRL 字段——应将其列在 gaps 中

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证授权。详情请参阅 LICENSE 文件。