propstack-mcp-server 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +321 -321
- package/dist/tools/activities.d.ts.map +1 -1
- package/dist/tools/activities.js +7 -6
- package/dist/tools/activities.js.map +1 -1
- package/dist/tools/admin.d.ts.map +1 -1
- package/dist/tools/admin.js +9 -8
- package/dist/tools/admin.js.map +1 -1
- package/dist/tools/composites.d.ts.map +1 -1
- package/dist/tools/composites.js +23 -22
- package/dist/tools/composites.js.map +1 -1
- package/dist/tools/contacts.js +1 -1
- package/dist/tools/contacts.js.map +1 -1
- package/dist/tools/deals.d.ts +5 -0
- package/dist/tools/deals.d.ts.map +1 -1
- package/dist/tools/deals.js +65 -8
- package/dist/tools/deals.js.map +1 -1
- package/dist/tools/documents.d.ts.map +1 -1
- package/dist/tools/documents.js +7 -6
- package/dist/tools/documents.js.map +1 -1
- package/dist/tools/helpers.d.ts.map +1 -1
- package/dist/tools/helpers.js +8 -0
- package/dist/tools/helpers.js.map +1 -1
- package/dist/tools/lookups.d.ts.map +1 -1
- package/dist/tools/lookups.js +28 -15
- package/dist/tools/lookups.js.map +1 -1
- package/dist/tools/projects.d.ts.map +1 -1
- package/dist/tools/projects.js +8 -6
- package/dist/tools/projects.js.map +1 -1
- package/dist/types/propstack.d.ts +31 -7
- package/dist/types/propstack.d.ts.map +1 -1
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,321 +1,321 @@
|
|
|
1
|
-
# Propstack MCP Server
|
|
2
|
-
|
|
3
|
-
Connect AI assistants (Claude, ChatGPT) to your Propstack real estate CRM.
|
|
4
|
-
|
|
5
|
-
> **Verbinden Sie KI-Assistenten mit Ihrem Propstack-CRM** — Kontakte verwalten, Objekte durchsuchen, Deals pflegen, Besichtigungen planen und Suchprofile erstellen, alles per Sprache oder Chat.
|
|
6
|
-
|
|
7
|
-
## What you can do / Was Sie damit machen koennen
|
|
8
|
-
|
|
9
|
-
- **Contact management** — search, create, update, and tag contacts with GDPR tracking
|
|
10
|
-
- **Property search & management** — filter by price, rooms, area, status; create and update listings
|
|
11
|
-
- **Deal pipeline** — create deals, move through stages, track win/loss rates
|
|
12
|
-
- **Buyer matching** — create search profiles from natural language ("3-Zimmer in Berlin, bis 400k, mit Balkon") and auto-match to new listings
|
|
13
|
-
- **Task & calendar** — log call notes, set follow-up reminders, schedule viewings
|
|
14
|
-
- **Email** — send templated emails linked to contacts and properties
|
|
15
|
-
- **360-degree contact view** — get a complete briefing before every call
|
|
16
|
-
- **Pipeline dashboards** — deal counts and values per stage, stale deal alerts
|
|
17
|
-
- **Lead intake** — one-call workflow: dedup, create contact, log notes, create deal, set reminder
|
|
18
|
-
- **Bulk export** — full data dumps for reporting, backup, or migration
|
|
19
|
-
|
|
20
|
-
## Quick Start
|
|
21
|
-
|
|
22
|
-
### 1. Set your API key
|
|
23
|
-
|
|
24
|
-
```bash
|
|
25
|
-
export PROPSTACK_API_KEY=your_api_key_here
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
### 2a. Claude Desktop
|
|
29
|
-
|
|
30
|
-
Add to your Claude Desktop config (`claude_desktop_config.json`):
|
|
31
|
-
|
|
32
|
-
```json
|
|
33
|
-
{
|
|
34
|
-
"mcpServers": {
|
|
35
|
-
"propstack": {
|
|
36
|
-
"command": "npx",
|
|
37
|
-
"args": ["-y", "propstack-mcp-server"],
|
|
38
|
-
"env": {
|
|
39
|
-
"PROPSTACK_API_KEY": "your_api_key_here"
|
|
40
|
-
}
|
|
41
|
-
}
|
|
42
|
-
}
|
|
43
|
-
}
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
### 2b. Claude Code (CLI)
|
|
47
|
-
|
|
48
|
-
Add to your project's `.mcp.json`:
|
|
49
|
-
|
|
50
|
-
```json
|
|
51
|
-
{
|
|
52
|
-
"mcpServers": {
|
|
53
|
-
"propstack": {
|
|
54
|
-
"command": "npx",
|
|
55
|
-
"args": ["-y", "propstack-mcp-server"],
|
|
56
|
-
"env": {
|
|
57
|
-
"PROPSTACK_API_KEY": "your_api_key_here"
|
|
58
|
-
}
|
|
59
|
-
}
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
### 2c. ChatGPT
|
|
65
|
-
|
|
66
|
-
1. Go to **Settings > Connectors > Developer Mode**
|
|
67
|
-
2. Add a new MCP connector
|
|
68
|
-
3. Set the command to `npx -y propstack-mcp-server`
|
|
69
|
-
4. Add environment variable `PROPSTACK_API_KEY`
|
|
70
|
-
|
|
71
|
-
### 2d. Cursor IDE
|
|
72
|
-
|
|
73
|
-
1. Open **Settings** (Ctrl+,) → search "MCP"
|
|
74
|
-
2. Edit **MCP Servers** JSON, or add `mcp.json` in project root / `.cursor/`
|
|
75
|
-
|
|
76
|
-
**Option A — local project** (after `npm run build`):
|
|
77
|
-
|
|
78
|
-
```json
|
|
79
|
-
{
|
|
80
|
-
"mcpServers": {
|
|
81
|
-
"propstack": {
|
|
82
|
-
"command": "node",
|
|
83
|
-
"args": ["./dist/index.js"],
|
|
84
|
-
"cwd": "C:/Users/you/path/to/propstack_mcp",
|
|
85
|
-
"env": {
|
|
86
|
-
"PROPSTACK_API_KEY": "your_api_key_here"
|
|
87
|
-
}
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
}
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
Or use `.env` in project root — the server loads it automatically; you can omit the `env` block.
|
|
94
|
-
|
|
95
|
-
**Option B — npx** (published package or `npx` from local):
|
|
96
|
-
|
|
97
|
-
```json
|
|
98
|
-
{
|
|
99
|
-
"mcpServers": {
|
|
100
|
-
"propstack": {
|
|
101
|
-
"command": "npx",
|
|
102
|
-
"args": ["-y", "propstack-mcp-server"],
|
|
103
|
-
"env": {
|
|
104
|
-
"PROPSTACK_API_KEY": "your_api_key_here"
|
|
105
|
-
}
|
|
106
|
-
}
|
|
107
|
-
}
|
|
108
|
-
}
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
### 2e. Run directly
|
|
112
|
-
|
|
113
|
-
```bash
|
|
114
|
-
npm install propstack-mcp-server
|
|
115
|
-
PROPSTACK_API_KEY=your_key npx propstack-mcp-server
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
## API Key / API-Schluessel
|
|
119
|
-
|
|
120
|
-
Get your Propstack API key:
|
|
121
|
-
|
|
122
|
-
1. Log in to [crm.propstack.de](https://crm.propstack.de)
|
|
123
|
-
2. Go to **Verwaltung > API-Schluessel** (Administration > API Keys)
|
|
124
|
-
3. Create or copy your V1 API key
|
|
125
|
-
|
|
126
|
-
> **Hinweis:** Der API-Schluessel bestimmt die Berechtigungen. Stellen Sie sicher, dass Lese- und Schreibzugriff fuer die benoetigten Endpunkte aktiviert ist.
|
|
127
|
-
|
|
128
|
-
## Available Tools (50)
|
|
129
|
-
|
|
130
|
-
### Contacts (Kontakte)
|
|
131
|
-
|
|
132
|
-
| Tool | Description |
|
|
133
|
-
|---|---|
|
|
134
|
-
| `search_contacts` | Search and filter contacts by name, email, phone, status, tags, broker, GDPR status |
|
|
135
|
-
| `get_contact` | Get full details of a single contact with related data |
|
|
136
|
-
| `create_contact` | Create a new contact (auto-dedup by email) |
|
|
137
|
-
| `update_contact` | Update contact details, tags, GDPR status, broker assignment |
|
|
138
|
-
| `delete_contact` | Soft-delete a contact (30-day recycle bin) |
|
|
139
|
-
| `get_contact_sources` | List lead sources (ImmoScout24, Website, Empfehlung, etc.) |
|
|
140
|
-
| `search_contacts_by_phone` | Look up a contact by phone number (formatting-insensitive) |
|
|
141
|
-
|
|
142
|
-
### Properties (Objekte)
|
|
143
|
-
|
|
144
|
-
| Tool | Description |
|
|
145
|
-
|---|---|
|
|
146
|
-
| `search_properties` | Search properties with 11 range filters, 17 sort fields |
|
|
147
|
-
| `get_property` | Get full property details including media and custom fields |
|
|
148
|
-
| `create_property` | Create a new property listing |
|
|
149
|
-
| `update_property` | Update price, status, description, broker assignment |
|
|
150
|
-
| `get_property_statuses` | List property statuses (Verfuegbar, Reserviert, Verkauft, etc.) |
|
|
151
|
-
|
|
152
|
-
### Tasks (Aufgaben & Notizen)
|
|
153
|
-
|
|
154
|
-
| Tool | Description |
|
|
155
|
-
|---|---|
|
|
156
|
-
| `create_task` | Create a note, to-do, appointment, or cancellation (polymorphic) |
|
|
157
|
-
| `update_task` | Mark done, reschedule, update notes |
|
|
158
|
-
| `get_task` | Get task details with linked contacts, properties, projects |
|
|
159
|
-
|
|
160
|
-
### Deals (Pipeline)
|
|
161
|
-
|
|
162
|
-
| Tool | Description |
|
|
163
|
-
|---|---|
|
|
164
|
-
| `search_deals` | Search deals by stage, pipeline, category, broker, feeling score |
|
|
165
|
-
| `create_deal` | Link a contact to a property at a pipeline stage |
|
|
166
|
-
| `update_deal` | Move deal through pipeline stages, update price/notes |
|
|
167
|
-
|
|
168
|
-
### Search Profiles (Suchprofile)
|
|
169
|
-
|
|
170
|
-
| Tool | Description |
|
|
171
|
-
|---|---|
|
|
172
|
-
| `list_search_profiles` | List what buyers/renters are looking for |
|
|
173
|
-
| `create_search_profile` | Capture buyer criteria from natural language |
|
|
174
|
-
| `update_search_profile` | Adjust budget, cities, room count, features |
|
|
175
|
-
| `delete_search_profile` | Remove a search profile |
|
|
176
|
-
|
|
177
|
-
### Projects (Projekte)
|
|
178
|
-
|
|
179
|
-
| Tool | Description |
|
|
180
|
-
|---|---|
|
|
181
|
-
| `list_projects` | List development projects with unit counts |
|
|
182
|
-
| `get_project` | Get project details with all units, media, documents |
|
|
183
|
-
|
|
184
|
-
### Activities & Events (Aktivitaeten & Termine)
|
|
185
|
-
|
|
186
|
-
| Tool | Description |
|
|
187
|
-
|---|---|
|
|
188
|
-
| `search_activities` | Full activity timeline for a contact, property, or project |
|
|
189
|
-
| `list_events` | Calendar events — viewings, meetings, filtered by date/state |
|
|
190
|
-
|
|
191
|
-
### Emails (E-Mails)
|
|
192
|
-
|
|
193
|
-
| Tool | Description |
|
|
194
|
-
|---|---|
|
|
195
|
-
| `send_email` | Send email using a Propstack template (snippet) |
|
|
196
|
-
| `update_email` | Mark read/archived, categorize, link to CRM records |
|
|
197
|
-
|
|
198
|
-
### Documents (Dokumente)
|
|
199
|
-
|
|
200
|
-
| Tool | Description |
|
|
201
|
-
|---|---|
|
|
202
|
-
| `list_documents` | List files attached to a property, project, or contact |
|
|
203
|
-
| `upload_document` | Upload a document (base64 data URI) |
|
|
204
|
-
|
|
205
|
-
### Relationships (Beziehungen)
|
|
206
|
-
|
|
207
|
-
| Tool | Description |
|
|
208
|
-
|---|---|
|
|
209
|
-
| `create_ownership` | Link a contact as property owner (Eigentuemer) |
|
|
210
|
-
| `create_partnership` | Link a contact as buyer, tenant, etc. (Kaeufer, Mieter) |
|
|
211
|
-
|
|
212
|
-
### Lookups (Konfiguration)
|
|
213
|
-
|
|
214
|
-
| Tool | Description |
|
|
215
|
-
|---|---|
|
|
216
|
-
| `list_pipelines` | Get deal pipelines with stages (IDs, names, positions) |
|
|
217
|
-
| `get_pipeline` | Get a single pipeline with stage details |
|
|
218
|
-
| `list_tags` | List tags/groups (Merkmale) — filter contacts by group IDs |
|
|
219
|
-
| `create_tag` | Create a new tag for contacts, properties, or activities |
|
|
220
|
-
| `list_activity_types` | List note/todo/event templates for create_task |
|
|
221
|
-
| `list_contact_statuses` | List contact statuses for search/assign |
|
|
222
|
-
| `list_reservation_reasons` | List deal cancellation reasons |
|
|
223
|
-
| `list_custom_fields` | Discover custom field definitions (names, types, options) |
|
|
224
|
-
| `list_users` | List all brokers/agents with contact info |
|
|
225
|
-
| `list_teams` | List teams/departments with member assignments |
|
|
226
|
-
| `list_locations` | List geographic areas (Geolagen) for location matching |
|
|
227
|
-
|
|
228
|
-
### Smart Composites (Intelligente Workflows)
|
|
229
|
-
|
|
230
|
-
| Tool | Description |
|
|
231
|
-
|---|---|
|
|
232
|
-
| `full_contact_360` | Complete contact dossier — info, search profiles, deals, activity |
|
|
233
|
-
| `property_performance_report` | Days on market, inquiry count, pipeline breakdown, activity summary |
|
|
234
|
-
| `pipeline_summary` | Deals per stage, total values, stale deals needing attention |
|
|
235
|
-
| `smart_lead_intake` | Full lead workflow: dedup, create/update, log notes, deal, reminder |
|
|
236
|
-
| `match_contacts_to_property` | Find buyers whose search profiles match a property |
|
|
237
|
-
|
|
238
|
-
### Admin (Verwaltung)
|
|
239
|
-
|
|
240
|
-
| Tool | Description |
|
|
241
|
-
|---|---|
|
|
242
|
-
| `list_webhooks` | List all configured webhook subscriptions |
|
|
243
|
-
| `create_webhook` | Subscribe to CRM events (CLIENT_CREATED, PROPERTY_UPDATED, etc.) |
|
|
244
|
-
| `delete_webhook` | Remove a webhook subscription |
|
|
245
|
-
| `export_data` | Bulk export an entire data table as JSON |
|
|
246
|
-
| `get_contact_favorites` | Get properties a contact has favorited |
|
|
247
|
-
|
|
248
|
-
## Example Conversations / Beispiel-Konversationen
|
|
249
|
-
|
|
250
|
-
### Morning Briefing / Morgen-Briefing
|
|
251
|
-
|
|
252
|
-
> **You:** What's on my calendar today?
|
|
253
|
-
>
|
|
254
|
-
> **AI:** *calls `list_events` with today's date range* — You have 3 viewings scheduled...
|
|
255
|
-
|
|
256
|
-
> **Du:** Gibt es neue Leads seit gestern?
|
|
257
|
-
>
|
|
258
|
-
> **KI:** *ruft `search_contacts` mit created_at_from=gestern auf* — 5 neue Kontakte...
|
|
259
|
-
|
|
260
|
-
### Lead Intake / Leaderfassung
|
|
261
|
-
|
|
262
|
-
> **You:** I just got off the phone with Maria Schmidt, +49 157 1234 5678. She's looking for a 3-room apartment in Berlin, budget 300-400k, must have a balcony. She found us on ImmoScout.
|
|
263
|
-
>
|
|
264
|
-
> **AI:** *calls `smart_lead_intake`* — Contact created (ID: 4521), call note logged, follow-up reminder set for tomorrow 9:00. Would you like me to create a search profile for her criteria?
|
|
265
|
-
|
|
266
|
-
### Property Matching / Objekt-Matching
|
|
267
|
-
|
|
268
|
-
> **Du:** Wir haben ein neues Listing: 3-Zimmer-Wohnung in Charlottenburg, 385.000 EUR. Wer kommt als Kaeufer in Frage?
|
|
269
|
-
>
|
|
270
|
-
> **KI:** *ruft `match_contacts_to_property` auf* — 12 passende Suchprofile gefunden. Top 3: Herr Weber (Score 95%), Frau Mueller (Score 88%), Herr Kim (Score 85%)...
|
|
271
|
-
|
|
272
|
-
### Pipeline Review
|
|
273
|
-
|
|
274
|
-
> **You:** How's our sales pipeline looking? Any stale deals?
|
|
275
|
-
>
|
|
276
|
-
> **AI:** *calls `pipeline_summary`* — 47 active deals, total value 12.3M EUR. 5 deals haven't been updated in 14+ days...
|
|
277
|
-
|
|
278
|
-
### Pre-Call Briefing / Vor dem Anruf
|
|
279
|
-
|
|
280
|
-
> **Du:** Gib mir alles ueber Kontakt 3847 — ich rufe gleich an.
|
|
281
|
-
>
|
|
282
|
-
> **KI:** *ruft `full_contact_360` auf* — Herr Weber, Rating 3 Sterne, sucht 3-Zimmer in Berlin/Potsdam bis 400k. 2 aktive Deals, letzte Aktivitaet vor 3 Tagen...
|
|
283
|
-
|
|
284
|
-
## Development
|
|
285
|
-
|
|
286
|
-
```bash
|
|
287
|
-
git clone <repo-url>
|
|
288
|
-
cd propstack-mcp-server
|
|
289
|
-
npm install
|
|
290
|
-
npm run build # tsc → dist/
|
|
291
|
-
npm start # requires PROPSTACK_API_KEY
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
### Project Structure
|
|
295
|
-
|
|
296
|
-
```
|
|
297
|
-
src/
|
|
298
|
-
index.ts # Server entry point (stdio transport)
|
|
299
|
-
propstack-client.ts # HTTP client with auth, retry, error handling
|
|
300
|
-
types/
|
|
301
|
-
propstack.ts # TypeScript interfaces for all API responses
|
|
302
|
-
tools/
|
|
303
|
-
helpers.ts # Shared formatting utilities
|
|
304
|
-
contacts.ts # 7 contact tools
|
|
305
|
-
properties.ts # 5 property tools
|
|
306
|
-
tasks.ts # 3 task tools (polymorphic: note/todo/event/cancel)
|
|
307
|
-
deals.ts # 3 deal pipeline tools
|
|
308
|
-
search-profiles.ts # 4 search profile tools
|
|
309
|
-
projects.ts # 2 project tools
|
|
310
|
-
activities.ts # 2 activity/event tools
|
|
311
|
-
emails.ts # 2 email tools
|
|
312
|
-
documents.ts # 2 document tools
|
|
313
|
-
relationships.ts # 2 relationship tools (ownership/partnership)
|
|
314
|
-
lookups.ts # 8 lookup/config tools
|
|
315
|
-
composites.ts # 5 smart composite tools
|
|
316
|
-
admin.ts # 5 admin tools (webhooks, export, favorites)
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
## License
|
|
320
|
-
|
|
321
|
-
MIT
|
|
1
|
+
# Propstack MCP Server
|
|
2
|
+
|
|
3
|
+
Connect AI assistants (Claude, ChatGPT) to your Propstack real estate CRM.
|
|
4
|
+
|
|
5
|
+
> **Verbinden Sie KI-Assistenten mit Ihrem Propstack-CRM** — Kontakte verwalten, Objekte durchsuchen, Deals pflegen, Besichtigungen planen und Suchprofile erstellen, alles per Sprache oder Chat.
|
|
6
|
+
|
|
7
|
+
## What you can do / Was Sie damit machen koennen
|
|
8
|
+
|
|
9
|
+
- **Contact management** — search, create, update, and tag contacts with GDPR tracking
|
|
10
|
+
- **Property search & management** — filter by price, rooms, area, status; create and update listings
|
|
11
|
+
- **Deal pipeline** — create deals, move through stages, track win/loss rates
|
|
12
|
+
- **Buyer matching** — create search profiles from natural language ("3-Zimmer in Berlin, bis 400k, mit Balkon") and auto-match to new listings
|
|
13
|
+
- **Task & calendar** — log call notes, set follow-up reminders, schedule viewings
|
|
14
|
+
- **Email** — send templated emails linked to contacts and properties
|
|
15
|
+
- **360-degree contact view** — get a complete briefing before every call
|
|
16
|
+
- **Pipeline dashboards** — deal counts and values per stage, stale deal alerts
|
|
17
|
+
- **Lead intake** — one-call workflow: dedup, create contact, log notes, create deal, set reminder
|
|
18
|
+
- **Bulk export** — full data dumps for reporting, backup, or migration
|
|
19
|
+
|
|
20
|
+
## Quick Start
|
|
21
|
+
|
|
22
|
+
### 1. Set your API key
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
export PROPSTACK_API_KEY=your_api_key_here
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### 2a. Claude Desktop
|
|
29
|
+
|
|
30
|
+
Add to your Claude Desktop config (`claude_desktop_config.json`):
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"mcpServers": {
|
|
35
|
+
"propstack": {
|
|
36
|
+
"command": "npx",
|
|
37
|
+
"args": ["-y", "propstack-mcp-server"],
|
|
38
|
+
"env": {
|
|
39
|
+
"PROPSTACK_API_KEY": "your_api_key_here"
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### 2b. Claude Code (CLI)
|
|
47
|
+
|
|
48
|
+
Add to your project's `.mcp.json`:
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"mcpServers": {
|
|
53
|
+
"propstack": {
|
|
54
|
+
"command": "npx",
|
|
55
|
+
"args": ["-y", "propstack-mcp-server"],
|
|
56
|
+
"env": {
|
|
57
|
+
"PROPSTACK_API_KEY": "your_api_key_here"
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### 2c. ChatGPT
|
|
65
|
+
|
|
66
|
+
1. Go to **Settings > Connectors > Developer Mode**
|
|
67
|
+
2. Add a new MCP connector
|
|
68
|
+
3. Set the command to `npx -y propstack-mcp-server`
|
|
69
|
+
4. Add environment variable `PROPSTACK_API_KEY`
|
|
70
|
+
|
|
71
|
+
### 2d. Cursor IDE
|
|
72
|
+
|
|
73
|
+
1. Open **Settings** (Ctrl+,) → search "MCP"
|
|
74
|
+
2. Edit **MCP Servers** JSON, or add `mcp.json` in project root / `.cursor/`
|
|
75
|
+
|
|
76
|
+
**Option A — local project** (after `npm run build`):
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"mcpServers": {
|
|
81
|
+
"propstack": {
|
|
82
|
+
"command": "node",
|
|
83
|
+
"args": ["./dist/index.js"],
|
|
84
|
+
"cwd": "C:/Users/you/path/to/propstack_mcp",
|
|
85
|
+
"env": {
|
|
86
|
+
"PROPSTACK_API_KEY": "your_api_key_here"
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Or use `.env` in project root — the server loads it automatically; you can omit the `env` block.
|
|
94
|
+
|
|
95
|
+
**Option B — npx** (published package or `npx` from local):
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"mcpServers": {
|
|
100
|
+
"propstack": {
|
|
101
|
+
"command": "npx",
|
|
102
|
+
"args": ["-y", "propstack-mcp-server"],
|
|
103
|
+
"env": {
|
|
104
|
+
"PROPSTACK_API_KEY": "your_api_key_here"
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### 2e. Run directly
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
npm install propstack-mcp-server
|
|
115
|
+
PROPSTACK_API_KEY=your_key npx propstack-mcp-server
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## API Key / API-Schluessel
|
|
119
|
+
|
|
120
|
+
Get your Propstack API key:
|
|
121
|
+
|
|
122
|
+
1. Log in to [crm.propstack.de](https://crm.propstack.de)
|
|
123
|
+
2. Go to **Verwaltung > API-Schluessel** (Administration > API Keys)
|
|
124
|
+
3. Create or copy your V1 API key
|
|
125
|
+
|
|
126
|
+
> **Hinweis:** Der API-Schluessel bestimmt die Berechtigungen. Stellen Sie sicher, dass Lese- und Schreibzugriff fuer die benoetigten Endpunkte aktiviert ist.
|
|
127
|
+
|
|
128
|
+
## Available Tools (50)
|
|
129
|
+
|
|
130
|
+
### Contacts (Kontakte)
|
|
131
|
+
|
|
132
|
+
| Tool | Description |
|
|
133
|
+
|---|---|
|
|
134
|
+
| `search_contacts` | Search and filter contacts by name, email, phone, status, tags, broker, GDPR status |
|
|
135
|
+
| `get_contact` | Get full details of a single contact with related data |
|
|
136
|
+
| `create_contact` | Create a new contact (auto-dedup by email) |
|
|
137
|
+
| `update_contact` | Update contact details, tags, GDPR status, broker assignment |
|
|
138
|
+
| `delete_contact` | Soft-delete a contact (30-day recycle bin) |
|
|
139
|
+
| `get_contact_sources` | List lead sources (ImmoScout24, Website, Empfehlung, etc.) |
|
|
140
|
+
| `search_contacts_by_phone` | Look up a contact by phone number (formatting-insensitive) |
|
|
141
|
+
|
|
142
|
+
### Properties (Objekte)
|
|
143
|
+
|
|
144
|
+
| Tool | Description |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `search_properties` | Search properties with 11 range filters, 17 sort fields |
|
|
147
|
+
| `get_property` | Get full property details including media and custom fields |
|
|
148
|
+
| `create_property` | Create a new property listing |
|
|
149
|
+
| `update_property` | Update price, status, description, broker assignment |
|
|
150
|
+
| `get_property_statuses` | List property statuses (Verfuegbar, Reserviert, Verkauft, etc.) |
|
|
151
|
+
|
|
152
|
+
### Tasks (Aufgaben & Notizen)
|
|
153
|
+
|
|
154
|
+
| Tool | Description |
|
|
155
|
+
|---|---|
|
|
156
|
+
| `create_task` | Create a note, to-do, appointment, or cancellation (polymorphic) |
|
|
157
|
+
| `update_task` | Mark done, reschedule, update notes |
|
|
158
|
+
| `get_task` | Get task details with linked contacts, properties, projects |
|
|
159
|
+
|
|
160
|
+
### Deals (Pipeline)
|
|
161
|
+
|
|
162
|
+
| Tool | Description |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `search_deals` | Search deals by stage, pipeline, category, broker, feeling score |
|
|
165
|
+
| `create_deal` | Link a contact to a property at a pipeline stage |
|
|
166
|
+
| `update_deal` | Move deal through pipeline stages, update price/notes |
|
|
167
|
+
|
|
168
|
+
### Search Profiles (Suchprofile)
|
|
169
|
+
|
|
170
|
+
| Tool | Description |
|
|
171
|
+
|---|---|
|
|
172
|
+
| `list_search_profiles` | List what buyers/renters are looking for |
|
|
173
|
+
| `create_search_profile` | Capture buyer criteria from natural language |
|
|
174
|
+
| `update_search_profile` | Adjust budget, cities, room count, features |
|
|
175
|
+
| `delete_search_profile` | Remove a search profile |
|
|
176
|
+
|
|
177
|
+
### Projects (Projekte)
|
|
178
|
+
|
|
179
|
+
| Tool | Description |
|
|
180
|
+
|---|---|
|
|
181
|
+
| `list_projects` | List development projects with unit counts |
|
|
182
|
+
| `get_project` | Get project details with all units, media, documents |
|
|
183
|
+
|
|
184
|
+
### Activities & Events (Aktivitaeten & Termine)
|
|
185
|
+
|
|
186
|
+
| Tool | Description |
|
|
187
|
+
|---|---|
|
|
188
|
+
| `search_activities` | Full activity timeline for a contact, property, or project |
|
|
189
|
+
| `list_events` | Calendar events — viewings, meetings, filtered by date/state |
|
|
190
|
+
|
|
191
|
+
### Emails (E-Mails)
|
|
192
|
+
|
|
193
|
+
| Tool | Description |
|
|
194
|
+
|---|---|
|
|
195
|
+
| `send_email` | Send email using a Propstack template (snippet) |
|
|
196
|
+
| `update_email` | Mark read/archived, categorize, link to CRM records |
|
|
197
|
+
|
|
198
|
+
### Documents (Dokumente)
|
|
199
|
+
|
|
200
|
+
| Tool | Description |
|
|
201
|
+
|---|---|
|
|
202
|
+
| `list_documents` | List files attached to a property, project, or contact |
|
|
203
|
+
| `upload_document` | Upload a document (base64 data URI) |
|
|
204
|
+
|
|
205
|
+
### Relationships (Beziehungen)
|
|
206
|
+
|
|
207
|
+
| Tool | Description |
|
|
208
|
+
|---|---|
|
|
209
|
+
| `create_ownership` | Link a contact as property owner (Eigentuemer) |
|
|
210
|
+
| `create_partnership` | Link a contact as buyer, tenant, etc. (Kaeufer, Mieter) |
|
|
211
|
+
|
|
212
|
+
### Lookups (Konfiguration)
|
|
213
|
+
|
|
214
|
+
| Tool | Description |
|
|
215
|
+
|---|---|
|
|
216
|
+
| `list_pipelines` | Get deal pipelines with stages (IDs, names, positions) |
|
|
217
|
+
| `get_pipeline` | Get a single pipeline with stage details |
|
|
218
|
+
| `list_tags` | List tags/groups (Merkmale) — filter contacts by group IDs |
|
|
219
|
+
| `create_tag` | Create a new tag for contacts, properties, or activities |
|
|
220
|
+
| `list_activity_types` | List note/todo/event templates for create_task |
|
|
221
|
+
| `list_contact_statuses` | List contact statuses for search/assign |
|
|
222
|
+
| `list_reservation_reasons` | List deal cancellation reasons |
|
|
223
|
+
| `list_custom_fields` | Discover custom field definitions (names, types, options) |
|
|
224
|
+
| `list_users` | List all brokers/agents with contact info |
|
|
225
|
+
| `list_teams` | List teams/departments with member assignments |
|
|
226
|
+
| `list_locations` | List geographic areas (Geolagen) for location matching |
|
|
227
|
+
|
|
228
|
+
### Smart Composites (Intelligente Workflows)
|
|
229
|
+
|
|
230
|
+
| Tool | Description |
|
|
231
|
+
|---|---|
|
|
232
|
+
| `full_contact_360` | Complete contact dossier — info, search profiles, deals, activity |
|
|
233
|
+
| `property_performance_report` | Days on market, inquiry count, pipeline breakdown, activity summary |
|
|
234
|
+
| `pipeline_summary` | Deals per stage, total values, stale deals needing attention |
|
|
235
|
+
| `smart_lead_intake` | Full lead workflow: dedup, create/update, log notes, deal, reminder |
|
|
236
|
+
| `match_contacts_to_property` | Find buyers whose search profiles match a property |
|
|
237
|
+
|
|
238
|
+
### Admin (Verwaltung)
|
|
239
|
+
|
|
240
|
+
| Tool | Description |
|
|
241
|
+
|---|---|
|
|
242
|
+
| `list_webhooks` | List all configured webhook subscriptions |
|
|
243
|
+
| `create_webhook` | Subscribe to CRM events (CLIENT_CREATED, PROPERTY_UPDATED, etc.) |
|
|
244
|
+
| `delete_webhook` | Remove a webhook subscription |
|
|
245
|
+
| `export_data` | Bulk export an entire data table as JSON |
|
|
246
|
+
| `get_contact_favorites` | Get properties a contact has favorited |
|
|
247
|
+
|
|
248
|
+
## Example Conversations / Beispiel-Konversationen
|
|
249
|
+
|
|
250
|
+
### Morning Briefing / Morgen-Briefing
|
|
251
|
+
|
|
252
|
+
> **You:** What's on my calendar today?
|
|
253
|
+
>
|
|
254
|
+
> **AI:** *calls `list_events` with today's date range* — You have 3 viewings scheduled...
|
|
255
|
+
|
|
256
|
+
> **Du:** Gibt es neue Leads seit gestern?
|
|
257
|
+
>
|
|
258
|
+
> **KI:** *ruft `search_contacts` mit created_at_from=gestern auf* — 5 neue Kontakte...
|
|
259
|
+
|
|
260
|
+
### Lead Intake / Leaderfassung
|
|
261
|
+
|
|
262
|
+
> **You:** I just got off the phone with Maria Schmidt, +49 157 1234 5678. She's looking for a 3-room apartment in Berlin, budget 300-400k, must have a balcony. She found us on ImmoScout.
|
|
263
|
+
>
|
|
264
|
+
> **AI:** *calls `smart_lead_intake`* — Contact created (ID: 4521), call note logged, follow-up reminder set for tomorrow 9:00. Would you like me to create a search profile for her criteria?
|
|
265
|
+
|
|
266
|
+
### Property Matching / Objekt-Matching
|
|
267
|
+
|
|
268
|
+
> **Du:** Wir haben ein neues Listing: 3-Zimmer-Wohnung in Charlottenburg, 385.000 EUR. Wer kommt als Kaeufer in Frage?
|
|
269
|
+
>
|
|
270
|
+
> **KI:** *ruft `match_contacts_to_property` auf* — 12 passende Suchprofile gefunden. Top 3: Herr Weber (Score 95%), Frau Mueller (Score 88%), Herr Kim (Score 85%)...
|
|
271
|
+
|
|
272
|
+
### Pipeline Review
|
|
273
|
+
|
|
274
|
+
> **You:** How's our sales pipeline looking? Any stale deals?
|
|
275
|
+
>
|
|
276
|
+
> **AI:** *calls `pipeline_summary`* — 47 active deals, total value 12.3M EUR. 5 deals haven't been updated in 14+ days...
|
|
277
|
+
|
|
278
|
+
### Pre-Call Briefing / Vor dem Anruf
|
|
279
|
+
|
|
280
|
+
> **Du:** Gib mir alles ueber Kontakt 3847 — ich rufe gleich an.
|
|
281
|
+
>
|
|
282
|
+
> **KI:** *ruft `full_contact_360` auf* — Herr Weber, Rating 3 Sterne, sucht 3-Zimmer in Berlin/Potsdam bis 400k. 2 aktive Deals, letzte Aktivitaet vor 3 Tagen...
|
|
283
|
+
|
|
284
|
+
## Development
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
git clone <repo-url>
|
|
288
|
+
cd propstack-mcp-server
|
|
289
|
+
npm install
|
|
290
|
+
npm run build # tsc → dist/
|
|
291
|
+
npm start # requires PROPSTACK_API_KEY
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
### Project Structure
|
|
295
|
+
|
|
296
|
+
```
|
|
297
|
+
src/
|
|
298
|
+
index.ts # Server entry point (stdio transport)
|
|
299
|
+
propstack-client.ts # HTTP client with auth, retry, error handling
|
|
300
|
+
types/
|
|
301
|
+
propstack.ts # TypeScript interfaces for all API responses
|
|
302
|
+
tools/
|
|
303
|
+
helpers.ts # Shared formatting utilities
|
|
304
|
+
contacts.ts # 7 contact tools
|
|
305
|
+
properties.ts # 5 property tools
|
|
306
|
+
tasks.ts # 3 task tools (polymorphic: note/todo/event/cancel)
|
|
307
|
+
deals.ts # 3 deal pipeline tools
|
|
308
|
+
search-profiles.ts # 4 search profile tools
|
|
309
|
+
projects.ts # 2 project tools
|
|
310
|
+
activities.ts # 2 activity/event tools
|
|
311
|
+
emails.ts # 2 email tools
|
|
312
|
+
documents.ts # 2 document tools
|
|
313
|
+
relationships.ts # 2 relationship tools (ownership/partnership)
|
|
314
|
+
lookups.ts # 8 lookup/config tools
|
|
315
|
+
composites.ts # 5 smart composite tools
|
|
316
|
+
admin.ts # 5 admin tools (webhooks, export, favorites)
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
## License
|
|
320
|
+
|
|
321
|
+
MIT
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"activities.d.ts","sourceRoot":"","sources":["../../src/tools/activities.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAyE9D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,
|
|
1
|
+
{"version":3,"file":"activities.d.ts","sourceRoot":"","sources":["../../src/tools/activities.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAyE9D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAsItF"}
|
package/dist/tools/activities.js
CHANGED
|
@@ -159,14 +159,15 @@ Event states:
|
|
|
159
159
|
.describe("Results per page (default: 25)"),
|
|
160
160
|
}, async (args) => {
|
|
161
161
|
try {
|
|
162
|
-
const
|
|
163
|
-
|
|
162
|
+
const raw = await client.get("/events", { params: args });
|
|
163
|
+
const events = raw.events ?? [];
|
|
164
|
+
if (events.length === 0) {
|
|
164
165
|
return textResult("No events found matching your criteria.");
|
|
165
166
|
}
|
|
166
|
-
const header =
|
|
167
|
-
? `Found ${
|
|
168
|
-
: `Found ${
|
|
169
|
-
const formatted =
|
|
167
|
+
const header = raw.meta?.total_count !== undefined
|
|
168
|
+
? `Found ${raw.meta.total_count} events (showing ${events.length}):\n\n`
|
|
169
|
+
: `Found ${events.length} events:\n\n`;
|
|
170
|
+
const formatted = events.map(formatEvent).join("\n\n---\n\n");
|
|
170
171
|
return textResult(header + formatted);
|
|
171
172
|
}
|
|
172
173
|
catch (err) {
|