Lmd MCP Mvp

Yassir LMD行动副驾驶

Yassir最后一英里交付团队的人工智能操作助理。使用带有30个连接到MongoDB的专用工具的LLM，通过聊天界面实时回答操作问题。

目标受众： 项目经理、运营、利益相关者和开发人员。 访问模式： 只读。没有写入，没有突变，没有删除。

______________________________________________________________________

目录

• 架构概述
• 它是如何工作的（代理流）
• 快速开始
• 环境变量
• 大语言模型提供商
• 项目结构
• 工具参考（30个工具）
• API终点
• Web UI功能
• 安全和数据保护
• 货币处理
• 缓存
• Redis（可选）
• 对话存储
• 部署
• 常见问题解答

______________________________________________________________________

架构概述

┌──────────────────────────────────────────────────────┐
│                    Web UI (index.html)                │
│         Chat interface + Charts + Dev Mode            │
└────────────────────────┬─────────────────────────────┘
                         │ SSE (Server-Sent Events)
                         ▼
┌──────────────────────────────────────────────────────┐
│              Express API Server (api-server.ts)       │
│  Helmet CSP │ CORS │ Rate Limit │ API Key Auth        │
│                                                       │
│  POST /api/chat ──► LLM (tool calling loop)           │
│                      │                                │
│                      ▼                                │
│               30 Read-Only Tools                      │
│       ┌──────────┬──────────┬──────────┐              │
│       │ MongoDB  │  Redis   │ In-Memory│              │
│       │ (yacool) │(optional)│ (alerts) │              │
│       └──────────┴──────────┴──────────┘              │
└──────────────────────────────────────────────────────┘

______________________________________________________________________

它是如何工作的（代理流）

User question
    │
    ▼
Express backend receives message via POST /api/chat
    │
    ▼
Backend sends message + system prompt + 30 tool definitions to LLM
    │
    ▼
LLM decides which tool(s) to call (function calling)
    │
    ▼
Backend executes tool → READ-ONLY MongoDB query
    │
    ▼
Tool result sent back to LLM
    │
    ▼
LLM formulates human-friendly response (tables, charts, summaries)
    │
    ▼
Response streams back to user via SSE

步骤3-6可以循环到 12轮 对于复杂的问题。A. 服务器端超时2分钟 以及a 客户端超时90秒 防止请求失控。

______________________________________________________________________

快速开始

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your DB_URI and at least one LLM API key

# 3. Build TypeScript
npm run build

# 4. Start the web server
npm run web
# → http://localhost:3737

可用脚本

______________________________________________________________________

环境变量

______________________________________________________________________

大语言模型提供商

服务器从环境变量中自动检测提供者（找到的第一个密钥获胜）：

所有供应商都使用 兼容OpenAI的API 格式。终端中的每个请求都会记录令牌使用情况。

______________________________________________________________________

项目结构

lmd-mcp-mvp/
├── public/
│   ├── index.html              # Web chat UI (single file)
│   ├── favicon.svg             # Yassir 'Y' favicon
│   └── yassir-logo.svg         # Full Yassir logo
├── src/
│   ├── connections/
│   │   ├── mongodb.ts          # MongoDB connection (secondaryPreferred)
│   │   └── redis.ts            # Redis connection (optional, graceful fallback)
│   ├── constants/
│   │   └── order-status.ts     # Status code → label mapping
│   ├── resources/
│   │   └── collection-schemas.ts  # Field guides for LLM context
│   ├── schemas/                # Mongoose schema definitions
│   │   ├── order.schema.ts
│   │   ├── driver.schema.ts
│   │   ├── restaurant.schema.ts
│   │   └── city.schema.ts
│   ├── tools/                  # All 30 tools organized by domain
│   │   ├── alerts/             # set_alert
│   │   ├── analytics/          # 9 analytics tools
│   │   ├── config/             # city_config_lookup
│   │   ├── dispatch/           # rejection_analysis, dispatch_queue
│   │   ├── fleet/              # fleet_status, supply_demand, ghost_drivers, lookup_driver
│   │   ├── general/            # flexible_query, describe_collection, list_collections
│   │   ├── infra/              # shift_report, scheduled_reports
│   │   ├── orders/             # query_orders, needs_attention, sla_status, lookup/investigate
│   │   ├── restaurant/         # restaurant_health, auto_busy, lookup_restaurant
│   │   ├── users/              # lookup_user
│   │   └── registry.ts         # Single source of truth for all tool definitions
│   ├── utils/
│   │   ├── cache.ts            # In-memory cache with TTL
│   │   ├── currency.ts         # Country → currency resolver
│   │   ├── fact-check.ts       # Debug query formatting
│   │   ├── query-logger.ts     # Query logging utility
│   │   └── tool-error.ts       # Structured tool errors
│   ├── web/
│   │   ├── api-server.ts       # Express server (main entry for web mode)
│   │   ├── tool-registry.ts    # OpenAI function calling adapter
│   │   ├── csv-export.ts       # JSON → CSV export utility
│   │   └── conversation-store.ts  # File-based conversation persistence (legacy)
│   ├── server.ts               # MCP server setup
│   └── index.ts                # MCP stdio entry point
├── schema/                     # Original backend Mongoose schemas (reference)
├── system-prompt.txt           # LLM system prompt with rules and tool routing
├── package.json
└── tsconfig.json

