房地产CRM连接服务

spark-mcp/
├── docs/                   # Spark.re API documentation (reference material)
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── tools/             # Tool handlers by category
│   │   ├── contacts.ts    # Contact search and management
│   │   ├── projects.ts    # Project listing and details
│   │   ├── interactions.ts # Interaction history
│   │   └── reports.ts     # Analytics and reporting
│   ├── api/
│   │   ├── client.ts      # Spark.re API client with auth
│   │   └── types.ts       # TypeScript types for API responses
│   └── utils/
│       ├── formatting.ts  # Response formatting for readability
│       └── errors.ts      # Error handling utilities
├── dist/                  # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── .env                   # API credentials (git-ignored)
├── .env.example           # Template for credentials
├── PATTERNS.md            # Implementation patterns and examples
└── README.md              # This file

# Clone the repository
git clone <repo-url> spark-mcp
cd spark-mcp

# Install dependencies
npm install

# Create environment file
cp .env.example .env
# Edit .env and add your SPARK_API_KEY

# Build the project
npm run build

# Verify build
ls dist/  # Should see index.js and other compiled files

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

{
  "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"]
}

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

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

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

// Fetch contacts individually in batches
const batchSize = 10; // Concurrent requests
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);
}

// Get engaged contacts via interactions
const interactions = await sparkApi.get('/interactions?project_id=2855');
const contactIds = [...new Set(interactions.map(i => i.contact_id))];
// Then fetch individual contacts for full data

// ❌ Wrong - ratings is not a direct property
const rating = contact.rating;

// ✅ Correct - ratings is an array
const rating = contact.ratings?.[0]?.value;

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

# Compile TypeScript
npm run build

# Test the server
node dist/index.js

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

New Lead
   ↓
[create_update_contact] ──→ Contact Created (ID: 123)
   ↓
Initial Call/Meeting
   ↓
[log_interaction] ──→ Activity Logged
   ↓
Follow-up Notes
   ↓
[add_contact_note] ──→ Note Added
   ↓
[search_contacts] ──→ Review Contact History
   ↓
[get_contact_details] ──→ Full Profile with All Notes & Interactions

User: "I just met Sarah Johnson at the Mira Mar open house. Her email is sarah.j@email.com
       and phone is 941-555-1234. She's interested in a 2-bedroom unit and found us through
       our website. Can you add her to the system?"

Claude uses create_update_contact:
- Creates contact with name, email, phone
- Sets project_id to Mira Mar (2855)
- Sets marketing_source to "Website"
- Returns contact ID: 8103687

User: "Great! I just had a 30-minute phone call with her to discuss floor plans.
       Can you log that?"

Claude uses log_interaction:
- contact_id: 8103687
- project_id: 2855
- interaction_type_id: 1 (Call)
- notes: "30-minute call discussing 2-bedroom floor plans"
- Returns interaction ID

User: "She mentioned she needs to close by March. Add a note about that."

Claude uses add_contact_note:
- contact_id: 8103687
- project_id: 2855
- note: "Needs to close by March - timeline critical"
- Returns confirmation

User: "Search for contact John Smith in Mira Mar"

Claude uses search_contacts:
- Returns: John Smith, ID: 8099234, Email: jsmith@example.com

User: "I just met with John. Update his phone to 941-555-9876 and log the meeting.
       We discussed pricing and he's very interested in the penthouse units."

Claude uses create_update_contact:
- contact_id: 8099234
- phone: "941-555-9876"
- Returns updated contact

Then uses log_interaction:
- contact_id: 8099234
- interaction_type_id: 3 (Meeting)
- notes: "Discussed pricing for penthouse units - very interested"
- Returns confirmation

User: "Add a new contact - Mark Davis, agent at Coldwell Banker.
       Email: mdavis@coldwell.com, phone 941-555-4321.
       He's referring clients to Mira Mar."

Claude uses create_update_contact:
- first_name: "Mark"
- last_name: "Davis"
- email: "mdavis@coldwell.com"
- phone: "941-555-4321"
- agent: true
- marketing_source: "Agent Referral"
- project_id: 2855
- Returns contact ID: 8103690

User: "Log that I emailed him our commission structure and floor plans today."

Claude uses log_interaction:
- contact_id: 8103690
- interaction_type_id: 2 (Email)
- notes: "Sent commission structure and floor plans"

User: "Show me all contacts from Mira Mar who haven't been contacted in the last 30 days"

Claude uses search_contacts with project_id filter, then analyzes last_interaction_date

User: "Call Lisa Martinez from that list. Update her phone to 941-555-7777 and log
       that I left a voicemail about our new pricing incentives."

Claude:
1. Searches for Lisa Martinez
2. Updates her phone number (create_update_contact)
3. Logs the interaction (log_interaction with notes: "Left voicemail about new pricing incentives")

User: "I attended the Sarasota Home Show yesterday and collected 5 leads. Let me add them:

       1. Robert Chen - robert@email.com, 941-555-0001
       2. Maria Garcia - maria.g@email.com, 941-555-0002
       3. David Kim - dkim@email.com, 941-555-0003
       4. Jennifer White - jwhite@email.com, 941-555-0004
       5. Carlos Rodriguez - crodriguez@email.com, 941-555-0005

       All from the Home Show, all interested in Mira Mar."

Claude uses create_update_contact 5 times:
- Creates each contact
- Sets marketing_source: "Home Show"
- Sets project_id: 2855
- Returns all 5 contact IDs

User: "Add a note to all of them that they visited our booth on October 9th."

