@talkspresso/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,130 @@
+# @talkspresso/mcp-server
+
+Manage your Talkspresso business through Claude, ChatGPT, or any MCP-compatible AI assistant.
+
+## What it does
+
+This MCP server lets Talkspresso providers control their business through conversational AI. Check your schedule, manage bookings, update services, view earnings, and more without leaving your AI chat.
+
+Perfect for creators, coaches, and consultants who want to manage their Talkspresso business hands-free.
+
+## Quick setup
+
+### 1. Get your API key
+
+Go to [app.talkspresso.com/settings/api-keys](https://app.talkspresso.com/settings/api-keys) and generate a new API key.
+
+### 2. Install the package
+
+```bash
+npm install -g @talkspresso/mcp-server
+```
+
+Or use it directly with npx (no install needed):
+
+```bash
+npx @talkspresso/mcp-server
+```
+
+### 3. Configure your AI assistant
+
+#### For Claude Desktop
+
+Add this to your Claude Desktop config file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "talkspresso": {
+      "command": "npx",
+      "args": ["-y", "@talkspresso/mcp-server"],
+      "env": {
+        "TALKSPRESSO_API_KEY": "tsp_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Then restart Claude Desktop.
+
+#### For Claude Code
+
+Add this to your Claude Code settings (`.claude/settings.json` in your project):
+
+```json
+{
+  "mcpServers": {
+    "talkspresso": {
+      "command": "npx",
+      "args": ["-y", "@talkspresso/mcp-server"],
+      "env": {
+        "TALKSPRESSO_API_KEY": "tsp_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Available tools
+
+### Appointments
+- **list-appointments** - View your upcoming or completed appointments with filters
+- **get-appointment** - Get details about a specific appointment
+- **get-pending-bookings** - See all bookings waiting for your approval
+- **approve-appointment** - Approve a pending booking
+- **decline-appointment** - Decline a booking with optional reason
+
+### Clients
+- **list-clients** - View all your clients with search
+- **get-client** - Get client details and booking history
+
+### Services
+- **list-services** - View all your service offerings
+- **create-service** - Create a new service (video call, workshop, webinar, etc.)
+- **update-service** - Update pricing, description, or status
+
+### Earnings
+- **get-earnings** - View your transaction history and earnings
+
+### Profile
+- **get-profile** - View your profile information
+- **update-profile** - Update your title, bio, categories, etc.
+- **get-schedule** - Quick view of your next 50 appointments
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TALKSPRESSO_API_KEY` | Yes | - | Your API key from app.talkspresso.com |
+| `TALKSPRESSO_API_URL` | No | `https://api.talkspresso.com` | API base URL (use for staging/testing) |
+
+## Example conversations
+
+"Show me my appointments for today"
+"Who are my top clients?"
+"Create a new 30-minute coaching call for $100"
+"What are my total earnings this month?"
+"Approve all pending bookings"
+
+## Troubleshooting
+
+**"TALKSPRESSO_API_KEY environment variable is required"**
+You need to add your API key to the config file. Get one at [app.talkspresso.com/settings/api-keys](https://app.talkspresso.com/settings/api-keys).
+
+**"API request failed"**
+Check that your API key is valid and hasn't been revoked. You can generate a new one in your settings.
+
+**Tools not showing up in Claude**
+Restart Claude Desktop after adding the config. Make sure the JSON is valid (no trailing commas).
+
+## Support
+
+Questions? Email [support@talkspresso.com](mailto:support@talkspresso.com) or visit [help.talkspresso.com](https://help.talkspresso.com).
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+export declare class TalkspressoClient {
+    private http;
+    constructor();
+    get<T = any>(path: string, params?: Record<string, any>): Promise<T>;
+    post<T = any>(path: string, data?: any): Promise<T>;
+    put<T = any>(path: string, data?: any): Promise<T>;
+    delete<T = any>(path: string): Promise<T>;
+    private formatError;
+}

package/dist/client.js

@@ -0,0 +1,61 @@
+import axios from 'axios';
+export class TalkspressoClient {
+    http;
+    constructor() {
+        const apiKey = process.env.TALKSPRESSO_API_KEY;
+        if (!apiKey) {
+            throw new Error('TALKSPRESSO_API_KEY environment variable is required. Generate one at https://app.talkspresso.com/settings/api-keys');
+        }
+        const baseURL = process.env.TALKSPRESSO_API_URL || 'https://api.talkspresso.com';
+        this.http = axios.create({
+            baseURL,
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            timeout: 30000,
+        });
+    }
+    async get(path, params) {
+        try {
+            const response = await this.http.get(path, { params });
+            return response.data?.data ?? response.data;
+        }
+        catch (err) {
+            throw this.formatError(err);
+        }
+    }
+    async post(path, data) {
+        try {
+            const response = await this.http.post(path, data);
+            return response.data?.data ?? response.data;
+        }
+        catch (err) {
+            throw this.formatError(err);
+        }
+    }
+    async put(path, data) {
+        try {
+            const response = await this.http.put(path, data);
+            return response.data?.data ?? response.data;
+        }
+        catch (err) {
+            throw this.formatError(err);
+        }
+    }
+    async delete(path) {
+        try {
+            const response = await this.http.delete(path);
+            return response.data?.data ?? response.data;
+        }
+        catch (err) {
+            throw this.formatError(err);
+        }
+    }
+    formatError(err) {
+        const data = err.response?.data;
+        const status = err.response?.status;
+        const message = data?.error || err.message || 'API request failed';
+        return new Error(`Talkspresso API error (${status}): ${message}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { TalkspressoClient } from './client.js';
+import { registerAppointmentTools } from './tools/appointments.js';
+import { registerClientTools } from './tools/clients.js';
+import { registerServiceTools } from './tools/services.js';
+import { registerEarningsTools } from './tools/earnings.js';
+import { registerProfileTools } from './tools/profile.js';
+const server = new McpServer({
+    name: 'talkspresso',
+    version: '1.0.0',
+});
+const apiClient = new TalkspressoClient();
+registerAppointmentTools(server, apiClient);
+registerClientTools(server, apiClient);
+registerServiceTools(server, apiClient);
+registerEarningsTools(server, apiClient);
+registerProfileTools(server, apiClient);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/appointments.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TalkspressoClient } from '../client.js';
+export declare function registerAppointmentTools(server: McpServer, client: TalkspressoClient): void;

package/dist/tools/appointments.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+export function registerAppointmentTools(server, client) {
+    server.tool('list-appointments', 'Get your appointments with optional filters. Returns upcoming appointments by default.', {
+        status: z.enum(['upcoming', 'completed', 'all']).optional().describe('Filter by appointment status (default: upcoming)'),
+        page: z.number().optional().describe('Page number for pagination'),
+        limit: z.number().optional().describe('Number of results per page'),
+    }, async (params) => {
+        const data = await client.get('/appointments/me', params);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('get-appointment', 'Get detailed information about a specific appointment', {
+        id: z.string().describe('The appointment ID'),
+    }, async (params) => {
+        const data = await client.get(`/appointments/${params.id}`);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('get-pending-bookings', 'Get all pending bookings that need your approval', {}, async () => {
+        const data = await client.get('/appointments/pending');
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('approve-appointment', 'Approve a pending booking request', {
+        id: z.string().describe('The appointment ID to approve'),
+    }, async (params) => {
+        const data = await client.post(`/appointments/${params.id}/approve`);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('decline-appointment', 'Decline a pending booking request', {
+        id: z.string().describe('The appointment ID to decline'),
+        decline_reason: z.string().optional().describe('Optional reason for declining'),
+    }, async (params) => {
+        const data = await client.post(`/appointments/${params.id}/decline`, {
+            decline_reason: params.decline_reason,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('create-appointment', 'Create an appointment and send an invitation to the client. Use list-clients first to find the client by name if needed. Use list-services to find a service_id if linking to a specific service.', {
+        client_name: z.string().describe('Client full name'),
+        client_email: z.string().optional().describe('Client email address (invitation sent here)'),
+        scheduled_date: z.string().describe('Date in YYYY-MM-DD format'),
+        scheduled_time: z.string().describe('Time in HH:mm format (24-hour, provider timezone)'),
+        service_id: z.string().optional().describe('Service ID to use (determines duration and price). Use list-services to find this.'),
+        duration: z.number().optional().describe('Duration in minutes (required if no service_id, default 30)'),
+        custom_title: z.string().optional().describe('Custom session title (overrides service title)'),
+        custom_price: z.number().optional().describe('Price in dollars (required if no service_id and not complimentary)'),
+        is_complimentary: z.boolean().optional().describe('If true, session is free (default: true)'),
+        invitation_message: z.string().optional().describe('Personal message included in the invitation email'),
+    }, async (params) => {
+        const data = await client.post('/appointments/invite', {
+            client_name: params.client_name,
+            client_email: params.client_email,
+            service_id: params.service_id,
+            scheduled_date: params.scheduled_date,
+            scheduled_time: params.scheduled_time,
+            duration: params.duration,
+            custom_title: params.custom_title,
+            custom_price: params.custom_price,
+            is_complimentary: params.is_complimentary ?? true,
+            invitation_message: params.invitation_message,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('cancel-appointment', 'Cancel an appointment', {
+        id: z.string().describe('The appointment ID to cancel'),
+    }, async (params) => {
+        const data = await client.post(`/appointments/${params.id}/cancel`);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('reschedule-appointment', 'Reschedule an appointment to a new date and time', {
+        id: z.string().describe('The appointment ID to reschedule'),
+        start_time: z.string().describe('New start time as ISO 8601 string (e.g. 2026-02-20T10:00:00-06:00)'),
+        end_time: z.string().describe('New end time as ISO 8601 string (e.g. 2026-02-20T11:00:00-06:00)'),
+    }, async (params) => {
+        const data = await client.post(`/appointments/${params.id}/reschedule`, {
+            start_time: params.start_time,
+            end_time: params.end_time,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/dist/tools/clients.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TalkspressoClient } from '../client.js';
+export declare function registerClientTools(server: McpServer, client: TalkspressoClient): void;

package/dist/tools/clients.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export function registerClientTools(server, client) {
+    server.tool('list-clients', 'Get your list of clients with optional search', {
+        search: z.string().optional().describe('Search clients by name or email'),
+        page: z.number().optional().describe('Page number for pagination'),
+        limit: z.number().optional().describe('Number of results per page'),
+    }, async (params) => {
+        const data = await client.get('/client/my', params);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('get-client', 'Get detailed information about a client including their booking history', {
+        id: z.string().describe('The client ID'),
+    }, async (params) => {
+        const data = await client.get(`/client/${params.id}/appointments`);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/dist/tools/earnings.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TalkspressoClient } from '../client.js';
+export declare function registerEarningsTools(server: McpServer, client: TalkspressoClient): void;

package/dist/tools/earnings.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export function registerEarningsTools(server, client) {
+    server.tool('get-earnings', 'Get your earnings and transaction history', {
+        transaction_type: z.string().optional().describe('Filter by transaction type (e.g., payment, refund)'),
+        page: z.number().optional().describe('Page number for pagination'),
+        limit: z.number().optional().describe('Number of results per page'),
+    }, async (params) => {
+        const data = await client.get('/transaction/my', params);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/dist/tools/profile.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TalkspressoClient } from '../client.js';
+export declare function registerProfileTools(server: McpServer, client: TalkspressoClient): void;

package/dist/tools/profile.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export function registerProfileTools(server, client) {
+    server.tool('get-profile', 'Get your Talkspresso profile information', {}, async () => {
+        const data = await client.get('/profile/me');
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('update-profile', 'Update your Talkspresso profile', {
+        expert_title: z.string().optional().describe('Your professional title (e.g., "Executive Coach")'),
+        about: z.string().optional().describe('Short about text'),
+        bio: z.string().optional().describe('Full bio'),
+        categories: z.array(z.string()).optional().describe('Array of category strings (e.g., ["coaching", "consulting"])'),
+    }, async (params) => {
+        const data = await client.put('/profile', params);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('get-schedule', 'Get your upcoming schedule (next 50 appointments)', {}, async () => {
+        const data = await client.get('/appointments/me', { status: 'upcoming', limit: 50 });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/dist/tools/services.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TalkspressoClient } from '../client.js';
+export declare function registerServiceTools(server: McpServer, client: TalkspressoClient): void;

package/dist/tools/services.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export function registerServiceTools(server, client) {
+    server.tool('list-services', 'Get all your services (video calls, workshops, etc.)', {}, async () => {
+        const data = await client.get('/service/me');
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('create-service', 'Create a new service offering', {
+        title: z.string().describe('Service title'),
+        description: z.string().describe('Service description'),
+        price: z.number().describe('Price in dollars (e.g., 100 for $100)'),
+        duration: z.number().describe('Duration in minutes'),
+        type: z.enum(['video_call', 'group_session', 'workshop', 'webinar']).describe('Type of service'),
+    }, async (params) => {
+        const data = await client.post('/service', params);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool('update-service', 'Update an existing service', {
+        id: z.string().describe('Service ID to update'),
+        title: z.string().optional().describe('New title'),
+        description: z.string().optional().describe('New description'),
+        price: z.number().optional().describe('New price in dollars'),
+        duration: z.number().optional().describe('New duration in minutes'),
+        status: z.enum(['active', 'inactive']).optional().describe('Service status'),
+    }, async (params) => {
+        const { id, ...updateData } = params;
+        const data = await client.put(`/service/${id}`, updateData);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@talkspresso/mcp-server",
+  "version": "1.0.0",
+  "description": "Manage your Talkspresso business through Claude, ChatGPT, or any MCP-compatible AI",
+  "bin": {
+    "talkspresso-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "talkspresso", "ai", "claude", "chatgpt"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "axios": "^1.7.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "tsx": "^4.0.0",
+    "@types/node": "^22.0.0"
+  },
+  "files": [
+    "dist/**/*"
+  ]
+}