______________________________________________________________________

工具参考（30个工具）

订单（6个工具）

车队（4个工具）

餐厅（3工具）

分析（9个工具）

调度（2个工具）

配置和基础设施（4个工具）

概述（3个工具）

______________________________________________________________________

API终点

SSE事件类型(/api/chat)

______________________________________________________________________

Web UI功能

• 聊天界面 使用markdown渲染（表格、粗体、链接）
• 图表渲染 --问“显示为图表”，AI输出交互式chart.js可视化（条形图、线条、饼图、甜甜圈）
• 快速操作 --常用查询的预设按钮（活动订单、车队状态、班次报告等）
• 国家聚焦 --侧边栏下拉菜单，用于查询特定国家的范围
• 开发模式 --切换以显示每个工具使用的原始MongoDB查询（用于事实检查）
• 会话持久性 --聊天记录保存在 localStorage，可从侧边栏恢复
• 停止按钮 --取消飞行中的请求（退出键或单击停止按钮）
• 深色主题 --Yassir品牌颜色

______________________________________________________________________

安全和数据保护

1.只读数据库访问

• MongoDB连接使用 readPreference: "secondaryPreferred"
• 所有工具仅执行 find, countDocuments, distinct，以及 aggregate 运营
• 无法执行插入、更新、删除或删除操作
• 所有模式都使用 strict: false 具有读取灵活性，但不存在写入模式

2.敏感场阻断

所有查询结果为 递归消毒 在发送给LLM或用户之前。

全球封锁模式 （任何包含这些字符串的字段名都会被编辑）：

password, token, secret, credit_card, card_number, cvv, pin, otp,
refresh_token, access_token, api_key, apikey, client_secret, auth_code,
approval_code, transaction_id, payment_order_id, action_id, device_token

特定于收藏的编辑 对于收款：

被阻止的字段显示为 "[REDACTED]" 结果。

3.查询安全

• 被阻止的操作员: $where, $function, $accumulator （无任意代码执行）
• 最大过滤深度：3个层次的嵌套
• 最大结果数：每个查询50个文档
• 被阻止的收藏: system.views, system.profile, system.js

4.API安全

• API密钥验证 --何时 API_KEY 设置， /api/chat 和 /api/export 需要 X-Api-Key 头球
• 速率限制 — express-rate-limit 上 /api/chat （默认值：60需求/分钟）
• 头盔CSP --限制脚本、样式和连接的内容安全策略
• 跨域资源共享 --可配置的原点限制
• Webhook URL验证 --定时报告阻止内部/私有IP（防止SSRF）

5.AI能看到什么和看不到什么

______________________________________________________________________

货币处理

每个国家都有自己的货币。该系统确保货币值始终以正确的货币符号显示。

它是如何工作的：