Claude uses add_contact_note 5 times:
- Adds "Visited Mira Mar booth at Sarasota Home Show on October 9, 2025" to each contact

User: "Which marketing sources are bringing us the best quality leads?"

Claude uses get_lead_sources:
- project_id: 2855
- Returns analysis of all sources with quality scores

Output includes:
- Contact Quality Score (0-100) based on data completeness and engagement
- Volume metrics (total contacts per source)
- Engagement rates (% with interaction history)
- Recent activity trends (30-day engagement)

Claude analyzes and responds:
"Based on the data, your top 3 sources are:
1. Website (Quality: 87/100) - 45 contacts, 82% have full contact info
2. Referral (Quality: 92/100) - 23 contacts, highest engagement at 91%
3. Home Show (Quality: 71/100) - 67 contacts, but only 54% engaged

Recommendation: Referrals convert best but Website brings volume.
Consider nurturing Home Show leads more actively."

User: "What's our average follow-up time with leads? Are we contacting
       people quickly enough?"

Claude uses get_interaction_summary:
- project_id: 2855
- days_ago: 30
- Returns interaction patterns and timing analysis

Output includes:
- Average time between interactions: 4.2 days
- Median time between interactions: 2.8 days
- Interaction types breakdown (calls, emails, meetings)
- Team member activity distribution
- Daily activity timeline

Claude analyzes:
"Your team averages 4.2 days between follow-ups, but the median is 2.8 days,
suggesting some leads wait much longer.

Top performers:
- Team Member 7927: 45 interactions (38%)
- Team Member 7925: 32 interactions (27%)

Peak activity days: Monday-Tuesday. Fridays show 40% less activity.

Recommendation: Set 48-hour follow-up rule for new leads to match your
median performers."

User: "Compare leads from September vs October. Are October leads better quality?"

Claude uses get_contacts_by_criteria twice:
1. created_after: "2025-09-01T00:00:00Z", created_before: "2025-09-30T23:59:59Z"
2. created_after: "2025-10-01T00:00:00Z", created_before: "2025-10-31T23:59:59Z"

Returns two datasets with:
- Summary statistics (email/phone completion rates)
- Source distribution per cohort
- Engagement metrics
- Full contact details for pattern analysis

Claude compares:
"September: 34 contacts, 76% have email, 45% engaged
October: 52 contacts, 85% have email, 62% engaged

October leads are higher quality:
- Better data completion (+9% emails)
- Higher engagement rate (+17%)
- More diverse sources (7 vs 4)

Key difference: October had 'Fall Home Show' source with 18 high-quality leads."

User: "Do we get better engagement from agents or direct buyers?"

Claude uses get_contacts_by_criteria twice:
1. agent: true, project_id: 2855, limit: 100
2. agent: false, project_id: 2855, limit: 100

Returns both datasets with engagement metrics

Claude analyzes:
"Agents (67 contacts):
- 94% have interaction history
- Average 3.8 interactions per agent
- 88% recent activity (30 days)

Direct Buyers (114 contacts):
- 58% have interaction history
- Average 2.1 interactions per buyer
- 42% recent activity (30 days)

Agents are 62% more engaged but represent only 37% of database.
Direct buyers need more nurturing - 48 have never been contacted."

User: "Which interaction types correlate with more engaged leads -
       calls or emails?"

Claude uses get_interaction_summary:
- project_id: 2855
- days_ago: 60
- Returns breakdown by interaction type

Output shows:
- Type ID 17863 (Calls): 127 interactions, 45 unique contacts
- Type ID 17988 (Emails): 89 interactions, 62 unique contacts
- Type ID 17987 (Meetings): 34 interactions, 28 unique contacts

Claude calculates:
"Interaction patterns:
- Calls: 2.8 interactions per contact (high intensity)
- Emails: 1.4 interactions per contact (broadcast approach)
- Meetings: 1.2 interactions per contact (conversion stage)

Contacts with 2+ calls have 3x higher subsequent engagement.
Email-only contacts drop off after 45 days.

Recommendation: Use emails for initial reach, follow up with calls
within 48 hours for serious leads."

User: "Are leads added on weekends different from weekday leads?"

Claude uses get_contacts_by_criteria:
- Returns large dataset (75 contacts)
- Includes full timeline and source data

Claude analyzes creation timestamps:
"Weekend leads (Sat-Sun): 18 contacts
- 89% from 'Website' source
- 72% request callback (high intent)
- 61% convert to meetings

Weekday leads: 57 contacts
- More diverse sources (7 different)
- 45% request callback
- 34% convert to meetings

Weekend leads show 79% higher conversion intent.

Recommendation: Set up weekend lead alerts - these are hot prospects
researching on their own time."

User: "How many of our leads are missing critical contact information?"

Claude uses get_contacts_by_criteria:
- project_id: 2855
- limit: 100
- Returns full dataset with completeness metrics

Output shows:
- 100 contacts analyzed
- 82% have email (82 contacts)
- 67% have phone (67 contacts)
- 54% have both email AND phone (54 contacts)

Claude identifies:
"Data quality issues:
- 18 contacts with NO email (can't reach)
- 33 contacts with NO phone (can't call)
- 46 contacts missing email OR phone

15 contacts have NO contact method at all.

These 15 incomplete records:
[Lists specific contact IDs]

Recommendation: Priority cleanup - get phone numbers for the 15 no-email
contacts, they're likely from walk-ins or events."

User: "Show me recent interactions from Mira Mar"
Claude uses search_interactions with project_id: 2855
Returns list showing interaction_type_id values used in your project