Power your agent
Yayıncıdan kurulum. PlugMCP uç noktası değildir.
Host a copy with our keys and logs.
Registry'de henüz paketlenmiş bir sürüm yok. Deponun README dosyasını izleyin.
Uzak URL mi, yoksa makinenizde bir komut mu? İki kurulum arasındaki fark
PlugMCP’de çalıştır
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
BaşlatYayıncıdan
面向金融研报问答、私有知识库检索与多工具分析生成的企业级 ReAct-RAG Agent。
核心目标：让用户用自然语言完成「跨研报检索 → 可信溯源 → 联网补充 → Word / Excel / Markdown 输出 → 多轮会话延续」。
金融分析师、投研人员或行业研究团队每天需要阅读大量研报、年报、公告和政策材料。传统流程通常是逐篇打开 PDF、手动搜索关键词、复制表格、再整理成报告，效率低且容易遗漏来源。
本项目实现了一个面向金融研报场景的 ReAct-RAG Agent，能够：
"面向金融研报问答与知识密集型场景的企业级智能体框架
本仓库不包含私有研报数据、向量库、密钥、运行日志和本地数据库。请通过
.env.example配置环境变量，并将自己的 PDF / 数据文件放入本地忽略目录中。
sql.py 提供 Text2SQL 路径，可对 SQLite 财务指标库进行自然语言查询，并返回 source_file / source_page。.docx 报告。
flowchart LR
U[User / Frontend] --> S[Streamlit UI]
U --> A[FastAPI REST + SSE]
S --> G[PersistentAgent]
A --> G
G --> LG[LangGraph ReAct Workflow]
LG --> T1[RAG Tool]
LG --> T2[Web Search Tool]
LG --> T3[Excel / Word / Markdown Tools]
T1 --> P[PDF Parser]
P --> R[BM25 + Vector Retriever]
R --> RR[RRF Fusion]
RR --> CE[Cross-Encoder Reranker]
CE --> C[Semantic Cache]
G --> CP[Checkpoint Store]
C --> Redis[(Redis)]
CP --> DB[(SQLite / PostgreSQL / Redis / Memory)]
用户请求
→ Streamlit / FastAPI
→ PersistentAgent
→ LangGraph ReAct 循环
→ 工具调用：RAG / Search / Excel / Word / Markdown
→ 反思与结果整理
→ 带来源、工具轨迹、token / cost 信息的响应
检索流程：
PDF / 文档
→ 版面解析与表格抽取
→ chunking
→ BM25 Top-10 + Vector Top-10
→ RRF 融合到最多 20 个候选
→ Cross-Encoder 精排
→ Top-3 返回给 Agent
当前默认注册工具以
react_agent/tools/__init__.py为准。sql.py已实现但默认未注册时，不会被 Agent 自动调用。
FastAPI 与 Streamlit 并存，共享同一套 Agent 实例与持久化存储。
本项目新增 stdio 模式 MCP Server，用于将金融研报 RAG 能力接入 Claude Desktop、Cursor、Claude Code、MCP Inspector 等支持 MCP 的客户端。
MCP 启动方式：
cd src
python mcp_rag_server.py
使用 MCP Inspector 测试：
cd src
npx -y @modelcontextprotocol/inspector -- python mcp_rag_server.py
使用 Codex 外接测试
codex mcp add financial-rag --env MCP_EXPOSE_ADMIN_TOOLS=0 -- "E:\anaconda\envs\agent_base\python.exe" "E:\transformer_program\nanoGPT_program\AI_Agent\agent_v0\react-agent-main\src\mcp_rag_server.py"
# 确认是否注册：
/mcp
query: 根据内部数据库，2026 年 1 月，国内领先的芯片设计企业兆易创新和谁正式签署战略合作协议？
MCP 启动入口遵循“薄启动”原则：启动阶段不预热 embedding、reranker、Chroma、Redis 等重资源，避免 stdio 握手阶段阻塞。普通业务查询只需调用 query_financial_reports；首次查询会自动触发 retriever / reranker 单例预热并进行有限等待。诊断或显式预热场景可设置 MCP_EXPOSE_ADMIN_TOOLS=1，再调用 start_rag_singleton_warmup / get_rag_singleton_warmup_status。
curl http://localhost:8000/health
curl -X POST http://localhost:8000/api/v1/chat/invoke \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{
"message": "总结新能源行业最近的投资主线，并给出来源",
"session_id": "demo-session"
}'
curl -N -X POST http://localhost:8000/api/v1/chat/stream \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{
"message": "检索半导体行业最近的供需变化，并生成要点",
"session_id": "demo-session"
}'
流式事件类型：
token | tool_call | tool_result | usage | done | error
curl http://localhost:8000/api/v1/metrics
推荐 Python 3.10+。
git clone https://github.com/lihaibohhh/ReAct-RAG-Agent.git
cd ReAct-RAG-Agent/src
使用 uv：
uv sync
或使用 pip：
pip install -r requirements.txt
cp .env.example .env
根据自己的模型和工具服务填写：
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=your_deepseek_api_key
TAVILY_API_KEY=your_tavily_api_key
# 可选：Redis / PostgreSQL / LangSmith 等
REDIS_URL=redis://localhost:6379/0
POSTGRES_URL=postgresql://user:password@localhost:5432/dbname
cd src
streamlit run tests/test_agent.py
cd src
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
Swagger 文档：
http://localhost:8000/docs
pytest tests/api -q
测试设计要点：
python eval/run_eval.py
支持检索评测与端到端评测。已验证指标：
金融研报常见双栏排版、表格密集、页眉页脚干扰。简单 PDF loader 容易造成左右栏交错、表格断裂、页码丢失。本项目改用 PyMuPDF 读取坐标块，按版面重建阅读顺序；表格由 pdfplumber 抽取后转 Markdown 整块保留，避免字符分块器破坏行列结构。
BM25 擅长股票代码、公司名、指标名等精确匹配；向量检索擅长语义近似。两路 Top-K 召回后用 RRF 融合，再交给 Cross-Encoder 精排。召回池从 10 扩到 20 后，减少相关文档在检索阶段被提前丢弃的问题。
早期实现中，低相关结果也会被缓存 1 小时，后续相似 query 命中缓存后会跳过新检索，造成错误固化。本项目让 reranker 返回 top_score，写入缓存前进行门控：
DeepSeek / LangChain 工具调用中，复杂工具参数可能进入 .invalid_tool_calls，如果路由只看 .tool_calls，就会误判“没有工具调用”，导致悬空 tool_call 被写入 checkpoint，下一轮恢复历史时触发多轮 400 死锁。
本项目统一封装 _ai_tool_call_ids()，同时覆盖 .tool_calls 与 .invalid_tool_calls，并在路由、入口净化、异常兜底三层使用同一检测口径。这个问题的教训是：协议检测必须与实际发送给模型的序列化路径保持一致。
这轮服务化改造不仅是“加几个接口”，而是补齐了 LLM 应用上线前常见的工程护栏：
MCP 改造中定位到的问题：首次 query_financial_reports 变慢的主要根因不是 BM25、Chroma、Redis、reranker 或 _dual_retrieve() 算法本身，而是 LangSmith/LangChain tracing 在首次 retriever.invoke() 时采集 runtime metadata，触发 git describe --tags --always --dirty 并卡住 40 秒以上。
已落地的处理方式：
mcp_rag_server.py 改为 stdio 薄启动入口，启动时不做重资源预热；LANGCHAIN_TRACING_V2、LANGSMITH_TRACING_V2、LANGCHAIN_TRACING、LANGSMITH_TRACING；react_agent/mcp_server/ 目录，按职责模块化注册；_get_retriever() 与 _get_reranker() 两个进程内单例；start_rag_singleton_warmup 可手动后台触发单例预热，立即返回；get_rag_singleton_warmup_status 用于查询后台单例预热状态；推荐使用流程：
1. List Tools
2. query_financial_reports
如需管理员提前预热，可手动执行：
1. MCP_EXPOSE_ADMIN_TOOLS=1
2. start_rag_singleton_warmup
3. get_rag_singleton_warmup_status，直到 warmup_status.state=done
4. query_financial_reports
当前已确认的问题边界：完整 RAG 链路预热不是解决首次慢 query 的关键；关闭 tracing 后，预热应降级为“只创建 retriever/reranker 单例”，避免额外执行 _dual_retrieve() 与真实 rerank。
react-agent-main/
└── src/
├── api/ # FastAPI 服务层
│ ├── main.py # app 入口、lifespan、路由挂载
│ ├── settings.py # 配置校验
│ ├── errors.py # problem+json 错误信封
│ ├── middleware.py # request_id 日志与 Prometheus 采集
│ ├── security.py # API Key 鉴权
│ ├── ratelimit.py # Redis 限流与 token 预算
│ ├── metrics.py # Prometheus 指标
│ └── routes/
│ ├── chat.py # legacy chat 路由
│ └── v1/
│ ├── chat.py # v1 token 级 SSE / invoke
│ └── sessions.py # 会话历史与删除
├── react_agent/
│ ├── core/ # LangGraph 工作流、节点、路由、状态、checkpointer
│ ├── rag/ # PDF 解析、分块、召回、精排、语义缓存、向量库
│ ├── tools/ # RAG / Search / Excel / Word / Markdown / SQL
│ ├── mcp_server/ # MCP 工具注册与 stdio Server 模块
│ │ ├── app.py # 创建 MCP Server；默认注册 info/rag，admin 模式注册 health/warmup
│ │ ├── info_tools.py # server_info：当前可用工具与能力边界
│ │ ├── health_tools.py # check_knowledge_base，可选 admin 工具
│ │ ├── warmup_manager.py # RAG 单例预热运行时：_get_retriever / _get_reranker
│ │ ├── warmup_tools.py # RAG 单例预热启动 / 状态查询，可选 admin 工具
│ │ ├── rag_tools.py # query_financial_reports
│ │ └── responses.py # mcp_ok / mcp_err 返回结构
│ ├── memory/ # Context 配置
│ └── utils/ # LLM、Redis、token、tool helpers
├── eval/ # RAGAS 评测脚本与数据生成
├── scripts/ # PDF 检查、财务抽取、Redis 检查、历史管理
├── tests/ # Streamlit 入口与 API 回归测试
├── config.yaml # 运行时配置
├── mcp_rag_server.py # MCP stdio 薄启动入口：关闭 tracing / 日志 / create_mcp_server
├── pyproject.toml
├── requirements.txt
├── .env.example
└── .gitignore
react_agent/mcp_server/，包含 app.py、responses.py、info_tools.py、health_tools.py、warmup_manager.py、warmup_tools.py、rag_tools.py；mcp_rag_server.py 为 stdio 薄启动入口：路径锚定、Windows UTF-8 流修复、.env 加载、关闭 tracing、stderr + file 日志，不在握手阶段预热重资源；git describe 长尾；start_rag_singleton_warmup / get_rag_singleton_warmup_status，内部只加载 _get_retriever() 与 _get_reranker() 两个进程内单例；server_info 与 query_financial_reports，check_knowledge_base、start_rag_singleton_warmup、get_rag_singleton_warmup_status 仅在 MCP_EXPOSE_ADMIN_TOOLS=1 时暴露；server_info 默认只返回普通业务能力，不暴露 hidden admin tools，降低 Claude Code 等 Agent 的信息负担。_ai_tool_call_ids()，统一检测 .tool_calls 与 .invalid_tool_calls；docx_tool，支持 Word 研报生成；md_tool，支持 Markdown 输出；_doc_common.py，复用文档工具公共逻辑；requirements.txt 新增 python-docx。/api/v1 路由；MIT License
"面向金融研报问答与知识密集型场景的企业级智能体框架
Araçlar
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
ReAct RAG Agent yerel olarak stdio üzerinden çalışır.
Son kontrol: 2026-10-28. "面向金融研报问答与知识密集型场景的企业级智能体框架
