L2Q

<p align="center"> <img src="docs/images/logo.png" width="96" alt="销售助手 logo" /> </p> <h1 align="center">销售助手 — 从线索到报价的 MCP 服务器</h1> <p align="center"> <strong>Microsoft 365 副驾驶</strong> · FastMCP · Salesforce CRM · Streamable HTTP · Azure 容器应用 </p> 一个企业级的 <a href="https://modelcontextprotocol.io/">模型上下文协议</a> 服务器，为金融科技销售专业人员提供完整的 **从线索到报价** 工作流程，无需离开工作流程。它支持两个界面： 1. **Microsoft 365 副驾驶声明式代理** — 与 Salesforce 管道聊天，带有丰富的品牌 HTML 小部件，内置 M365 代理工具包（VS Code）和 RemoteMCP 插件。 2. **副驾驶协作者插件** — 五种协作者技能（研究简报、跟进自动化、推介演示、会议安排、管道审查包），将 Salesforce 信号转换为完成的电子邮件、Word、PowerPoint 和 Excel 文档。参见 [`cowork/`](cowork/README.md)。 --- ## 📸 截图 | 销售仪表盘 | 管道摘要 | |---|---| | [](docs/images/dashboard.png) | [](docs/images/pipeline.png) | | 账户 360（带有 M365 信号） | 机会（Kanban + 表格） | |---|---| | [](docs/images/account_360.png) | [](docs/images/opportunities.png) | | 线索 | 暗色模式 | |---|---| | [](docs/images/leads.png) | [](docs/images/dashboard-dark.png) | > 小部件带有 Microsoft 365 副驾驶的外观 — 浅色界面、签名彩虹色强调条、Segoe UI 字体 — 并自动适应 **浅色、暗色和高对比度** 主题。 --- ## ✨ 功能 | 功能 | 详情 | |---|---| | **Salesforce CRM** | 线索、账户、联系人、机会、报价、产品、活动 | | **身份验证** | 客户端凭证、OAuth 承载者直通、Entra 单一登录（可通过环境变量切换） | | **UI 小部件** | 副驾驶品牌 HTML+Skybridge 小部件绑定到 `_meta.structuredContent`，具有浅色/暗色/对比度主题 | | **M365 集成** | Teams、Outlook 的会议/电子邮件助手，通过 M365 工具服务器 | | **协作者插件** | 五种协作者技能，协调 Salesforce 数据与协作者的内置电子邮件/Word/PowerPoint/Excel | | **市场情报** | 设计用于与外部市场情报 MCP 工具配对，用于公司、宏观和市场背景 | | **合规性** | MiFID II / GDPR / FCA 合规标志和交易台审批跟踪 | | **传输** | Streamable HTTP (`/mcp`) 或 stdio | | **云** | 一键部署到 Azure 容器应用（`scripts/deploy-l2q.ps1`） | --- ## 🏗 架构 ``` Microsoft 365 副驾驶 │ ├── 声明式代理 ──► RemoteMCP 插件 │ │ └── 协作者插件 ──► remoteMcpServer 连接器 │ ▼ 销售助手 MCP 服务器（FastMCP / Streamable HTTP） 托管在 Azure 容器应用上 │ ┌─────────────────────────┼─────────────────────────┐ ▼ ▼ ▼ Salesforce REST API M365 工具服务器 市场情报 MCP （SOQL） Teams · Outlook · 日历 （外部，在代理中） 线索 / 账户 / （引用，不代理） 公司 · 宏观 · 热点 联系人 / 机会 / 报价 / 产品 ``` 每个工具返回： - **`content`** – 带有提示建议的叙述文本，以便代理可以继续自然对话。 - **`_meta.structuredContent`** – JSON 数据由 HTML+Skybridge 小部件在 `ui://widgets/<name>.html` 处消费。 大多数工具是 **只读** 的。创建/更新工具（`create_record`、`update_record`）是写入操作，需要显式确认（`confirm=true`）。 --- ## 🚀 快速入门（本地） ### 1. 先决条件 - Python 3.11+ - Salesforce Connected 应用，启用 **客户端凭证** 流 - （可选）Entra ID 应用注册，用于 SSO ### 2. 安装 ```powershell python -m venv .venv .venv\Scripts\Activate.ps1 pip install -e .[dev] ``` ### 3. 配置 ```powershell Copy-Item env\l2q.example.env env\l2q.env ``` 编辑 `env/l2q.env`: ```dotenv # 身份验证模式：client_credentials | oauth_bearer | entra_sso SF_AUTH_MODE=client_credentials SF_INSTANCE_URL=https://your-org.my.salesforce.com SF_CLIENT_ID=3MVG9... SF_CLIENT_SECRET=... SF_API_VERSION=v59.0 # 仅在 entra_sso 模式下需要 AAD_APP_CLIENT_ID= AAD_APP_TENANT_ID= ``` ### 4. 在本地运行 ```powershell scripts\run-l2q.ps1 # 或 python -m l2q.cli --transport http --host 0.0.0.0 --port 8080 ``` 服务器监听 `http://localhost:8080/mcp`。 ### 5. 使用 MCP 检查器进行测试 1. 打开 MCP 检查器 → 新建 HTTP 连接 → `http://localhost:8080/mcp` 2. 添加标头 `Authorization: Bearer <token>`（适用于 oauth_bearer / entra_sso 模式） 3. 调用 `get_sales_dashboard` 以查看您的晨间简报 --- ## ☁️ 部署到 Azure 该服务器附带一个幂等部署脚本，该脚本在 Azure 容器注册表中构建映像（云构建）并将其部署到 Azure 容器应用中。 ```powershell az login .\scripts\deploy-l2q.ps1 # 可选：.\scripts\deploy-l2q.ps1 -Location eastus -ImageTag v1.2.0 ``` 它配置/更新（所有幂等，安全重新运行）： | 资源 | 名称 | 备注 | |---|---|---| | 资源组 | `rg-l2q-dev` | | | 容器注册表 | `acrl2qdev` | 基本 SKU | | 容器应用环境 | `cae-l2q-dev` | 自动创建日志分析 | | 容器应用 | `ca-l2q-dev` | 缩放至零，0-3 个副本，0.5 vCPU / 1 GiB | 成功时，它会打印实时端点： ``` MCP 端点：https://<app>.<region>.azurecontainerapps.io/mcp 健康检查：https://<app>.<region>.azurecontainerapps.io/health ``` 在运行的应用上设置 Salesforce 凭证： ```powershell az containerapp update --name ca-l2q-dev --resource-group rg-l2q-dev ` --set-env-vars SF_AUTH_MODE=client_credentials ` SF_INSTANCE_URL=https://your-org.my.salesforce.com ` SF_CLIENT_ID=... SF_CLIENT_SECRET=... ``` ### 验证部署 ```powershell $base = "https://<app>.<region>.azurecontainerapps.io" # 健康检查 Invoke-RestMethod "$base/health" # -> {"status":"ok"} # MCP 握手 + 工具列表 $h = @{ "Content-Type"="application/json"; "Accept"="application/json, text/event-stream" } Invoke-WebRequest "$base/mcp" -Method Post -Headers $h ` -Body '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' ``` 健康服务器响应 `initialize`，带有 `serverInfo.name = "l2q"`，并提供完整的 Salesforce 工具目录（58 个工具）。 --- ## 🛠 工具参考 ### 线索管理 | 工具 | 描述 | |---|---| | `search_leads` | 按名称、公司、状态或行业搜索 | | `get_lead` | 完整的线索详情 | | `get_recent_leads` | 所有开放的线索（最近的优先） | | `get_leads_by_status` | 按状态筛选（新建 / 进行中 / 合格） | ### 账户管理 | 工具 | 描述 | |---|---| | `search_accounts` | 搜索金融机构账户 | | `get_account` | 完整的账户详情 | | `get_account_contacts` | 账户的联系人 | | `get_account_opportunities` | 账户的机会 | ### 联系人管理 | 工具 | 描述 | |---|---| | `search_contacts` | 按姓名、账户或职称搜索 | | `get_contact` | 完整的联系人资料 | | `get_contact_activity_history` | 通话 / 电子邮件 / 会议历史 | ### 机会管理 | 工具 | 描述 | |---|---| | `search_opportunities` | 按阶段、价值、账户筛选 | | `get_opportunity` | 完整的机会详情 | | `get_open_opportunities` | 开放的管道机会 | | `get_opportunities_by_stage` | 特定阶段的交易 | | `get_pipeline_summary` | 按阶段汇总管道，附总计 | ### 报价管理 | 工具 | 描述 | |---|---| | `search_quotes` | 查找报价名称或状态 | | `get_quote` | 完整的报价，附定价 | | `get_quote_pdf_package` | 检索生成的报价 PDF 工件/下载 URL，用于电子邮件工作流 | | `get_quote_products` | 报价的商品 | | `get_opportunity_quotes` | 机会的所有报价 | ### 产品目录 | 工具 | 描述 | |---|---| | `search_products` | 搜索产品目录 | | `get_product` | 产品详情和列表价格 | ### 活动和任务 | 工具 | 描述 | |---|---| | `get_activity_timeline` | 账户/机会/联系人的时间线 | | `get_open_tasks` | 按优先级排序的开放任务 | ### 创建和更新工作流（先草稿） | 工具 | 描述 | |---|---| | `draft_create_record` | 为 account/contact/case/opportunity/task/quote/lead/event 构建预创建草稿表单 | | `create_record` | 在 Salesforce 中创建记录（显式确认后） | | `get_record_for_update` | 加载单个记录为可编辑的更新草稿 | | `update_record` | 在 Salesforce 中应用更新（显式确认后） | | `get_task` / `get_event` / `get_case` | 检索单个对象以更新流程 | ### 引导实体解析和查找 | 工具 | 描述 | |---|---| | `search_reference_records` | 为可搜索的选取下拉菜单搜索账户/联系人/机会/线索/案件 | ### 报告 | 工具 | 描述 | |---|---| | `run_salesforce_report` | 运行 Salesforce 报告并在小部件 UI 中呈现表格结果 | ### 合规性和交易台 | 工具 | 描述 | |---|---| | `get_compliance_flags` | MiFID II / GDPR / FCA 标志 | | `get_deal_desk_status` | 审批流程状态 | ### M365 集成助手 | 工具 | 描述 | |---|---| | `prepare_meeting_agenda` | Salesforce 数据的 Teams 会议议程 | | `prepare_email_summary` | 专业电子邮件/提案草稿 | | `get_sales_dashboard` | 晨间简报：管道 + 任务 + 线索 | | `capture_lead_from_email` | 从 Outlook 电子邮件上下文构建线索草稿 | > **Teams / Outlook / 日历**：直接从您的 Copilot 声明式代理使用 [M365 工具服务器](https://learn.microsoft.com/en-us/microsoft-agent-365/tooling-servers-overview) 来安排会议和发送电子邮件。 --- ## 🎨 UI 小部件 HTML+Skybridge 小部件注册为 MCP 资源，位于 `ui://widgets/<name>.html`： | 小部件 | 用途 | |---|---| | `dashboard.html` | 销售仪表盘 – 管道 + 任务 + 线索 | | `leads.html` | 线索列表，附状态筛选 | | `opportunities.html` | Kanban + 表格视图 | | `quotes.html` | 报价卡 + 商品 | | `accounts.html` | 账户卡 + 产品目录 | | `contacts.html` | 联系人卡 + 详细资料 | | `pipeline.html` | 漏斗 + 堆叠条形图 | | `activities.html` | 时间线 + 会议/电子邮件查看器 | 每个小部件从 MCP `_meta` 通过 Skybridge `postMessage` 协议读取 `structuredContent`。 所有小部件现在默认为 **紧凑模式** （适用于内联聊天 iframe），并包含一个 **右上角最大化/恢复按钮**，以便用户根据需要扩展到全高工作模式。 创建/更新表单现在支持 **搜索和选择查找流程**，用于关系 ID（`AccountId`、`ContactId`、`WhoId`、`WhatId`、`OpportunityId` 和机会 `PrimaryContactId`），以避免手动输入 ID。 ### 引导创建流程的提示模式 - **会议驱动的创建：` - `我想为与 Jim 的会议创建一个机会` - 代理流程：运行 `search_reference_records` 查找账户/联系人 → 打开 `opportunity_form.html`，并带有预填充的数据和候选查找。 - **空白创建：` - `创建一个新的机会` - 代理流程：运行 `draft_create_record object_type=opportunity` → 在表单中使用 `search_reference_records` 选择账户/联系人之前创建。 ### 提示库 – L2Q 生命周期 + 高级自动化（带有上下文期望） 提示下面编写适用于 Copilot 声明式代理，可以： - 读取 **电子邮件**、**Teams 会议摘要** 和 **Teams 消息**， - 使用此 **L2Q MCP 服务器**， - 使用外部 **市场情报 MCP** 获取公司/市场上下文。 当提示引用“此交易/账户/线索”时，预期的解析流程： 1. 从当前工件上下文（电子邮件/线程/会议）解析实体， 2. 如果不明确，显示候选并要求用户选择， 3. 继续进行更深入的分析/草稿。 #### L2Q 阶段 + 生命周期报告的 6 个提示 | 标题 | 提示 | 上下源和预期流程 | |---|---|---| | **线索摄入快照** | 从最近的客户端电子邮件、Teams 消息和会议摘要中生成线索摄入摘要，包含资格信号、紧急程度和推荐的下一步行动。 | 工件引导：从当前对话工件开始；仅在多个公司被引用时询问实体确认。 | | **资格决定** | 对于线索 `[lead name or ID]`，评估资格/培养/不合格，并使用通信证据以及外部公司和市场上下文进行说明。 | 实体引导：如果未提供 ID，则按名称解析并要求用户确认最佳匹配。 | | **机会准备检查** | 对于机会 `[name or ID]`，评估阶段准备情况、缺少所需数据、利益相关者空白以及在阶段推进之前必须完成的内容。 | 实体引导：如果未指定，短列出活跃的机会，让用户选择一个。 | | **报价准备审查** | 对于机会 `[name or ID]`，使用最近的客户端交互和外部市场/公司信号评估报价准备情况，然后列出阻塞器和下一步骤。 | 实体引导：需要选定的机会，然后结合内部通信上下文 + 外部情报。 | | **关闭计划和提交信心** | 对于机会 `[name or ID]`，创建带有里程碑、所有者、信心驱动因素和顶级风险的关闭计划。 | 实体引导：一个选定的机会；返回计划和信心叙述。 | | **智能会议准备包** | 对于账户 `[name]`，创建一个会议准备包，包含目标、谈话要点、可能的异议和基于最新交互的市场感知响应。 | 账户引导：解析账户，然后拉取工件上下文 + 外部更新。 | | **会议后自动编排** | 从此会议总结中，生成后续行动、业主分配、时间线更新和精致的客户后续消息，符合交易策略。 | 工件引导：从当前会议总结开始；如果存在多个链接交易，用户被要求选择目标交易。 | | **续期风险和扩展计划** | 对于账户 `[name]`，创建续期风险评估和扩展计划，使用关系信号、参与模式和外部展望。 | 账户引导，多交易汇总（如果适用）；返回 30/60/90 计划。 | | **董事会准备的管道包** | 为 `[portfolio/team/region]` 构建一个董事会就绪的管道包，包含信心叙述、集中度风险和推荐的管理干预措施。 | 投资组合引导：询问范围（如果未提供），然后编写包叙述和优先级。 | #### 6 个提示，用于高价值、复杂的自动化 | 标题 | 提示 | 上下文源和预期流程 | |---|---|---| | **高风险交易营救** | 确定我的投资组合中最有风险的开放机会，并使用通信信号和外部市场/公司背景生成一个为期两周的营救计划。 | 投资组合优先，然后钻取：建议最有风险的交易，确认，然后生成营救行动。 | | **高管预测叙述** | 构建本周的高管预测叙述，结合管道移动、通信证据和外部市场发展。 | 投资组合引导的综合分析，用于领导层报告；无需单个实体选择。 | | **智能会议准备包** | 对于账户 `[name]`，创建一个会议准备包，包含目标、谈话要点、可能的异议和基于最新交互的市场感知响应的市场感知响应。 | 账户引导：解析账户，然后拉取工件上下文 + 外部更新。 | | **会议后自动编排** | 从此会议总结中，生成后续行动、业主分配、时间线更新和精致的客户后续消息，符合交易策略。 | 工件引导：从当前会议总结开始；如果存在多个链接交易，用户被要求选择目标交易。 | | **续期风险和扩展计划** | 对于账户 `[name]`，创建续期风险评估和扩展计划，使用关系信号、参与模式和外部展望。 | 账户引导，多交易汇总（如果适用）；返回 30/60/90 计划。 | | **董事会就绪的管道包** | 为 `[portfolio/team/region]` 构建一个董事会就绪的管道包，包含信心叙述、集中度风险和推荐的管理干预措施。 | 投资组合引导：询问范围（如果未提供），然后编写包叙述和优先级。 | ### 本地小部件预览，附带样本数据 使用预览脚本在浏览器中渲染所有小部件，无需运行 MCP 工具： ```powershell scripts\run-widget-preview.ps1 ``` 然后打开 `http://127.0.0.1:8090/` 并选择任意小部件页面。 您还可以选择自定义主机/端口： ```powershell scripts\run-widget-preview.ps1 -HostName 127.0.0.1 -Port 8091 ``` --- ## 🔐 身份验证模式 在您的环境文件中设置 `SF_AUTH_MODE`： | 模式 | 工作原理 | |---|---| | `client_credentials` | 服务器使用 `SF_CLIENT_ID` + `SF_CLIENT_SECRET` （连接应用）获取 Salesforce 令牌 | | `oauth_bearer` | 调用者将 Salesforce OAuth 令牌放入 `Authorization: Bearer …` 头部 – 服务器转发它 | | `entra_sso` | 调用者传递微软 Entra ID JWT – 服务器验证后转发到 Salesforce | --- ## 🐳 Docker ```bash docker build -t l2q-mcp . docker run -p 8080:8080 \ -e SF_AUTH_MODE=client_credentials \ -e SF_INSTANCE_URL=https://your-org.my.salesforce.com \ -e SF_CLIENT_ID=... \ -e SF_CLIENT_SECRET=... \ l2q-mcp ``` 服务器在 `GET /health` 处暴露了一个 `/health` 端点，返回 `{"status": "ok"}` — 适用于容器编排的存活/就绪探测。 --- ## 🧪 测试 ```bash pip install -e . python -m pytest tests/ -v ``` --- ## 📋 M365 Copilot 声明式代理设置 1. 使用 M365 代理工具包在 VS Code 中创建一个新的声明式代理。 2. 添加带有端点 `https://<your-server>/mcp` 的 **RemoteMCP** 插件。 3. 为 Teams、Outlook 和 Calendar 添加 [M365 工具服务器](https://learn.microsoft.com/en-us/microsoft-agent-365/tooling-servers-overview)。 4. （可选）为同一代理添加外部 **市场情报 MCP** 插件以获取外部公司/市场上下文。 5. 在 RemoteMCP 插件配置中设置 `Authorization: Bearer <Entra token>`。 --- ## 🤝 Copilot Cowork 插件 [`cowork/`](cowork/README.md) 文件夹包含一个 Copilot Cowork 插件， 它重用同一个 MCP 服务器作为 `remoteMcpServer` 连接器。哪里有声明式代理是 **聊天** 界面，用于快速查找， 哪里有 Cowork 插件是 **协同工作** 界面，用于深入工作 — 它生成完成后的电子邮件、Word、 PowerPoint 和 Excel 文档。它提供了两种金融科技人物形象的五项技能： | 技能 | 人物 | 内置界面 | |---|---|---| | `account-research-brief` | 账户执行官 | Word, 电子邮件 | | `deal-followup-automation` | 账户执行官 | 电子邮件, Word | | `pitch-deck-builder` | 账户执行官 | PowerPoint | | `client-meeting-scheduler` | 账户执行官 | 日历, 电子邮件 | | `pipeline-review-pack` | 销售经理 | Excel, PowerPoint, 电子邮件 | 使用 [`cowork/scripts/package.ps1`](cowork/scripts/package.ps1) 打包它并 侧载 `sales-assistant-cowork.zip`。参见 [`cowork/README.md`](cowork/README.md) 了解完整的故事、连接器身份验证和打包步骤。 --- ## 🏢 关于 销售助手是一个微软 365 副驾驶可扩展性示例，用于 **金融科技 B2B 销售** — 为管理大型复杂交易与 金融机构客户在高度监管的环境（MiFID II / GDPR / FCA）中的专业人士而构建。它演示了一个 MCP 服务器， 为基于 Salesforce 的实时数据提供动力，同时支持声明式代理和 Copilot Cowork 插件。