火花-MCP

作者：dbreck0 星标更新：2025-10-23

安装使用来源：spider==github.com

项目介绍

Spark.re MCP Server

连接Claude Desktop与Spark.re房地产CRM API的Model Context Protocol服务器，支持自然语言查询及写操作，实现完整的销售工作流程自动化。

项目概述

目的： 使Claude能够通过对话界面直接查询、创建、更新和分析Spark.re CRM数据 开发： 在Claude Code中构建，在Claude Desktop中测试 状态： 已准备好生产使用，具备完整的读取/写入/分析功能

关键特性：

📖 读取操作： 搜索联系人，查看详细信息，分析项目，跟踪互动
✍️ 写入操作： 创建/更新联系人，记录互动，添加备注
📊 分析操作： 基于AI的潜在客户来源、参与模式、群组分析洞察
🔄 完整工作流： 从潜在客户捕获 → 互动记录 → 跟进笔记 → 绩效分析
🎯 销售导向： 针对房地产代理的日常任务和管理决策设计
✨ 自动ID丰富化： 显示“发送邮件”而不是“类型ID 17861”，显示“Nicholle DiPinto”而不是“团队成员7927”
📄 分页支持： 访问所有结果（超过第一页，如100+联系人、互动等）

技术栈

语言： TypeScript
运行时： Node.js 18+
MCP SDK： @modelcontextprotocol/sdk
传输： StdioServerTransport（用于Claude Desktop）
API： Spark.re REST API（Bearer token认证）

先决条件

Node.js 18或更高版本
npm或yarn
Spark.re API密钥（从Spark.re项目设置中获取）
Claude Desktop应用（用于测试）

项目结构

spark-mcp/
├── docs/                   # Spark.re API文档（参考材料）
├── src/
│   ├── index.ts           # MCP服务器入口点
│   ├── tools/             # 按类别分类的工具处理器
│   │   ├── contacts.ts    # 联系人搜索和管理
│   │   ├── projects.ts    # 项目列表和详细信息
│   │   ├── interactions.ts # 互动历史
│   │   └── reports.ts     # 分析和报告
│   ├── api/
│   │   ├── client.ts      # 带有认证的Spark.re API客户端
│   │   └── types.ts       # API响应的TypeScript类型
│   └── utils/
│       ├── formatting.ts  # 为了可读性而格式化的响应
│       └── errors.ts      # 错误处理实用程序
├── dist/                  # 编译的JavaScript（生成）
├── package.json
├── tsconfig.json
├── .env                   # API凭证（git忽略）
├── .env.example           # 凭证模板
├── PATTERNS.md            # 实现模式和示例
└── README.md              # 此文件

快速开始

安装（克隆现有仓库）

# 克隆仓库
git clone <repo-url> spark-mcp
cd spark-mcp

# 安装依赖
npm install

# 创建环境文件
cp .env.example .env
# 编辑.env并添加你的SPARK_API_KEY

# 构建项目
npm run build

# 验证构建
ls dist/  # 应该看到index.js和其他编译文件

从零开始设置（新项目）

1. 初始化项目

npm init -y
npm install @modelcontextprotocol/sdk dotenv
npm install -D typescript @types/node

2. 配置TypeScript

创建tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

3. 添加构建脚本

更新package.json：

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch",
    "start": "node dist/index.js"
  }
}

4. 设置环境

创建.env：

SPARK_API_KEY=your_api_key_here
SPARK_API_BASE_URL=https://api.spark.re/v1

创建.env.example（用于git）：

SPARK_API_KEY=your_api_key_here
SPARK_API_BASE_URL=https://api.spark.re/v1

开发工作流程

第一阶段：基础（先构建）

API客户端 (src/api/client.ts)
- Bearer token认证
- 请求/响应处理
- 错误管理
- 参见PATTERNS.md中的实现
服务器设置 (src/index.ts)
- MCP服务器初始化
- StdioServerTransport设置
- 工具注册框架
- 参见PATTERNS.md中的样板代码
类型 (src/api/types.ts)
- API响应的TypeScript接口
- 联系人、项目、互动类型
- 查看/docs/api/中的字段定义

第二阶段：核心工具（优先顺序）

按价值顺序实现这些工具：

search_contacts - 按姓名、电子邮件、项目、评分搜索联系人
get_contact_details - 完整的联系人概况，包括互动
list_projects - 活动项目及其基本统计
get_project_analytics - 详细的项目指标
search_interactions - 最近的联系人活动

