内容
# LeadMind MCP
> 一个MCP（模型上下文协议）服务器，将人工智能线索管理系统转变为任何兼容MCP的AI客户端（如Claude Desktop）可以直接控制的对话工具。
**仅限免费层级。生产级可靠性。为GitHub公开演示而构建。**
LeadMind同时演示了四点：
1. **实用的MCP实现**，使用所有三个MCP基元——**工具**、**资源**和**提示**——以及官方Python SDK。
2. **超越CRUD的智能推理**——服务器分类、建议下一步行动，并综合每周审查，不仅存储记录。
3. **生产级可靠性工程**——缓存、优雅降级和速率限制处理，所有这些都是被低估但高度重视的技能。
4. **零成本架构**——堆栈的每一层都运行在真正免费的层级上（Groq LLM、SQLite，无外部付费服务）。适合具有无限并发访客的公开GitHub演示。
---
## 目录
- [架构](#架构)
- [仅限免费层级的堆栈](#仅限免费层级的堆栈)
- [设置](#设置)
- [连接到Claude Desktop](#连接到claude-desktop)
- [MCP基元参考](#mcp基元参考)
- [工具（8）](#工具8)
- [资源（2）](#资源2)
- [提示模板（1）](#提示模板1)
- [演示安全设计](#演示安全设计)
- [项目结构](#项目结构)
- [可选集成（n8n + Gmail）](#可选集成n8n--gmail)
- [演示流程](#演示流程)
- [故障排除](#故障排除)
- [许可证](#许可证)
---
## 架构
```
┌────────────────────────────────────────────────────────────────────────────┐
│ MCP 客户端（例如Claude Desktop） │
│ │
│ 用户说：“给我展示所有热门线索，并建议对排名第一的线索采取下一步行动。” │
└──────────────────────────────┬─────────────────────────────────────────────┘
│ MCP协议（JSON-RPC via stdio或SSE）
▼
┌────────────────────────────────────────────────────────────────────────────┐
│ LeadMind MCP 服务器 │
│ （mcp_server.py，FastMCP） │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────────────────┐ │
│ │ 8 工具 │ │ 2 资源 │ │ 1 提示模板 │ │
│ │ （tools.py）│ │ │ │ （weekly_lead_review） │ │
│ └──────┬──────┘ └──────┬──────┘ └───────────────┬──────────────┘ │
│ │ │ │ │
│ └────────────────┬┴──────────────────────────┘ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ 可靠性层 │ │
│ │ │ │
│ │ ┌────────────┐ ┌────────────────────┐ ┌──────────────┐ │ │
│ │ │ cache.py │───▶│ groq_classifier.py │───▶│ fallback_ │ │ │
│ │ │ TTL+LRU │ │ （Groq + counter） │ │ classifier │ │ │
│ │ └────────────┘ └─────────┬──────────┘ └──────────────┘ │ │
│ │ │ 速率限制/错误 │ │
│ │ ▼ → fallback │ │
│ └───────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬─────────────────────────────────────────────┘
│
┌──────────────┴───────────────┐
▼ ▼
┌─────────────────────────┐ ┌──────────────────────────────────┐
│ SQLite（leadmind.db） │ │ Groq API（免费层级） │
│ │ │ Llama-3.3-70b-versatile │
│ - 线索 │ │ 30 req/min 免费 │
│ - 线索历史 │ │ │
│ - 审计日志 │ │ │
│ - 元数据 │ └──────────────────────────────────┘
└─────────────────────────┘
```
**`classify_lead(text)`的数据流：**
```
classify_lead(text)
│
▼
cache.get() ────────命中─────────▶ 返回缓存（source="cache"）
│
未命中
│
▼
Groq API 调用 ─────成功──────▶ 返回LLM结果（source="groq"）
│
429 / 超时 / 错误
│
▼
fallback_classifier.classify() ──▶ 返回基于规则的结果（source="fallback"）
│
▼
cache.set() （后续相同调用免费）
```
---
## 仅限免费层级的堆栈
每个组件都运行在真正免费的层级上。**没有信用卡试用，没有付费API，没有意外账单。**
| 层级 | 选择 | 免费层级详情 |
|---|---|---|
| LLM | **Groq API** (`llama-3.3-70b-versatile`) | 免费永久；~30 req/min，14,500 req/day。 [获取密钥](https://console.groq.com/keys)。 |
| 数据库 | **SQLite** （本地文件） | 零成本，零运维，零托管。位于 `leadmind.db`。 |
| MCP SDK | **`modelcontextprotocol/python-sdk`** | 开源（MIT）。 |
| Web框架 | **FastAPI** （可选，仅限Webhook） | 开源。 |
| 传输 | **stdio** （本地）或 **SSE** （远程） | 内置于MCP SDK。 |
| 托管 | 任意免费托管（Render，Fly.io，Railway免费层级，您的笔记本电脑） | 静态进程；无需特殊基础设施。 |
**故意不使用：**
- OpenAI / Anthropic APIs（付费，即使有免费积分也需要信用卡）。
- Hosted Postgres / Supabase / PlanetScale（免费层级存在但需要注册 + 信用卡）。
- 任何外部SaaS用于缓存、队列或监控。
---
## 设置
### 先决条件
- Python 3.10+
- （可选）来自 <https://console.groq.com/keys> 的免费Groq API密钥
### 安装
```bash
git clone <您的fork网址>
cd leadmind-mcp
python -m venv .venv
source .venv/bin/activate # 在Windows上：.venv\Scripts\activate
pip install -r requirements.txt
```
### 配置
```bash
cp .env.example .env
# 编辑.env并可选地填写GROQ_API_KEY
```
服务器**无需**Groq密钥即可工作——它将为所有内容使用基于规则的备用分类器。Groq密钥只是升级分类质量。
### 运行
```bash
# 默认：stdio传输（用于Claude Desktop）
python mcp_server.py
# 或：SSE传输（用于远程客户端）
MCP_TRANSPORT=sse MCP_PORT=8080 python mcp_server.py
```
首次运行时，服务器：
1. 创建`leadmind.db`（SQLite）。
2. 用18个现实的演示线索填充它。
3. 开始监听stdio（或SSE）。
---
## 连接到Claude Desktop
1. 打开Claude Desktop → **设置 → 开发者 → 编辑配置**。
2. 在`claude_desktop_config.json`中添加LeadMind：
```json
{
"mcpServers": {
"leadmind": {
"command": "python",
"args": ["/absolute/path/to/leadmind-mcp/mcp_server.py"],
"env": {
"GROQ_API_KEY": "your_key_here_or_leave_empty",
"DEMO_MODE": "true"
}
}
}
}
```
（参见`claude_desktop_config.example.json`获取模板。）
3. 重新启动Claude Desktop。你应该在**设置 → 开发者 → MCP 服务器**下看到`leadmind`，并带有绿色“已连接”的指示器。
4. 在[`demo_script.md`](./demo_script.md)中尝试演示脚本。
---
## MCP基元参考
### 工具（8）
| # | 工具 | 描述 | 示例调用 |
|---|---|---|---|
| 1 | `tool_get_leads(status="")` | 返回所有线索，可选地按Hot/Warm/Cold/Converted/Lost过滤。 | `tool_get_leads(status="Hot")` |
| 2 | `tool_classify_lead(text)` | 将消息分类为Hot/Warm/Cold，带有置信度 + 推理。使用缓存 → Groq → 备用。 | `tool_classify_lead("Need a CRM urgently, budget approved")` |
| 3 | `tool_add_lead(name, contact_info, message, source="manual")` | 添加线索并在插入时自动分类。 | `tool_add_lead(name="John", contact_info="john@x.com", message="...", source="Website Form")` |
| 4 | `tool_update_lead_status(id, status)` | 手动覆盖状态；记录更改并带有时间戳。 | `tool_update_lead_status(id=1, status="Converted")` |
| 5 | `tool_get_lead_stats()` | 聚合统计：总数、按状态/来源的分解、平均响应时间、转换率、Groq使用情况。 | `tool_get_lead_stats()` |
| 6 | `tool_get_lead_history(id)` | 线索状态更改和交互的完整时间线。 | `tool_get_lead_history(id=1)` |
| 7 | `tool_suggest_next_action(id)` | AI生成的下一步行动建议（带有备用）。 | `tool_suggest_next_action(id=1)` |
| 8 | `tool_bulk_import_leads(csv_data)` | 解析CSV文本并批量分类 + 插入。使用缓存避免重复API调用。 | `tool_bulk_import_leads("name,message\nJohn,...")` |
#### 示例工具响应（`tool_classify_lead`）
```json
{
"status": "Hot",
"confidence": 0.85,
"reasoning": "Hot because urgent language detected and budget mentioned — prioritize outreach.",
"source": "groq"
}
```
### 资源（2）
资源是MCP客户端可以“读取”的只读数据。
| URI | 描述 |
|---|---|
| `leads://dashboard` | 实时更新的整个管道的汇总快照——总数、分解、最近的线索、Groq使用情况监控。 |
| `audit://recent` | 最近的30条工具调用审计记录，记录了使用的路径（groq/fallback/cache）。演示可观察性。 |
### 提示模板（1）
| 提示 | 描述 |
|---|---|
| `weekly_lead_review` | 预包装一个结构化提示，供AI客户端生成完整的每周性能摘要。自动注入当前管道统计数据，并指示AI通过工具获取更多详细信息。 |
---
## 演示安全设计
该项目旨在GitHub上公开部署，带有实时演示链接。多个陌生人可以同时打开并测试它。系统**不能崩溃、被限速成故障或耗尽配额**。以下是如何缓解每个风险：
### 1. 响应缓存（防止速率限制）
- `cache.py`实现了一个线程安全的TTL缓存（默认5分钟，500条记录）。
- 缓存键是标准化消息文本的SHA-256哈希。
- 相同的`classify_lead(text)`调用在TTL窗口内返回缓存结果——**零Groq API调用**。
- 批量导入类似消息也受益（实际CRM数据中的常见模式）。
- 缓存跨进程共享所有工具调用。
- 缓存命中标记为`source: "cache"`，以便在审计日志中可见。
### 2. 优雅的备用（负载下零停机时间）
- `fallback_classifier.py`实现了一个透明的关键字/启发式分类器，与Groq路径具有相同的输入/输出契约。
- 如果Groq返回429（速率限制）、5xx、超时或任何其他错误——请求透明地降级到基于规则的分类器。
- 响应始终包括`source: "groq" | "fallback" | "cache"`，以便调用者知道使用的是哪条路径。
- 备用**可解释**：每个决定返回一个人类可读的推理字符串，例如`"Hot because 3 urgent/intent signal(s) detected (budget, asap, decision-ready) — prioritize outreach."`。
### 3. 种子演示数据（无空状态尴尬）
- `seed_data.py`定义了18个现实的演示线索，涵盖Hot/Warm/Cold和8个不同的来源。
- 首次运行时，数据库会自动填充。
- 每个种子线索的消息都编写以调用Groq分类器和备用分类器（因此，即使没有Groq密钥，演示也很有趣）。
### 4. 演示模式自动重置（自我愈合数据集）
- 当`DEMO_MODE=true`（默认）时，数据库每6小时（可通过`DEMO_RESET_INTERVAL_SEC`配置）重置为种子数据。
- 重置在下一个工具调用后延迟触发 - 不需要后台线程。
- 重置保留`audit_log`表，因此可观察性数据会累积。
### 5. Groq使用情况监控（免费层级可见性）
- 每个Groq调用都会增加一个进程计数器（`groq_classifier.get_call_count()`）。
- 每个调用也会记录到`groq_usage.log`，状态为（`success`, `rate_limited`, `error`）。
- `leads://dashboard`资源显示：此会话的调用次数、记录的总调用次数、速率限制次数、错误次数。
- `tool_get_lead_stats()`在其响应中返回一个`groq_usage`块。
- `audit_log`表记录每个工具调用的标志：`used_groq`, `used_fallback`, `used_cache` - 您可以回答“我的演示流量中多少比例使用了LLM？”只需一个SQL查询。
### 6. 可选身份验证（不仅仅是一个本地玩具）
- 设置`LEADMIND_AUTH_ENABLED=true`和`LEADMIND_API_KEY=<secret>`用于SSE / webhook部署。
- 对于stdio（Claude Desktop），通常关闭身份验证，因为传输是本地的。
- webhook接收器（`webhook_receiver.py`）验证每个请求上的`X-API-Key`。
---
## 项目结构
```
leadmind-mcp/
├── mcp_server.py # FastMCP服务器：注册工具、资源、提示
├── tools.py # 8个MCP工具实现（带有审计日志）
├── db.py # SQLite模式、CRUD、审计、演示重置逻辑
├── groq_classifier.py # Groq API + 缓存 + 备用链 + 使用情况计数器
├── fallback_classifier.py # 基于规则的关键字分类器（否定意识加权）
├── cache.py # 线程安全的TTL+LRU缓存
├── seed_data.py # 18个现实的演示线索 + 幂等填充
├── webhook_receiver.py # 可选的FastAPI应用，用于n8n/Gmail集成
├── config.py # 中央环境驱动配置
├── test_leadmind.py # 端到端工具测试（不需要Groq密钥）
├── test_mcp_protocol.py # 真实的MCP JSON-RPC协议烟雾测试
├── Makefile # 安装/测试/运行快捷方式
│
├── requirements.txt # Python依赖项（所有免费/开源）
├── .env.example # 环境变量模板
├── .gitignore
├── LICENSE # MIT
├── claude_desktop_config.example.json
├── demo_script.md # 示例对话流程
└── README.md # （本文件）
```
---
## 可选集成（n8n + Gmail）
### n8n Webhook 触发器
`webhook_receiver.py`公开了一个HTTP端点，n8n工作流可以POST到：
```bash
# 启动webhook接收器（单独进程）
pip install fastapi uvicorn
python webhook_receiver.py # 监听：8000
```
在n8n中，添加一个**HTTP请求**节点，将数据POST到`http://your-host:8000/webhook/lead`:
```json
{
"name": "Lead from n8n",
"contact_info": "lead@example.com",
"message": "Interested in your product, saw it on the webinar",
"source": "n8n Workflow"
}
```
webhook接收器使用相同的`tools.add_lead()`函数，因此线索会被自动分类并插入完整的历史记录。
### Gmail通知钩（免费层级）
Gmail的免费层级允许每天发送约20,000封电子邮件——足够一个演示。推荐的模式：
1. 创建一个Gmail过滤器，将匹配的电子邮件（例如主题包含“线索查询”）转发到Gmail Apps Script。
2. Apps Script解析电子邮件并POST到您的`/webhook/lead`端点。
3. （可选）设置`GMAIL_NOTIFY_TO`环境变量以启用新热门线索的外部通知。
实际的Gmail API集成故意不包含在内——它需要OAuth设置，这会破坏零配置演示。Webhook合约已记录，因此任何人都可以插入自己的Gmail桥接器。
---
## 演示流程
参见[`demo_script.md`](./demo_script.md)获取完整的对话流程演示。简短版本：
1. **“读取leads://dashboard资源”** → 实时管道快照。
2. **“给我展示所有热门线索，并建议对排名第一的线索采取下一步行动。”** → 两个工具调用自动串联。
3. **“添加新线索：John Smith, john@smith.com, '需要CRM，预算已批准，本周', Cold Outreach。”** → 自动分类为热门。
4. **“批量导入这些CSV线索...”** → 批量路径，缓存分类。
5. **“将线索ID=1标记为已转换。”** → 手动覆盖，历史记录。
6. **“生成weekly_lead_review提示。”** → 模板自动注入统计数据；Claude调用其他工具。
---
## 测试
包含两个测试套件。两者都在**没有Groq API密钥的情况下运行**（它们使用备用路径），因此可以在CI中安全运行。
### 1. 端到端工具测试
```bash
make test # 或：python test_leadmind.py
```
直接调用每个工具（绕过MCP传输），验证第二次`classify_lead`调用的缓存命中，断言`add_lead`正确分类，并检查资源/提示是否返回预期内容。
### 2. 真实的MCP协议烟雾测试
```bash
make test-proto # 或：python test_mcp_protocol.py
```
在子进程中启动`mcp_server.py`，使用stdio发送实际的MCP JSON-RPC协议，并验证：
- `initialize`握手成功
- `tools/list`返回8个工具
- `resources/list`返回2个资源
- `prompts/list`返回1个提示
- `tools/call`返回实际的线索数据
- `resources/read`返回仪表板文本
- `prompts/get`返回每周审查模板
这证明服务器可以与任何真实的MCP客户端（Claude Desktop, Cursor等）连接，而不仅仅是作为Python函数调用。
---
## 故障排除
**服务器无法在Claude Desktop上连接**
- 检查`claude_desktop_config.json`中的路径是否绝对。
- 检查`python`是否在您的PATH中（或使用Python二进制文件的完整路径）。
- 完全重启Claude Desktop（不仅仅是重新加载）。
- 查看Claude Desktop的开发者日志：`~/Library/Logs/Claude/mcp-server-leadmind.log`（macOS）。
**`ModuleNotFoundError: No module named 'mcp'`**
- 激活您的虚拟环境：`source .venv/bin/activate`.
- 重新安装：`pip install -r requirements.txt`.
**分类始终显示`source: "fallback"`**
- 或者未设置`GROQ_API_KEY`，或者Groq限制了您的访问。
- 检查`groq_usage.log` - 如果您看到很多`rate_limited`行，则备用正在发挥作用。
- 备用功能齐全；分类仍然正确，只是细微差别较少。
**克隆后数据库为空**
- 运行`python mcp_server.py`一次以触发初始填充。
- 或运行`python -c "from seed_data import seed_database; seed_database()"`.
**演示模式不断重置我的更改**
- 这是故意的。 在`.env`中设置`DEMO_MODE=false`，如果您希望更改持续。
---
## 许可证
MIT - 参见[`LICENSE`](./LICENSE).
---
## 为什么存在该项目
作为**AI自动化开发者 / 多智能体系统**角色的作品集。演示：
- **MCP掌握** - 使用所有三个基元（工具、资源、提示）。
- **智能设计** - 服务器不仅仅是CRUD；它分类、推荐和综合。
- **可靠性工程** - 缓存、优雅降级、速率限制处理。这是大多数作品集项目跳过的内容，也是招聘经理对生产角色最看重的内容。
- **成本纪律** - 一个真正的、可用的AI产品，在0美元/月的基础设施上运行，适合无限公共测试。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器