Skip to main content
Glama
eneszh
QuantQJ

filings-search

by QuantQJ
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

filings-search

基于 SEC 10-K 文件的混合（BM25 + kNN）智能检索系统，运行于 OpenSearch，配备 Claude 工具使用代理，该代理可自主规划搜索并生成带有逐项引用和硬性数值溯源检查的回答。采用 FastAPI 接口 + TypeScript MCP 工具服务器。作为 Qdrant 管道的 OpenSearch 升级版构建；引用或放弃的溯源逻辑移植自我的 12 域出处包装器。

EDGAR ──► connector ──► section splitter ──► chunker ──► embeddings ──► OpenSearch (BM25 + HNSW kNN)
(SEC API)  (ticker→CIK,   (Item 1/1A/1C/7/8…)  (450 tok,    (nomic-embed-text            │
            10-K list,     order-constrained,    60 overlap)  local via Ollama, or        │
            iXBRL strip)   x-ref filtered)                     OpenAI)                     ▼
                                                                          hybrid search (RRF) + filters
                                                                                       │
                                                       ┌───────────────────────────────┼─────────────────────┐
                                                       ▼                               ▼                     ▼
                                              FastAPI /search /ask           TS MCP server            eval harness
                                              /chunk /companies         (search_filings, ask_filings)  (P@k/MRR, LLM-judge)
                                                       ▲
                                              Claude agent (tool loop):
                                              resolve_company → search_filings (item/ticker/FY filters, hybrid|bm25|knn)
                                              → expand_chunk → answer with [c:chunk_id] cites → numeric grounding check

包含内容

层

文件

说明

连接器

filings_search/edgar.py

SEC 股票代码映射 + browse-edgar 回退（处理 successor-shell CIK 问题）、data.sec.gov 提交数据、主文档获取、iXBRL/HTML 剥离、磁盘缓存

解析

filings_search/parse.py

10-K 项目分割器：标题验证的标题、交叉引用过滤器、规范顺序 + 最长跨度选择（解决目录行问题）

分块

filings_search/chunk.py

尊重段落、令牌限制（450/60 重叠）、确定性块 ID `sha1(accession

item

idx)`

嵌入

filings_search/embed.py

默认使用本地 Ollama 上的 nomic-embed-text（768 维）；OpenAI text-embedding-3-small 回退

索引

filings_search/index.py

OpenSearch 2.19 映射：英语分析器 BM25 字段 + knn_vector（lucene HNSW，余弦相似度）+ 关键字元数据（股票代码、CIK、项目、财年、访问号…）

检索

filings_search/search.py

bm25、knn、hybrid（客户端倒数排名融合）、元数据过滤器、邻近扩展

代理

filings_search/agent.py

Claude（claude-opus-5）工具循环；工具：list_indexed_companies、resolve_company、search_filings、expand_chunk；答案必须引用 [c:id]；答案中的每个数字必须出现在引用的块中，否则响应会被标记为 grounded_numbers=false

API

filings_search/api.py

FastAPI：GET /search、POST /ask、GET /chunk/{id}?expand=、GET /companies、GET /health

MCP

mcp/src/server.ts

TypeScript stdio MCP 服务器，暴露 list_companies、search_filings、get_chunk、ask_filings

评估

eval/

run_retrieval_eval.py（按模式评估 hit@1/hit@5/MRR@10，带标注查询）、run_grounding_eval.py（数值溯源 + LLM 作为评判的引用支持）

运行方式

docker compose up -d                       # OpenSearch 2.19 (knn + neural plugins), :9200
ollama pull nomic-embed-text               # local embeddings
python3.12 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
./.venv/bin/python ingest.py --recreate AAPL MSFT NVDA JPM XOM WMT TSLA JNJ   # ~2 min, 8 filings, ~2.1k chunks
./run_api.sh                               # FastAPI on :8801
./.venv/bin/python -m filings_search.agent "What does NVIDIA disclose about export controls to China?"
./.venv/bin/python eval/run_retrieval_eval.py
./.venv/bin/python eval/run_grounding_eval.py

MCP（Claude Desktop / Claude Code / Cursor）：

{"mcpServers": {"filings-search": {"command": "node", "args": ["/ABS/PATH/filings-search/mcp/dist/server.js"],
                                    "env": {"FILINGS_API_URL": "http://127.0.0.1:8801"}}}}

通过环境变量配置：FS_OPENSEARCH_URL、FS_INDEX、FS_EMBED_BACKEND=ollama|openai、FS_AGENT_MODEL、FS_JUDGE_MODEL、SEC_USER_AGENT。代理/评判需要 ANTHROPIC_API_KEY（或 ~/.env）。

结果（2026-08-18，8 份文件 / 2,101 个块，28 个标注查询）

检索 — 参见 eval/retrieval_results.json：

设置

模式

hit@1

hit@5

MRR@10

平均毫秒

未过滤

bm25

0.571

0.857

0.686

5.7

未过滤

knn

0.679

0.857

0.759

29.7

未过滤

hybrid

0.679

0.857

0.759

37.9

股票代码过滤

bm25

0.679

0.929

0.772

3.8

股票代码过滤

knn

0.679

0.893

0.779

26.6

股票代码过滤

hybrid

0.714

0.929

0.812

34.9

代理溯源 — 10 个分析师问题，claude-opus-5 代理 + claude-opus-5 评判（参见 eval/grounding_results.json）：

指标

值

数值溯源率（每个数字出现在引用的块中）

10/10 = 1.00

LLM 评判结果：已溯源 / 部分溯源 / 未溯源

9 / 1 / 0

由引用块支持的主张平均比例

0.968

每个答案平均引用数

9.7

每个答案平均工具调用次数（代理选择的搜索/扩展）

7.6

平均延迟

41 秒（简单 13 秒 → 多项目 59 秒）

10 个问题运行的令牌数

563k 输入 / 23k 输出

那一个 partially_grounded（沃尔玛关税，0.87）是因为代理总结了引用块中更狭窄陈述的缓解措施 — 评判发现了这一点；这正是评判的用途。

设计说明 / 诚实限制

  • 智能 ≠ 固定 RAG。 模型选择公司、项目、模式和轮数；固定的 top-k 管道没有第二次机会。工具描述带有“何时使用”指南（项目映射、bm25 用于数字、无结果时扩大范围）。

  • 溯源严格是故意的。 衍生四舍五入（“$99,779M” → “~$99.8B”）会被标记为未溯源；分析师希望看到文件中的原始数字。如果不同意，可以放宽容差。

  • 10-K 结构怪癖是真实的，不是解析器错误：JPM 和 XOM 是“包装型”10-K，其 MD&A/财务数据位于书末的财务部分（在最后一个项目下标记）；NVIDIA 在项目 15 下提交报表。这些的评估标签仅为股票代码。后续工作是 F 页面检测（Consolidated Statements of … 标题）以重新标记为项目 8。

  • RRF 是客户端实现的 — 透明且易于推理；OpenSearch 的 hybrid 查询标准化管道是集群内的替代方案。尚无交叉编码器重排序器。

  • 本次运行每家公司仅一份文件；--filings N 可提取前几年数据（财年过滤器已在映射和工具中）。

  • 无认证、无速率限制、单节点 OpenSearch — 这是一个功能性垂直领域，而非部署方案。

This server cannot be installed

-
license - not tested
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/QuantQJ/filings-search'

If you have feedback or need assistance with the MCP directory API, please join our Discord server