1. src/utils/currency.ts 解决 country_code → { currency_code, currency_symbol } 从 countrycurrency 集合（缓存5分钟，硬编码回退）
2. 所有货币工具(revenue_metrics, lookup_order, lookup_user, lookup_restaurant, promo_performance)包括 currency_code 和 currency_symbol 在他们的回答中
3. 当收入按国家分组时， 不计算跨货币总计 --您不能将DZD+MAD+EUR相加
4. 系统提示指示AI始终显示货币符号，从不跨货币求和

______________________________________________________________________

缓存

内存缓存(src/utils/cache.ts)减少频繁访问数据的数据库负载。

• 最大缓存条目数：200（LRU驱逐）
• 每个进程都有缓存，重启时重置

______________________________________________________________________

Redis（可选）

Redis是 可选的 并且仅由 dispatch_queue 用于监控调度队列的工具。

• 如果未配置Redis：该工具返回一条明确的错误消息，而不是崩溃
• 如果Redis关闭：重试前冷却60秒，没有应用程序崩溃
• 如果Redis可用：提供调度队列深度、卡住订单和处理计数

通过配置 REDIS_HOST, REDIS_PORT, REDIS_PASSWORD 环境变量。

______________________________________________________________________

对话存储

聊天对话存储在浏览器的 localStorage 在钥匙下面 yassir_conversations.

• 自动保存 每位助理回复后
• 可恢复的 从侧边栏（最多30个最近的对话）
• 可删除的 通过每个对话旁边的×按钮
• 每个浏览器 --对话在设备之间不同步
• 幸存者部署 --与服务器端存储不同，localStorage在服务器重启后仍然存在

______________________________________________________________________

部署

渲染（自由层）

该应用程序旨在在Render的免费层上运行：

• 不需要持久文件系统（对话在本地存储中）
• 单 npm run build && npm run web 命令
• 优雅降级：Redis、警报和计划报告在内存中工作，并优雅降级
• 通过Render仪表板配置的环境变量

生成命令

npm install && npm run build

开始命令

npm run web

健康检查

GET /api/health

退货 200 如果MongoDB已连接， 503 如果退化。

______________________________________________________________________

常见问题解答

它是只读的吗？

是的，100%。 服务器仅运行 find, countDocuments, distinct，以及 aggregate MongoDB操作。没有写模式，没有插入/更新/删除处理程序，连接使用 readPreference: "secondaryPreferred" 哪些路由到副本集次级。

它会泄露密码或支付信息吗？

号码 所有查询结果都通过两层进行递归清理：全局 BLOCKED_FIELDS （字段名称的模式匹配）以及 COLLECTION_REDACTED_KEYS （收款的确切字段名称）。被阻止的值显示为 "[REDACTED]".

如果LLM对字段名产生幻觉怎么办？

这 flexible_query 工具有一个 现场自动校正 系统。它对集合的实际字段进行采样，并将LLM请求的字段与最接近的实际字段模糊匹配。还有一个静态 FIELD_ALIASES 常见失配的映射（例如。， total_price → billings.amount.grand_total).

如果LLM试图写入数据库怎么办？

它不能。工具层只公开读取操作。没有注册写入工具。甚至 flexible_query 仅支持 count, find，以及 distinct 行动。

如果Redis宕机了怎么办？

应用程序继续工作。仅 dispatch_queue 使用Redis。如果Redis不可用，该工具会立即返回错误消息，而不会挂起。该应用程序从未因Redis故障而崩溃。

我可以将其用于MCP客户端（Claude、Cursor等）吗？

对。跑 npm run start 启动MCP stdio服务器。这通过模型上下文协议公开了所有30个工具，供任何兼容MCP的客户端使用。

代币是如何计算的？

每 /api/chat 请求将令牌使用情况记录到终端：

[llm] user query | input+output=total tokens | N tools | Xms

支持哪些国家？

DZ（阿尔及利亚）、MA（摩洛哥）、TN（突尼斯）、FR（法国）、SN（塞内加尔）、ZA（南非）。每个都有自己的货币、时区和操作配置。

我可以添加新工具吗？

1. 创建新 .tool.ts 文件在适当的 src/tools/ 子目录
2. 导出Zod模式和处理程序函数
3. 将工具添加到 src/tools/registry.ts
4. 向添加路由提示 system-prompt.txt
5. 重建与 npm run build

______________________________________________________________________

依赖项

______________________________________________________________________