filinglens

filinglens

filinglens 是一个小型本地桥接层，用于连接托管的 Finbolt MCP 服务。其核心是来自 SEC 文件的公司财务数据，每个数字都可以追溯到来源文件：查询某项已报告事实，即可获得该数值及其 accession 编号、表格类型、申报日期和 XBRL 标签；查询报表，则会按期间从新到旧返回利润表、资产负债表或现金流量表。核心功能之外还提供市场数据——报价、日线／周线／月线时间序列、汇率和新闻情绪——以及常见的技术指标。

该桥接层本身不保存任何数据。它在本地提供上游服务捕获的工具列表，并将每次工具调用转发到上游，原样返回结果。

带标签的子集——23 个工具中的 21 个

此重建版本是一个带标签的子集：它提供实时捕获中的 23 个工具里的 21 个。省略的两个工具是 find_tool 和 run_tool，这对元分发工具可搜索并运行“所有 113 个数据工具，包括默认列表中没有的工具”。这是一个动态接口，涉及大约 92 个未枚举工具，其架构从未公开，因此无法固定为对等实现，故这里有意不注册。测试套件会断言它们不存在。

提供的 21 个工具均为只读：带引文的 SEC 文件财务数据、市场数据和技术指标。其中没有交易、订单或账户工具。上游描述将这些数据标记为“仅供个人研究”；使用时请遵守这一限制。

工具

时间序列、搜索和报价：

• fetch_time_series_daily — 日线 OHLCV。必填：symbol。
• fetch_time_series_weekly — 周线 OHLCV。必填：symbol。
• fetch_time_series_monthly — 月线 OHLCV。必填：symbol。
• search_endpoint — 股票代码／公司搜索。必填：keywords。
• fetch_quote — 最新价格和交易信息。必填：symbol。
• fetch_news_sentiment — 新闻情绪。必填：tickers。
• fetch_company_overview — 概览、比率、市值。必填：symbol。
• fetch_exchange_rate — 货币兑换。必填：from_currency、to_currency。

报表和收益：

• fetch_income_statement — 必填：symbol。
• fetch_balance_sheet — 必填：symbol。
• fetch_cash_flow — 必填：symbol。
• fetch_earnings — EPS 预估值与实际值对比。必填：symbol。

技术指标：

• fetch_sma — 必填：symbol、interval、time_period。
• fetch_ema — 必填：symbol、interval、time_period。
• fetch_macd — 必填：symbol、interval。
• fetch_rsi — 必填：symbol、interval。
• fetch_bbands — 必填：symbol、interval。

SEC 文件工具：

• analyze_stock — 一次调用生成简报：已申报的基本面数据（每份文件均附有 accession 引文）、市场数据和推导得出的比率。必填：symbol。
• compare_stocks — 并排比较 2–6 只股票的表格。必填：symbols。
• get_fact — 一项已报告数据及其引文；从未报告的数据会标记为缺失，不会进行估算。必填：company、concept。
• financials — 来自 SEC 文件的完整报表，按期间从新到旧排列，每个空值均附有原因。必填：company。

配置

• FINBOLT_MCP_URL（可选）— 覆盖上游端点。默认值为 https://api.getfinbolt.com/mcp。（此覆盖钩子是本重建版本自行标注的重建内容。）
• FINBOLT_API_KEY（可选）— 设置后，每个上游请求都会携带 Authorization: Bearer <key> 标头。未设置时，不会发送密钥标头。（标头名称由注册记录固定；Bearer 方案和环境变量转发均为带标签的重建内容——原始接口是在不含密钥的情况下捕获的。）

转发机制

在首次工具调用时，客户端会与上游建立一个可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（协议版本 2025-03-26，客户端信息名称为 filinglens），然后发送 notifications/initialized 通知，接着发送携带调用方原样参数的 tools/call 请求。当上游在响应 initialize 时返回 Mcp-Session-Id 标头， 该值会随会话的后续每个请求发送，并在进程存续期间重复使用。响应 可能是普通 JSON，也可能是服务器发送事件； 两种格式都会读取。

成功的上游结果会原样传递， 包括上游设置的任何 isError 标记。 失败情况——JSON-RPC 错误、非 2xx 状态码、无法读取的响应，或 无法完成的请求——会作为 isError 结果返回，其 文本以 filinglens error: 开头（此呈现方式 是本次重建自行添加的标注）。

命令行界面

每个工具也可作为子命令使用，并接收一个 JSON 参数 字符串：

npx @reneturcios/filinglens fetch_quote '{"symbol":"AAPL"}'
npx @reneturcios/filinglens get_fact '{"company":"AAPL","concept":"revenue"}'
npx @reneturcios/filinglens financials '{"company":"AAPL","statement":"income"}'
npx @reneturcios/filinglens --version

退出代码：成功时为 0，结果为 isError 时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/filinglens mcp

MCP 客户端配置：

{
  "mcpServers": {
    "filinglens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/filinglens", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/filinglens
docker run --rm ghcr.io/cloudcorprecords/filinglens --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他 参数会照常传递给命令行界面。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全使用存根 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。