每个工具需要：

工具定义在ListToolsRequestSchema处理器中
在适当的/tools/*.ts文件中的处理器函数
在/utils/formatting.ts中的响应格式化
使用/utils/errors.ts进行错误处理

参见PATTERNS.md中的每个组件的完整示例。

第三阶段：格式化与润色

响应格式化 (src/utils/formatting.ts)
- 将API JSON转换为可读的markdown
- 使用表格、项目符号、标题
- 格式化日期为相对时间（如“2天前”）
- 参见PATTERNS.md中的格式化函数
错误处理 (src/utils/errors.ts)
- 用户友好的错误消息
- 速率限制重试逻辑
- 认证失败检测
- 参见PATTERNS.md中的错误模式

API文档

完整的Spark.re API文档位于/docs/api/和/docs/knowledge-base/。

需实现的关键端点：

GET /contacts - 联系人搜索
GET /contacts/:id - 联系人详情
GET /projects - 项目列表
GET /projects/:id/analytics - 项目统计数据
GET /interactions - 互动历史

参考文档以了解：

请求参数
响应结构
认证头
速率限制

重要API行为：列表端点 vs 单个端点

关键发现： Spark API根据使用的端点返回不同深度的数据：

列表端点（例如，`GET /contacts`）

返回优化性能的“轻量级”联系人数据：

包含： 基本字段如id、first_name、last_name、email、phone、created_at
排除： 嵌套数据如ratings、projects、notes、team_members、自定义字段
用例： 搜索、过滤，获取进一步查询的联系人ID
性能： 快速，能高效处理分页

单个端点（例如，`GET /contacts/{id}`）

返回包含所有嵌套关系的完整联系人数据：

包含： 所有49+字段，包括ratings数组、projects、notes、team_members
格式： 评分作为数组：[{id, value, color, position}]
用例： 获取完整的联系人详情，访问评分和关系
性能： 较慢，应选择性使用

实际影响

问题： 如果你需要多个联系人的评分，列表端点不会包含它们。

解决方案1 - 单独获取（用于get_sales_funnel）：

// 分批次获取联系人
const batchSize = 10; // 并发请求
for (let i = 0; i < contactIds.length; i += batchSize) {
  const batch = contactIds.slice(i, i + batchSize);
  const batchPromises = batch.map(id =>
    sparkApi.get(`/contacts/${id}`)
  );
  const results = await Promise.all(batchPromises);
}

✅ 获取完整数据，包括评分
⚠️ 对大数据集较慢（例如，176个联系人 ≈ 18秒，10个并发）
使用场景： 需要评分、备注或其他嵌套数据时

解决方案2 - 互动为基础的工作方法：

// 通过互动获取活跃联系人
const interactions = await sparkApi.get('/interactions?project_id=2855');
const contactIds = [...new Set(interactions.map(i => i.contact_id))];
// 然后获取单个联系人的完整数据

✅ 过滤到只有活跃联系人（那些有活动的）
✅ 更相关的分析数据集
使用场景： 分析活跃管道、销售漏斗

访问评分：

// ❌ 错误 - 评分不是一个直接属性
const rating = contact.rating;

// ✅ 正确 - 评分是一个数组
const rating = contact.ratings?.[0]?.value;

此行为在我们的代码中有记录：

src/index.ts:668-670 - formatContactsResponse()
src/index.ts:723-726 - handleGetContactDetails()
src/index.ts:2046-2070 - handleGetSalesFunnel()批量获取

实现指南

认证模式

所有请求都需要Bearer token：

headers: {
  'Authorization': `Bearer ${process.env.SPARK_API_KEY}`,
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

工具命名约定

使用清晰、行动导向的名称：

✅ search_contacts、get_project_analytics、list_projects
❌ contacts、getData、fetch

响应格式

始终为可读性格式化响应：

使用markdown（标题、项目符号、表格）
格式化日期为相对时间（如“3天前”）
逻辑地组织数据（最重要的放在前面）
保持响应简洁但完整

坏：返回原始JSON 好：格式化为带上下文的结构化文本

参见PATTERNS.md中的格式化示例。

错误处理

返回有用的错误消息：

✅ “认证失败。请检查您的SPARK_API_KEY。”
❌ “错误401：未授权”

处理常见情况：

缺少API密钥
无效凭据
速率限制（带有退避的重试）
网络超时
结果为空

测试

构建与运行

# 编译TypeScript
npm run build

# 测试服务器
node dist/index.js

配置Claude Desktop

编辑Claude Desktop配置：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spark-re": {
      "command": "node",
      "args": ["/Users/dannybreckenridge/spark-mcp/dist/index.js"],
      "env": {
        "SPARK_API_KEY": "your_api_key_here"
      }
    }
  }
}

在Claude Desktop中测试

配置更改后重启Claude Desktop
开始新的对话
尝试查询如：
- “搜索名为John的联系人”
- “展示项目X的分析”
- “过去7天发生了哪些互动？”

调试检查清单

如果工具不起作用：

检查npm run build是否无错误完成
验证配置中设置了API密钥
检查Claude Desktop控制台中的错误消息
直接测试API客户端（在MCP集成之前）
验证响应格式化返回字符串，而非对象

参考材料

PATTERNS.md - 完整的实现示例和代码模式
docs/api/ - Spark.re API端点文档
docs/knowledge-base/ - Spark.re功能文档
MCP SDK文档 - https://modelcontextprotocol.io

开发笔记

对于Claude Code

当构建这个项目时：

先构建基础 - API客户端和服务器设置
逐步构建 - 一次一个工具，测试后再继续
参考PATTERNS.md - 不要重新发明轮子，使用示例
验证docs/api/ - 实现前核实端点结构
格式化响应 - 始终让输出对人类可读
优雅地处理错误 - 用户友好的消息，不显示堆栈跟踪
使用TypeScript类型 - 为API响应定义接口
每次工具后测试 - 编译并验证其工作

需避免的常见陷阱

❌ 返回原始JSON而不是格式化文本
❌ 不处理缺失的环境变量
❌ 解析前忘记检查response.ok
❌ 使用技术性错误消息而不是用户友好的消息
❌ 构建后不在Claude Desktop中测试
❌ 硬编码API密钥而不是使用环境变量

销售工作流程图

新潜在客户
   ↓
[create_update_contact] ──→ 联系人创建（ID：123）
   ↓
初次通话/会议
   ↓
[log_interaction] ──→ 活动记录
   ↓
跟进笔记
   ↓
[add_contact_note] ──→ 笔记添加
   ↓
[search_contacts] ──→ 查看联系人历史
   ↓
[get_contact_details] ──→ 包含所有笔记和互动的完整概况

可用工具

读取操作（查询数据）

search_contacts - 按姓名、电子邮件、项目或评分搜索联系人（带分页）
get_contact_details - 获取完整的联系人概况，包括互动和备注
list_projects - 列出所有项目及其基本信息（带分页）
get_project_details - 获取详细的项目信息
search_interactions - 搜索互动历史，自动丰富名称（带分页）

写入操作（修改数据）

create_update_contact - 创建新联系人或更新现有联系人
log_interaction - 记录电话、会议、电子邮件及其他接触点
add_contact_note - 向联系人记录添加快速备注

分析操作（基于AI的洞察）

get_contacts_by_criteria - 高级筛选返回25-100个联系人用于模式分析（带分页）
get_interaction_summary - 汇总互动数据，自动丰富名称，节奏和参与度指标（带分页）
get_lead_sources - 营销来源表现，质量评分和ROI数据

参考数据操作（ID映射）

list_interaction_types - 获取所有互动类型定义（例如，“电话呼叫”，“发送邮件”）
list_team_members - 获取所有团队成员及其ID → 名称映射
list_ratings - 获取所有联系人评分定义（例如，“热线索”，“代理”）

实用销售工作流程示例

示例1：完整的新增潜在客户工作流程

销售代理在开放日遇到潜在买家，并希望将其添加到CRM中：

用户：“我在Mira Mar开放日遇到了Sarah Johnson。她的电子邮件是sarah.j@email.com，
      电话是941-555-1234。她对两居室单元感兴趣，并通过我们的网站找到我们。你能把她加到系统里吗？”

Claude使用create_update_contact：
- 创建具有姓名、电子邮件、电话的联系人
- 设置项目ID为Mira Mar（2855）
- 设置营销来源为“网站”
- 返回联系人ID：8103687

用户：“很好！我刚刚与她进行了30分钟的电话讨论了平面图。你能记录下来吗？”

Claude使用log_interaction：
- contact_id：8103687
- project_id：2855
- interaction_type_id：1（电话）
- 备注：“30