MCPAppsDemo

# MCP 应用演示 本仓库包含两个 C# 模型上下文协议（MCP）演示： - `Sample/`：最小的可能的 stdio MCP 服务器，适合学习基础知识。 - `src/GroceryInventory.Api/`：一个更丰富的 HTTP MCP 服务器，包含用于杂货库存场景的 REST API，包括工具、提示、资源、补全、通知、日志记录、诱导、采样、根和 MCP 应用仪表盘。 主要目标是向同事和客户展示 MCP 在成熟度曲线上的表现： - 从确定性的仅工具服务器开始， - 进入结构化提示和资源， - 然后分层添加高级客户端中介功能，如采样、诱导、日志记录、通知和交互式 UI。 ## 为什么这个仓库值得分享 本仓库在以下情况下很有用： - 向客户或内部团队展示如何通过 MCP 公开业务数据和操作，而无需创建新的代理框架， - 当 MCP 工具比原始提示工程更合适时， - 为什么提示、资源和补全使代理体验更可靠， - 如何将确定性操作与模型驱动推理分开， - 当客户端可以渲染 HTML UI 时，MCP 应用体验是什么样的， - 如何通过 REST 和 MCP 提供相同的领域。 ## 仓库地图 | 路径 | 它是什么 | 何时使用 | | --- | --- | --- | | `Sample/` | 带有随机数工具的最小 stdio MCP 服务器 | 当您需要最快的可能的上线示例时 | | `src/GroceryInventory.Api/` | 使用 HTTP 传输的主要杂货库存演示 | 当您想要具有多个 MCP 功能的现实业务场景时 | | `src/GroceryInventory.Api/McpTools/` | 工具、提示、资源、补全、采样、诱导和根的实现 | 在扩展或审查 MCP 表面时 | | `src/GroceryInventory.Api/McpApp/` | 基于 Vite 的单文件仪表盘 UI 包 | 在演示 MCP 应用或聊天相邻的可视化体验时 | | `src/GroceryInventory.Api/GroceryMcpTools.http` | 用于 MCP 手动测试的端到端 JSON-RPC 请求集合 | 当您想要直接检查协议调用时 | | `src/GroceryInventory.Api/GroceryRestEndpoints.http` | HTTP API 的 REST 请求集合 | 在比较 REST 与 MCP 或测试确定性 API 时 | | `.vscode/mcp.json` | VS Code MCP 服务器注册 | 在将正在运行的服务器连接到 Copilot Chat 时 | ## 架构概览 主要演示故意通过两种方式公开相同的杂货领域： - 用于传统应用集成的 REST API。 - 用于 AI 辅助工作流、交互式聊天工具、提示模板、资源和 UI 的 MCP 服务器。 这种分离使得向客户解释 MCP 不是其应用程序后端的替代品变得更加容易。 它是在其领域模型之上分层的高聚焦代理接口。 ## 先决条件 对于完整的杂货演示： - .NET 10 SDK - Node.js 20+ 和 npm - 带有 Copilot Chat 的 VS Code（如果您想从聊天中使用 MCP 服务器） - 可选：VS Code 的 REST Client 扩展（如果您想直接运行 `.http` 文件） 对于最小样本： - .NET 10 SDK ## 快速入门 ### 运行杂货库存演示 从仓库根目录： ```powershell dotnet restore .\MCPAppsDemo.slnx dotnet run --project .\src\GroceryInventory.Api ``` 发生了什么： - 应用程序启动了一个 HTTP API 和一个 HTTP MCP 端点。 - MCP 端点在 `http://localhost:5256/mcp` 处可用。 - REST 根探测在 `http://localhost:5256/` 处可用。 - OpenAPI 在开发环境中于 `http://localhost:5256/openapi/v1.json` 处可用。 - `.csproj` 在 .NET 构建之前自动从 `src/GroceryInventory.Api/McpApp/` 构建仪表盘包。 如果您需要跳过仪表盘构建，因为 Node 未安装： ```powershell dotnet run --project .\src\GroceryInventory.Api -p:BuildMcpApp=false ``` 在此模式下，服务器仍然运行，但 MCP 应用仪表盘资源将显示一个占位符，除非 `McpApp/dist/index.html` 已经存在。 ### 运行最小样本 ```powershell dotnet run --project .\Sample ``` 在您想要最小的可能教学样本之前引入更丰富的杂货场景时使用此命令。 ## 从 VS Code Copilot Chat 连接 此仓库已经包含 `.vscode/mcp.json`: ```json { "servers": { "Grocery MCP Demo": { "type": "http", "url": "http://localhost:5256/mcp" } } } ``` 如何使用它： 1. 使用 `dotnet run --project .\src\GroceryInventory.Api` 启动杂货 API。 2. 在 VS Code 中打开工作区。 3. 确保在 Copilot Chat 中启用了 MCP 服务器。 4. 要求 Copilot 使用服务器，例如： - `显示商店库存仪表盘。` - `列出商店 2 的低库存商品。` - `分析 Riverbend Foods 库存健康状况。` - `用通俗语言解释收缩。` 客户为什么喜欢此流程： - 它将 MCP 配置保留在工作区本地。 - 它演示了业务工具在聊天 UI 中如何感觉原生。 - 它降低了非开发人员不想编写原始 JSON-RPC 请求的门槛。 ## 使用 HTTP 集合进行手动 MCP 测试 打开 `src/GroceryInventory.Api/GroceryMcpTools.http` 并按顺序运行请求。 首次握手是： 1. `initialize` 2. `notifications/initialized` 3. 任意 `tools/list`、`resources/list`、`prompts/list` 或 `tools/call` 请求 此文件在以下情况下很有用： - 检查确切的 JSON-RPC 有效载荷， - 使用 `Mcp-Session-Id` 演示会话处理， - 在隔离状态下测试各个 MCP 功能， - 比较通用 REST 客户端和更丰富的 MCP 感知主机之间的区别。 重要限制： - `.http` 文件表现得像一个普通客户端，不会宣传诸如 `sampling`、`elicitation` 或 `roots` 等高级客户端功能。 - 这意味着诸如 `recommend_restocks`、`plan_bulk_restock` 和 `list_client_roots` 之类的请求对于演示能力协商很有用，但并不总是用于演示顺利的路径。 ## REST API 测试 杂货项目也是一个标准的 ASP.NET Core API。 代表性路由： - `/api/categories` - `/api/suppliers` - `/api/stores` - `/api/products` - `/api/inventory/stores/{storeId}` - `/api/inventory/products/{productId}` - `/api/inventory/stores/{storeId}/products/{productId}` - `/api/inventory/low-stock` 此双表面设计对客户来说很有价值，因为它使边界清晰： - REST 仍然是传统的应用契约。 - MCP 是面向 AI 的契约，它封装了代理和 copilots 最有用的任务。 ## 功能概述 | 功能 | 主要入口点 | 如何使用它 | 客户何时获得价值 | 为什么它很重要 | | --- | --- | --- | --- | --- | | 引用数据查找 | `get_categories`、`get_suppliers`、`get_stores`、`get_products` | 直接从聊天或 JSON-RPC 调用工具 | 当代理必须在真实的目录、商店或供应商数据中定位时 | 可靠的确定性读取减少了幻觉和糟糕的后续行动 | | 库存状态和突变 | `get_inventory`、`set_inventory`、`adjust_stock`、`get_low_stock` | 使用工具读取库存、更新计数或识别短缺 | 当工作流需要操作行动，而不仅仅是分析时 | 将聊天从被动的问答转变为有用的业务操作 | | MCP 应用仪表盘 | `show_store_inventory_dashboard` 加 `ui://grocery/store-dashboard.html` | 从 MCP 应用感知的客户端调用工具 | 当用户需要可视化的多商店库存视图时 | 比原始 JSON 更容易让人类验证和行动 | | 提示模板 | `prompts/list`、`prompts/get` | 发现提示，然后用类型化参数请求提示消息 | 当您想要可重用的 AI 任务时 | 减少提示工程开销并标准化结果 | | 资源模板 | `resources/templates/list`、`resources/read` | 发现 URI 模板，然后用具体 ID 替换 | 当您需要动态的只读上下文和稳定的 URI 时 | 保持频繁请求业务视图的简单和可发现 | | 参数补全 | `completion/complete` | 使用提示或资源引用加上部分输入请求建议 | 当用户输入 ID 或已知术语时 | 改善 UX 并减少无效参数错误 | | 基于采样的推理 | `recommend_restocks` | 从支持 `sampling` 并具有连接模型的客户端调用 | 当确定性规则不够，需要判断时 | 让客户重用客户端的模型访问，而不是将模型访问构建到服务器中 | | 基于诱导的规划 | `plan_bulk_restock` | 从支持 `elicitation` 的客户端调用 | 当服务器应该在采取行动之前向人类询问预算、范围或偏好时 | 人类在环中的规划更安全、更可控 | | 通知和日志记录 | `resources/updated`、`logging/setLevel`、SSE | 监听事件流并选择日志级别 | 当客户端需要实时更新和可追溯性时 | 启用反应式 UX 和更好的调试 | | 根 | `list_client_roots` | 从宣传 `roots` 的客户端调用 | 当服务器行为应感知工作区或项目上下文时 | 帮助未来工具保持在用户的实际工作集范围内 | | 最小启动服务器 | `Sample/` | 运行_stdio_样本并调用`get_random_number` | 当受众是 MCP 新手，应从小开始时 | 最低摩擦教学样本，介绍高级模式之前 | ## 详细功能指南 ### 1. 引用数据查找工具 工具： - `get_categories` - `get_suppliers` - `get_stores` - `get_products` 如何使用： - 向 Copilot 提出领域问题，如 `列出供应商` 或 `显示类别 2 中的产品`。 - 或使用工具名称和可选过滤器（如 `id`、`categoryId` 或 `supplierId`）调用 `tools/call`。 何时使用： - 在需要受信任的业务上下文的任何工作流开始时。 - 当客户端需要在调用突变工具或资源模板之前解析 ID 时。 - 当您想要一个紧凑的工具表面，而不是公开许多小而重叠的端点到模型时。 为什么客户获得价值： - 查找工具为模型提供结构化事实，而不是迫使它推断领域状态。 - 它们是确定性和廉价的，因此非常适合高频定位。 - 它们展示了如何在不使工具设计过于复杂的情况下，将普通的业务线数据封装在 MCP 中。 良好的客户场景： - 需要商店和供应商元数据的商店运营 Copilot。 - 按类别或供应商过滤产品的规划助手。 - 需要有关位置、供应商或 SKU 的快速答案的支持代理。 ### 2. 库存状态和突变工具 工具： - `get_inventory` - `set_inventory` - `adjust_stock` - `get_low_stock` 如何使用： - 使用 `get_inventory` 进行全链、每店、每产品或单行库存读取。 - 使用 `set_inventory` 创建或替换具有绝对值的库存记录。 - 使用 `adjust_stock` 进行相对更改，如销售、减损或补货。 - 使用 `get_low_stock` 查找处于或低于阈值的行，可选地限定为一个商店。 何时使用： - 当您需要模型执行操作任务而不是仅仅解释数据时。 - 当您想要模拟或自动化接收、销售调整或补货时。 - 当低库存检测应确定且快速时。 为什么客户获得价值： - 这是许多客户关心的核心模式：通过工具契约公开安全的业务操作。 - 它演示了绝对更新和相对调整之间的区别。 - 它使库存工作流可审计和可重复。 良好的客户场景： - 商店经理在盘点后调整库存。 - 损失预防或减少分析流程，扣除已知损失。 - 自动低库存监控，馈送下游规划或订购。 重要注意： - 演示使用 `SeedData.cs` 中的种子数据初始化的内存单例存储。 - 更改仅在运行时过程中持续。 - 重新启动应用程序会重置数据集。 ### 3. MCP 应用仪表盘 工具和资源： - `show_store_inventory_dashboard` - `ui://grocery/store-dashboard.html` 如何使用： - 从 MCP 应用感知的客户端调用 `show_store_inventory_dashboard`。 - 工具返回结构化快照数据和 `_meta.ui.resourceUri`，告诉客户端要渲染哪个 HTML 资源。 - HTML 包从 `src/GroceryInventory.Api/McpApp/dist/index.html` 提供。 何时使用： - 当原始 JSON 不够，用户需要可视化的库存审查时。 - 当您希望人类比较商店、扫描 KPI 和快速验证异常值时。 - 当演示 MCP 可以将工具与 UI 配对，而不仅仅是文本时。 为什么客户获得价值： - 可视化验证建立了对工具输出的信任。 - 仪表盘减少了非开发人员操作用户的认知负担。 - 它显示了一条从工具输出到更丰富的任务导向接口的实用路径。 良好的客户场景： - 每日库存汇报会。 - 区经理查看多个商店。 - 人工干预审批工具建议。 ### 4. 提示模板 提示： - `analyze_store_performance` - `draft_supplier_order` - `explain_inventory_term` 如何使用： - 调用 `prompts/list` 以发现可用的提示模板。 - 调用 `prompts/get` 并带有提示名称和类型参数。 - 服务器返回准备好让客户端发送给其 LLM 的提示消息。 何时使用： - 当您有具有稳定结构的重复 AI 任务时。 - 当您想要打包特定于领域的分析或写作任务，而无需构建新工具时。 - 当业务用户不应该知道确切的提示词时。 为什么客户获得价值： - 提示模板提供一致性，而无需硬编码单个模型响应。 - 它们将领域上下文保持在服务器端，而不是在客户端之间分散提示。 - 它们适用于可重用的工作流，例如商店审查、草稿采购订单或词汇解释。 良好的客户场景： - 类别经理希望在不同地点获得一致的商店健康分析。 - 采购助理需要根据当前短缺情况提供供应商订单草稿。 - 一线员工需要对库存术语进行通俗解释。 ### 5. 资源模板 模板： - `inventory://stores/{storeId}/summary` - `inventory://products/{productId}/details` 如何使用： - 调用 `resources/templates/list` 以发现参数化资源。 - 在 URI 模板中替换真实值。 - 使用具体 URI 调用 `resources/read`，例如 `inventory://stores/3/summary`。 何时使用： - 当客户端需要结构化的只读上下文，应表现得像可寻址内容。 - 当您想要用于重复访问、缓存或链接的稳定 URI 时。 - 当工具调用对于只读操作来说太重时。 为什么客户获得价值： - 资源模板使动态业务视图可发现，而无需大量自定义工具。 - 它们与希望按需浏览或获取参考资料的客户端配合良好。 - 它们特别适用于摘要、详情页和可重用上下文有效载荷。 良好的客户场景： - Copilot 加载商店摘要，然后起草操作更新。 - 产品助手为一个 SKU 获取全链库存详情。 - 仪表盘体验深入链接到基于资源的详情视图。 ### 6. 参数补全 补全入口点： - `completion/complete` 如何使用： - 提供描述提示或资源模板的 `ref`。 - 提供参数名称和到目前为止输入的部分值。 - 服务器返回过滤后的建议。 - 一些参数，例如 `urgencyLevel`，从提示定义上的 `[AllowedValues]` 自动提供。 何时使用： - 当用户输入商店 ID、产品 ID、供应商 ID 或已知领域术语时。 - 当您正在构建一个应该指导正确参数输入的客户端 UI 时。 - 当您想要减少由拼写错误或未知值引起的错误调用时。 为什么客户获得价值： - 补全是一个简单但影响很大的可用性功能。 - 它们在不要求大量自定义 UI 的情况下减少了错误率。 - 它们使提示和资源调用感觉更像应用程序，而不是手动协议工作。 良好的客户场景： - 聊天中的提示表单。 - 带有内联搜索的资源浏览器。 - 为商店操作员提供引导式数据录入体验。 ### 7. 基于采样的补货推荐 工具： - `recommend_restocks` 使用方法： - 从支持 `sampling` 功能的 MCP 客户端调用该工具。 - 确保客户端已连接模型。 - 可选地传递 `storeId` 以限定推荐范围，并传递 `maxRecommendations` 以限制输入大小。 - 服务器收集低库存上下文，然后要求客户端模型优先考虑并确定推荐订单的大小。 何时使用： - 当确定性重订规则不足时。 - 当紧急程度应反映易腐性、单位价格暴露和低于阈值的深度等权衡时。 - 当您想要模型推理但不希望在服务器中托管模型凭证时。 客户价值： - 这是企业已经在客户端层面管理模型访问的现实模式。 - 服务器拥有业务上下文；客户端拥有模型访问权限。 - 它允许客户在不围绕 LLM 重写后端的情況下，为现有的确定性系统添加推理。 良好的客户场景： - 优先考虑哪些低库存商品值得当天关注。 - 为采购或商店运营团队生成排名列表。 - 将模型驱动的优先级与简单的阈值排序进行比较。 重要注意事项： - 通用 REST 客户端将无法满足 `sampling/createMessage`。 - 如果客户端报告“模型未连接”，请在主机中连接或选择模型。 - 服务器可以发送模型提示，但最终的模型可用性由客户端主机控制。 ### 8. 基于诱导的批量补货规划 工具： - `plan_bulk_restock` 使用方法： - 从支持 `elicitation` 的客户端调用该工具。 - 服务器呈现一个表单，询问商店、预算、类别以及是否包括接近阈值的商品。 - 用户响应后，服务器会根据所选预算构建过滤后的补货计划。 何时使用： - 当用户（而非模型）应提供规划前的操作约束时。 - 当您需要预算感知或类别范围规划时。 - 当您想要一种更安全、更适合审批的替代自由表单代理操作时。 客户价值： - 诱导是企业工作流程中人工干预的强大模式。 - 它让用户控制业务约束。 - 它将聊天转变为引导式规划体验，无需单独的网络表单。 良好的客户场景： - 商店经理规划每周的面包和乳制品补货，预算固定。 - 采购团队在批准订单前探索各类别之间的权衡。 - 任何可接受的答案取决于用户提供的偏好的场景。 ### 9. 通知和日志记录 相关功能： - `resources/updated` 通知库存变更后 - `logging/setLevel` - 通过 `Accept: application/json, text/event-stream` 支持 SSE 的响应 使用方法： - 通过在 `Accept` 头中包含 `text/event-stream` 来选择流式传输。 - 调用 `logging/setLevel` 请求信息级日志。 - 使用 `set_inventory` 或 `adjust_stock` 变更库存，并监听 `resources/updated` 通知。 何时使用： - 当客户端需要自动刷新 UI 以适应状态变更时。 - 当您希望了解工具执行进度或服务器端决策时。 - 当构建更丰富的客户端时，它们的行为更像反应式应用程序，而不是一次性 RPC 调用程序。 客户价值： - 通知减少了轮询和过时的 UI。 - 日志记录为操作员和开发人员提供了对服务器正在执行的操作的洞察。 - 当客户从原型工具转向操作体验时，这些模式变得很重要。 良好的客户场景： - 库存调整后的实时仪表板。 - 需要清晰事件跟踪的管理工具。 - 调试采样或批量规划等高级功能。 ### 10. 根目录 工具： - `list_client_roots` 使用方法： - 从支持 `roots` 功能的客户端调用它。 - 服务器请求客户端的工作区根目录，并以可读的摘要返回它们。 何时使用： - 当服务器应根据用户的活动仓库或文件夹量身定制行为时。 - 当未来工具应限制其在相关工作区内而不是猜测上下文时。 客户价值： - 根目录是一种干净的方式，可以让服务器行为与用户的实际工作集保持一致。 - 它们在服务器可能对文档、仓库或本地工件进行操作时特别有用。 良好的客户场景： - 仓库感知的代码助手。 - 多项目工作区，其中范围很重要。 - 仅在批准的目录内运行的治理敏感工具。 ### 11. 最小样本服务器 项目： - `Sample/` 使用方法： - 运行 `dotnet run --project .\Sample`。 - 将其配置为_stdio_ MCP 服务器。 - 请求随机数以确认工具路径正常工作。 何时使用： - 首次向客户介绍 MCP 时。 - 在讨论提示、资源或 UI 之前，您需要一个低噪音的启动器。 - 讲解传输线路和领域逻辑之间的区别。 客户价值： - 它将 MCP 精简到基本要素。 - 它使新团队的入职更快。 - 它为客户在评估更丰富的示例之前提供了一个干净的基准。 ## 建议的演示流程 ### 流程 1：确定性操作助手 在观众希望首先看到可靠、安全的工具调用时使用此流程。 1. 列出商店或产品。 2. 读取某个商店的库存。 3. 查询低库存商品。 4. 调整库存以适应销售或补货。 5. 显示低库存和资源摘要立即更改。 为什么它效果好： - 它展示了值得信赖的读取和写入操作。 - 它避免了早期在对话中对模型依赖的担忧。 ### 流程 2：引导式分析和写作 在观众关心可重复的 AI 工作流程时使用此流程。 1. 调用 `prompts/list`。 2. 使用 `analyze_store_performance` 或 `draft_supplier_order`。 3. 显示提示参数的补全。 4. 解释服务器如何为模型封装领域上下文。 为什么它效果好： - 它展示了 MCP 如何在无需自定义应用开发的情况下标准化基于提示的工作。 ### 流程 3：人工干预的规划 在观众希望审批环节和预算控制时使用此流程。 1. 调用 `plan_bulk_restock`。 2. 让用户选择商店、预算和类别。 3. 查看返回的计划。 为什么它效果好： - 它展示了企业安全交互流程的实用路径。 ### 流程 4：模型辅助优先级 在观众希望看到模型推理增加价值的地方使用此流程。 1. 运行 `get_low_stock` 以显示原始的确定性短缺列表。 2. 从支持采样的主机调用 `recommend_restocks`。 3. 将排名推荐与原始低库存行进行比较。 为什么它效果好： - 它突出了阈值检测和业务优先级之间的差异。 ## 扩展演示的关键文件 | 文件 | 为什么重要 | | --- | --- | | `src/GroceryInventory.Api/Program.cs` | 连接 OpenAPI、HTTP 传输、工具、资源、提示、补全和 `/mcp` 端点 | | `src/GroceryInventory.Api/McpTools/Tools.cs` | 核心确定性 MCP 工具 | | `src/GroceryInventory.Api/McpTools/DashboardTools.cs` | MCP 应用仪表盘工具和响应形状 | | `src/GroceryInventory.Api/McpApp/GroceryDashboardResource.cs` | UI 资源注册和包加载 | | `src/GroceryInventory.Api/McpTools/Prompts.cs` | 提示模板定义 | | `src/GroceryInventory.Api/McpTools/ResourceTemplates.cs` | 动态资源模板 | | `src/GroceryInventory.Api/McpTools/Completions.cs` | 补全处理程序实现 | | `src/GroceryInventory.Api/McpTools/RestockRecommendationTools.cs` | 基于采样的推荐流程 | | `src/GroceryInventory.Api/McpTools/ElicitationTools.cs` | 基于诱导的表单和规划流程 | | `src/GroceryInventory.Api/McpTools/RootsTools.cs` | 根目录能力示例 | | `src/GroceryInventory.Api/Services/InMemoryInventoryService.cs` | 内存持久性和变更行为 | | `src/GroceryInventory.Api/Data/SeedData.cs` | 整个演示中使用的可重复样本数据 | | `src/GroceryInventory.Api/GroceryMcpTools.http` | 手动 MCP 协议演练 | ## 故障排除 ### 仪表板显示包丢失 构建 MCP 应用包： ```powershell Set-Location .\src\GroceryInventory.Api\McpApp npm install npm run build ``` 然后重启 API。 ### `recommend_restocks` 失败 检查这些条件： - 客户端必须支持 `sampling` 能力。 - 客户端必须连接模型。 - 普通 REST 客户端将无法满足采样往返。 ### `plan_bulk_restock` 返回能力错误或空计划 可能原因： - 客户端不支持 `elicitation`。 - 所选类别和商店当前不产生任何合格的补货商品。 - 预算上限过滤掉所有内容。 ### `list_client_roots` 返回能力消息 这意味着客户端没有广播 `roots`。该工具正在按设计工作；它正在演示能力协商。 ### 库存更改在重启后消失 这是预期的。杂货演示使用从 `SeedData.cs` 播种的内存单例存储。 ## 告诉客户的话 如果您向客户展示此存储库，一个有用的总结是： - 从安全的读取和写入的确定性工具开始。 - 当可重复的 AI 任务很重要时添加提示。 - 当客户端需要稳定、可发现的上下文时添加资源。 - 当用户体验需要防护措施时添加补全。 - 当人类应选择约束时添加诱导。 - 当模型推理增加价值但应保持客户端所有权时添加采样。 - 当文本不再是合适的交互界面时添加 MCP 应用 UI。 这种渐进式的方法帮助客户将 MCP 视为 copilots 的实用集成层，而不仅仅是协议演示。