MCP操作系统演示（LP单页）
一 基于MCP（模型上下文协议）的操作系统 该系统使用 多代理非确定性工作流 其中代理通过MCP协议编排MCP工具，这些工具与不同的数据源（文件、数据库、API）交互。
📖 有关详细文档，请参阅 PRD.md
______________________________________________________________________
快速开始
1.启动数据库
docker compose up -dPostgres URL： postgres://mcp:mcp@localhost:5433/mcp_ctx
2.设置环境变量
创建一个 .env 项目根目录中的文件：
cp .env.example .env编辑 .env 根据您的配置：
# Database connection
DB_URL=postgres://mcp:mcp@localhost:5433/mcp_ctx
# Embedding Model (optional, default: Xenova/all-MiniLM-L6-v2 - local model, no API key needed)
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
# MCP Server Configuration
MCP_SERVER_URL=http://localhost:3333/mcp
# LangChain Agent Configuration (optional, for LLM content generation)
OPENAI_API_KEY=your_openai_api_key_here # Optional - enables LLM-generated content
LLM_MODEL=gpt-3.5-turbo # Optional - OpenAI model to use (default: gpt-3.5-turbo)
# All agents (IngestionAgent, KPIComputationAgent, ContentGenerationAgent) use this model
# Supported: gpt-3.5-turbo, gpt-4, gpt-4-turbo, etc.
# Workflow Configuration (optional)
DEAL_ID=00000000-0000-0000-0000-000000000001
COMPANY_NAME=Acme Software, Inc.
PERIOD_END=2025-09-30
DATA_DIR=./data注：
- 嵌入是通过以下方式生成的 局部模型 （ChromaDB）-无需API密钥！
OPENAI_API_KEY是 可选的 -仅需要LLM生成的投资论文和风险- 如果
OPENAI_API_KEY如果未设置，系统将使用回退内容 LLM_MODEL配置所有代理（IngestionAgent、KPIComputationAgent、ContentGenerationAgent）使用的OpenAI模型- 默认型号为
gpt-3.5-turbo；可以更改为gpt-4,gpt-4-turbo等等。
3.启动MCP服务器
服务器自动从以下位置加载环境变量 .env 如果存在：
npx tsx mcp-lp-tools-server.ts首次运行时，嵌入模型将自动下载（约79MB）。后续运行将使用缓存的模型。
4.运行工作流
运行非确定性多代理工作流：
source venv/bin/activate
python demo_agent_workflow.py标准模式（硬编码工具选择）：
- 代理使用预定义的逻辑来选择工具
- 对已知文件类型快速可靠
- 默认行为
动态工具发现模式：
启用动态工具发现，代理向MCP服务器查询可用工具，并使用LLM推理选择合适的工具：
python demo_agent_workflow.py --discover-tools动态模式的作用：
- 🔍 代理通过以下方式查询MCP服务器
tools/list发现可用的工具及其模式 - 🤖 LLM使用发现的工具信息（描述、参数）智能地选择工具
- 📋 基于文件类型、模式和工具功能的工具选择
- ✅ 所有工具调用仍然根据硬编码进行验证
ALLOWED_TOOLSallowlist（安全性不变） - 📊 详细记录显示了发现过程和工具选择推理
发现模式下的示例输出：
🔍 Tool Discovery Mode: ENABLED
🔍 Discovering ingestion tools from MCP server...
Found 12 total tools from server
Discovered 6 ingestion tools:
• ingest_excel: Ingest Excel (.xlsx) file...
• ingest_csv: Ingest CSV file...
🤖 Using LLM to select tools based on discovered tool schemas...
LLM tool selection results:
✓ financials_Q3_2025.xlsx → ingest_excel (priority: 1)
✓ edgar_xbrl_q3_2025.csv → ingest_edgar_xbrl (priority: 1)特征：
- ✅ 自适应重试逻辑（最多2次重试）
- ✅ 基于验证结果的条件路由
- ✅ 故障回退机制
- ✅ 透明路径日志记录
- ✅ 智能工具选择（硬编码或LLM通过
--discover-tools) - ✅ 动态工具发现（可选，支持LLM关于工具选择的推理）
5.使用Streamlit查看生成的单页
使用捆绑的Streamlit应用程序在格式化的交互式浏览器界面中查看markdown单页：
安装Streamlit（如果尚未安装）：
source venv/bin/activate
pip install streamlit运行Streamlit应用程序：
streamlit run app.py这将：
- 🌐 自动打开默认浏览器
- 📄 在以下位置显示格式化的寻呼机
output/LP_OnePager_Acme_Software_Inc_2025_09_30_agent.md - 🎨 使用适当的格式（表格、项目符号、HTML）渲染标记
- 💾 为markdown文件提供下载按钮
- 📋 在可展开的部分中显示原始markdown代码
查看其他文件：
streamlit run app.py -- /path/to/your/onepager.md访问应用程序：
- 默认URL:
http://localhost:8501 - 如果端口8501正在使用中，Streamlit将使用下一个可用端口（8502、8503等）
- URL将显示在终端输出中
特征：
- ✅ 支持HTML的格式化markdown渲染
- ✅ 可扩展源链接（单击“📊 在表格中查看来源）
- ✅ markdown文件的下载按钮
- ✅ 原始标记代码查看器
- ✅ 文件路径显示在顶部
______________________________________________________________________
🤖 多代理架构
该系统使用 多agent体系结构 由...驱动 LangGraph 有三个专业代理商：
架构流程
┌─────────────────────────────────────────────────────────┐
│ Agents (Python/LangGraph) │
│ - IngestionAgent │
│ - KPIComputationAgent │
│ - ContentGenerationAgent │
└─────────────────────────────────────────────────────────┘
↓
(MCP protocol calls via HTTP/JSON-RPC)
↓
┌─────────────────────────────────────────────────────────┐
│ MCP Server (TypeScript) │
│ - Exposes tools via MCP protocol │
│ - Session management │
│ - Tool validation │
└─────────────────────────────────────────────────────────┘
↓
(executes tools)
↓
┌─────────────────────────────────────────────────────────┐
│ MCP Tools │
│ - ingest_excel, ingest_csv, ingest_memo │
│ - compute_kpis │
│ - get_golden_facts, render_onepager_markdown │
└─────────────────────────────────────────────────────────┘
↓
(interacts with data sources)
↓
┌─────────────────────────────────────────────────────────┐
│ Data Sources │
│ - Files (Excel, CSV, TXT, MD) │
│ - PostgreSQL Database (with pgvector) │
│ - APIs (future: Stripe, Zuora, Snowflake) │
└─────────────────────────────────────────────────────────┘代理角色
1. 摄入剂
- 自动发现数据文件
- 确定最佳摄入顺序（LLM供电，可通过以下方式配置
LLM_MODEL) - 采用替代策略重新尝试失败的摄入
- 验证摄入结果
2. KPIComputingAgent
- 计算前验证数据质量
- 确定最佳KPI参数（LLM驱动，可通过配置
LLM_MODEL) - 通过验证计算KPI
- 如果计算失败，则回退到现有KPI
3. 内容生成代理
- 分析财务趋势
- 使用LLM生成投资理论和风险（可通过以下方式配置
LLM_MODEL) - 验证内容质量
- 如果生成失败，则返回默认内容
非确定性工作流
工作流使用 条件路由 以适应不同的条件：
- 摄入后：路线
continue,retry（最多2倍），或skip基于验证 - KPI计算后：路线
continue或fallback基于结果 - 内容生成后：路线
continue或fallback_content基于验证
看 PRD.md 获取详细的架构文档。
______________________________________________________________________
🛠️ 安装
Node.js依赖关系
npm installPython依赖关系
source venv/bin/activate
pip install -r requirements.txt所需的Python包：
langchain,langchain-openai,langgraph-代理框架chromadb,sentence-transformers-本地嵌入httpx,aiohttp-MCP协议的HTTP客户端pg（psycopg2二进制）-PostgreSQL客户端python-dotenv-环境变量管理
______________________________________________________________________
📖 文档
- PRD.md -完整的产品需求文档
- 系统架构 - 多代理工作流详细信息 - MCP协议使用 - 矢量搜索与语义检索 - 工具规格
- 代理/README.md -代理实现细节
______________________________________________________________________
🔍 主要特点
局部矢量嵌入
- 使用ChromaDB的内置嵌入模型(
sentence-transformers/all-MiniLM-L6-v2) - 嵌入不需要API密钥
- 完全在本地运行（约79MB型号下载）
多代理工作流
- 用于摄取、计算和内容生成的专用代理
- LLM驱动的决策
- 动态工具发现 （可选）：代理查询MCP服务器并使用LLM推理选择工具
- 自动重试和回退机制
- 每一步的质量验证
MCP协议
- 标准化JSON-RPC接口
- 会话管理
- 工具发现和验证(
tools/list方法） - 动态工具发现模式（代理向服务器查询可用工具）
- 流媒体支持
可追溯性
- 从源单元格到KPI的完整沿袭跟踪
- markdown输出中的可扩展源链接
- 所有生成工件的审计跟踪
______________________________________________________________________
📊 验证安装
检查是否计算了KPI：
SELECT k.name, kv.value, kv.unit
FROM golden_facts gf
JOIN kpi_values kv USING (kpi_value_id)
JOIN kpis k USING (kpi_id)
WHERE gf.deal_id = '00000000-0000-0000-0000-000000000001'
AND gf.status = 'approved';______________________________________________________________________
🚀 示例输出
工作流生成带有以下内容的markdown单页：
- 格式化财务指标（497万美元，28.4%等）
- 可扩展资源的投资论文部分
- 关键风险和缓解措施部分，可扩展来源
- 完整的血统可追溯性
输出示例： output/LP_OnePager_Acme_Software_Inc_2025_09_30_agent.md
______________________________________________________________________
📁 项目结构
.
├── agents/ # Multi-agent system
│ ├── ingestion_agent.py # Data ingestion agent
│ ├── kpi_agent.py # KPI computation agent
│ ├── content_agent.py # Content generation agent
│ ├── workflow_graph.py # LangGraph workflow (deterministic)
│ └── nondet_workflow_graph.py # LangGraph workflow (non-deterministic)
├── data/ # Sample data files
├── scripts/ # Utility scripts
├── sql/ # Database schema and seeds
├── mcp-lp-tools-server.ts # MCP server (TypeScript)
├── demo_agent_workflow.py # Multi-agent workflow demo (recommended)
├── prd.md # Product Requirements Document
└── README.md # This file______________________________________________________________________
🔧 故障排除
MCP服务器无法访问
确保服务器正在运行：
npx tsx mcp-lp-tools-server.tsOpenAI API关键问题
- 集
OPENAI_API_KEY在.env文件 - 或出口：
export OPENAI_API_KEY=your_key - 如果未设置，系统将使用回退内容（仍然有效！）
- 通过配置LLM模型
LLM_MODELenv为（默认值：gpt-3.5-turbo) - 所有代理都使用中配置的相同模型
LLM_MODEL
导入错误
确保安装了所有依赖项：
pip install -r requirements.txt数据库连接问题
确保Docker正在运行，数据库已启动：
docker compose up -d______________________________________________________________________
📝 许可证
有关详细信息，请参阅LICENSE文件。
______________________________________________________________________
🤝 贡献
有关架构和设计决策，请参阅PRD.md。