AI Managed Shopping List

🛒 人工智能管理购物清单（MCP和Groq供电）

一个生产级的全栈人工智能应用程序，利用 模型上下文协议（MCP） 允许LLM通过自然语言管理本地PostgreSQL数据库。它采用现代技术栈构建，具有实时仪表板和能够进行复杂实体提取和部分库存扣除的专用AI代理。

______________________________________________________________________

🚀 主要特点

• 自然语言编排：使用英语会话添加、删除或列出项目（例如，“我买了2公斤5公斤的糖”）。
• 代理推理：技术支持 Groq（火焰3.3），系统区分“完成”项目和“扣除”数量。
• 模型上下文协议（MCP）：实施2025年行业标准，通过SSE将人工智能模型连接到本地数据源。
• 实时库存仪表板：光滑的 午夜黑 使用React和Tailwind CSS v4构建的UI，具有与PostgreSQL后端自动同步的功能。
• Docker化架构：整个堆栈（前端、后端和数据库）的一键部署。

______________________________________________________________________

📸 截图

1.仪表板（午夜主题）

Frontend Dashboard Frontend Dashboard Frontend Dashboard

______________________________________________________________________

2.MCP检查器调试

MCP Inspector Tool View MCP Inspector Tool View MCP Inspector Tool View MCP Inspector Tool View MCP Inspector Tool View

______________________________________________________________________

🛠 技术栈

• 后端Java 21、Spring Boot 3.5、Spring AI、Spring Data JPA。
• AI/LLM：Groq Cloud（Llama 3.3-70b），模型上下文协议（MCP）。
• 前端：React.js、Tailwind CSS v4、Lucide Icons、Axios。
• 数据库：PostgreSQL。
• 开发运维：Docker，Docker Compose。

______________________________________________________________________

🚦 入门指南

先决条件

• Node.js 20+
• JDK 21+
• Docker&Docker编写
• Groq API密钥

选项1:Docker部署（推荐）

1. 克隆存储库。

   git clone 

1. 创建一个 .env 根目录下的文件。

   cp .env.example .env

添加您的密钥： GROQ_API_KEY=your_key_here NLO；Postgres密码： POSTGRES_PASSWORD=your_secure_password.

1. 运行：

   docker-compose up --build

1. 访问UIhttp://localhost:5173后端位于http://localhost:8080.

方案2：地方发展

1. 克隆存储库。

   git clone 

1. 后端： 更新 application.properties 使用您的本地Postgres凭据并运行 AiManagedShoppingListApplication.
2. 前端：

   cd shopping-list-mcp-client
   npm install
   npm run dev

1. 访问UIhttp://localhost:5173后端位于http://localhost:8080.

______________________________________________________________________

🤖 人工智能工具（MCP）

后端向AI公开以下工具：

• addItem(name, quantity, unit)：添加或更新项目。

• listItems()：返回库存的当前状态。

• deductItem(name, amount)：处理部分购买。

• completeItem(name)：将商品标记为已完全购买。

• clearCompleted()：批量删除已完成的任务。

🔍 使用MCP检查器进行调试

这 MCP检查员 是一个专门的工具，用于可视化Spring Boot服务器和模型上下文协议之间的“握手”。它允许您测试Java方法，就像您是AI模型一样。

1.启动检查器：

确保您的Spring Boot后端正在运行http://localhost:8080.然后，在一个新的终端中，运行：

    npx @modelcontextprotocol/inspector

检查员通常会在http://localhost:6274.

2.通过SSE连接：

在检查器的浏览器窗口中：

• 将传输类型设置为 SSE.
• 输入URL：http://localhost:8080/sse.
• 单击“连接”。

3.逐步工具验证：

连接后，请按照以下步骤验证您的逻辑：

i） 工具发现： 转到“工具”选项卡。单击“列出工具”。您应该看到所有6个工具（addItem、listItems、debutItem等）及其描述。

ii） 状态验证： 选择 addItem.输入参数：

• name: Coffee
• quantity: 2
• unit: packs
• 单击运行工具。

iii） 交叉检查： 立即奔跑 listItems。输出现在应该反映更新的数据库状态。

iv） 逻辑测试： 跑 deductItem 随着 name: Coffee 和 amount: 1.快跑 listItems 再次确保数量降至 1.

______________________________________________________________________