viviscape-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ViviScape LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# viviscape-mcp
+
+MCP server for the [ViviScape](https://viviscape.io) API — exposes CRM, projects, companies, tasks, time tracking, notes, and insights as tools for Claude and other MCP clients.
+
+## Installation
+
+No install needed — run via `npx`:
+
+```bash
+npx viviscape-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g viviscape-mcp
+```
+
+## Configuration
+
+Set the following environment variables:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VIVISCAPE_API_KEY` | yes | — | Your ViviScape API key |
+| `VIVISCAPE_API_URL` | no | `https://api.viviscape.io` | API base URL |
+
+## Claude Desktop / Claude Code
+
+Add to your MCP client config (e.g. `claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "viviscape": {
+      "command": "npx",
+      "args": ["-y", "viviscape-mcp"],
+      "env": {
+        "VIVISCAPE_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+The server exposes tools across these domains:
+
+- **Prospects** — `prospect_add`, `prospect_get`, `prospect_update`, `prospect_query`, follow-ups, notes
+- **Clients** — `client_add`, `client_get`, `client_get_by_email`, `clients_by_company`
+- **Companies** — `company_add`, `company_list`, `company_update`
+- **Projects** — `project_get`, `project_list`, `project_list_active`, `project_staff`, `project_tasks`, `projects_by_company`
+- **Tasks** — `task_add`, `task_get`, `task_update`, `tasks_open`, `tasks_pending`, `tasks_by_company`, `tasks_by_milestone`
+- **Time logs** — `timelog_add`, `timelog_update`
+- **Notes** — `note_add`, `note_get`, `note_update`, `note_remove`, `notes_mine`, `notes_query`
+- **Insights** — hours by person/service/project, AI summary, person stats, time totals
+- **Account** — `account_info`, `account_services`, `account_users`
+
+## Development
+
+```bash
+npm install
+npm run dev      # run with tsx, hot reload
+npm run build    # compile to dist/
+npm start        # run compiled
+```
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,69 @@
+export declare class ViviScapeClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private request;
+    addProspect(data: Record<string, unknown>): Promise<unknown>;
+    updateProspect(data: Record<string, unknown>): Promise<unknown>;
+    getProspect(prospectId: number): Promise<unknown>;
+    getProspectsByRep(repId: number): Promise<unknown>;
+    getProspectsByAccount(): Promise<unknown>;
+    queryProspects(query?: string, accountId?: number, userId?: number, stages?: string[]): Promise<unknown>;
+    removeProspect(prospectId: number): Promise<unknown>;
+    addProspectNote(data: Record<string, unknown>): Promise<unknown>;
+    updateProspectNote(data: Record<string, unknown>): Promise<unknown>;
+    getProspectNotes(prospectId: number): Promise<unknown>;
+    removeProspectNote(noteId: number): Promise<unknown>;
+    addFollowup(data: Record<string, unknown>): Promise<unknown>;
+    updateFollowup(data: Record<string, unknown>): Promise<unknown>;
+    getFollowups(prospectId: number): Promise<unknown>;
+    listCompanies(): Promise<unknown>;
+    addCompany(data: Record<string, unknown>): Promise<unknown>;
+    updateCompany(data: Record<string, unknown>): Promise<unknown>;
+    getClientsByCompany(companyId: number): Promise<unknown>;
+    addClient(data: Record<string, unknown>): Promise<unknown>;
+    getClientById(clientId: number): Promise<unknown>;
+    getClientByEmail(data: {
+        email: string;
+    }): Promise<unknown>;
+    getMyProjects(): Promise<unknown>;
+    getActiveProjects(): Promise<Record<string, unknown>[]>;
+    getProjectById(projectId: number): Promise<unknown>;
+    getProjectStaff(projectId: number): Promise<unknown>;
+    addTask(data: Record<string, unknown>): Promise<unknown>;
+    updateTask(data: Record<string, unknown>): Promise<unknown>;
+    getProjectTasks(projectId: number): Promise<unknown>;
+    getOpenTasks(): Promise<unknown>;
+    getTask(taskId: number): Promise<unknown>;
+    getPendingTasks(userId: number): Promise<unknown>;
+    getTasksByMilestone(milestoneId: number): Promise<unknown>;
+    getTasksByGroupAndUser(groupId: number, userId: number): Promise<unknown>;
+    getCompanyTasks(companyId: number): Promise<unknown>;
+    getProjectsByCompany(userId: number, companyId: number): Promise<unknown>;
+    getActiveProjectsByUser(userId: number): Promise<unknown>;
+    addTimeLog(data: Record<string, unknown>): Promise<unknown>;
+    updateTimeLog(data: Record<string, unknown>): Promise<unknown>;
+    getMyNotes(): Promise<unknown>;
+    getNoteById(noteId: number): Promise<unknown>;
+    addNote(data: Record<string, unknown>): Promise<unknown>;
+    updateNote(data: Record<string, unknown>): Promise<unknown>;
+    removeNote(noteId: number): Promise<unknown>;
+    queryNotes(data: Record<string, unknown>): Promise<unknown>;
+    getAccountInfo(): Promise<unknown>;
+    getActiveServices(): Promise<unknown>;
+    getAllServices(): Promise<unknown>;
+    getUsers(): Promise<unknown>;
+    getHoursByPerson(data: Record<string, unknown>): Promise<unknown>;
+    getTimeLogsByDateRange(data: Record<string, unknown>): Promise<unknown>;
+    getPersonStats(data: Record<string, unknown>): Promise<unknown>;
+    getHoursByPersonAndService(data: Record<string, unknown>): Promise<unknown>;
+    getAllTimeHoursByPersonAndService(data: Record<string, unknown>): Promise<unknown>;
+    getProjectHoursByService(data: Record<string, unknown>): Promise<unknown>;
+    getAccountHoursByService(data: Record<string, unknown>): Promise<unknown>;
+    getAiLogSummary(data: Record<string, unknown>): Promise<unknown>;
+    getPersonHoursThisWeek(userId: number): Promise<unknown>;
+    getPersonHoursThisMonth(userId: number): Promise<unknown>;
+    getPersonHoursLastMonth(userId: number): Promise<unknown>;
+    getProjectTimeTotal(projectId: number): Promise<unknown>;
+    getAllUsersTime(): Promise<unknown>;
+}

package/dist/api-client.js

@@ -0,0 +1,414 @@
+const DEFAULT_USER_ID = 210; // Art Hicks
+/**
+ * Parse shorthand duration (e.g., "3h", "1h30m", "45m") to HH:MM:SS TimeSpan format.
+ */
+function parseShorthandDuration(input) {
+    const raw = input.trim();
+    const hMatch = raw.match(/(\d+)\s*h/i);
+    const mMatch = raw.match(/(\d+)\s*m/i);
+    const hours = hMatch ? parseInt(hMatch[1], 10) : 0;
+    const minutes = mMatch ? parseInt(mMatch[1], 10) : 0;
+    // If already in HH:MM:SS format, pass through
+    if (/^\d{1,2}:\d{2}:\d{2}$/.test(raw)) {
+        return { duration: raw, log_time: raw };
+    }
+    const hh = String(hours).padStart(2, '0');
+    const mm = String(minutes).padStart(2, '0');
+    return { duration: `${hh}:${mm}:00`, log_time: raw };
+}
+/**
+ * Build a full Group_Task payload from simplified MCP tool params.
+ */
+function buildTaskPayload(data) {
+    const now = new Date().toISOString();
+    const assignees = [];
+    const userId = data.assigned_to ?? DEFAULT_USER_ID;
+    assignees.push({
+        assignee_id: 0,
+        task_id: 0,
+        user_id: userId,
+        client_id: 0,
+        leader: true,
+        attention: false,
+        promoting: false,
+        pinned: false,
+        notify: true,
+        active: false,
+        activitys: [],
+        duration: '00:00:00',
+        duration_friendly: '-',
+    });
+    // Convert estimated_hours shorthand to ticks (1 tick = 100ns, 1h = 36_000_000_000 ticks)
+    let estimatedTicks = 0;
+    if (data.estimated_hours) {
+        const parsed = parseShorthandDuration(String(data.estimated_hours));
+        const [h, m] = parsed.duration.split(':').map(Number);
+        estimatedTicks = ((h * 60 + m) * 60) * 10_000_000;
+    }
+    const priorityMap = { low: 1, medium: 2, high: 3, critical: 4 };
+    const priorityStr = String(data.priority || 'medium');
+    const priorityRank = priorityMap[priorityStr] ?? 2;
+    return {
+        task_id: 0,
+        group_id: data.project_id ?? 0,
+        company_id: data.company_id ?? 0,
+        service_id: data.service_id ?? 0,
+        task: data.title ?? '',
+        description: data.description ?? '',
+        notes: data.notes ?? '',
+        status: data.status ?? 'new',
+        priority: priorityStr,
+        priority_rank: priorityRank,
+        start: data.start_date ?? now,
+        end: data.due_date ?? now,
+        creation_date: now,
+        complete_date: '1901-01-01T00:00:00+00:00',
+        estimated_ticks: estimatedTicks,
+        task_type: data.task_type ?? 'task',
+        isbillable: data.isbillable ?? false,
+        creator_id: userId,
+        milestone_id: data.milestone_id ?? 0,
+        client_id: 0,
+        event_id: 0,
+        account_id: 0,
+        percentage: 0,
+        attention: false,
+        pinned: false,
+        assign_all_staff: false,
+        agg_cost: 0,
+        agg_rate: 0,
+        predecessor_id: 0,
+        predecessor_complete: false,
+        predecessor_name: '',
+        solution: '',
+        meta: '',
+        agent_id: '00000000-0000-0000-0000-000000000000',
+        unit_id: '00000000-0000-0000-0000-000000000000',
+        reviewer_id: 0,
+        review_required: false,
+        parts: '',
+        staff_assignees: assignees,
+        client_assignees: [],
+        task_files: [],
+        logs: [],
+    };
+}
+/**
+ * Build update fields for a Group_Task, mapping friendly names to API names.
+ */
+function buildTaskUpdatePayload(data) {
+    const mapped = {};
+    if (data.task_id !== undefined)
+        mapped.task_id = data.task_id;
+    if (data.title !== undefined)
+        mapped.task = data.title;
+    if (data.description !== undefined)
+        mapped.description = data.description;
+    if (data.status !== undefined)
+        mapped.status = data.status;
+    if (data.priority !== undefined) {
+        mapped.priority = data.priority;
+        const priorityMap = { low: 1, medium: 2, high: 3, critical: 4 };
+        mapped.priority_rank = priorityMap[String(data.priority)] ?? 2;
+    }
+    if (data.due_date !== undefined)
+        mapped.end = data.due_date;
+    if (data.assigned_to !== undefined) {
+        mapped.staff_assignees = [{
+                assignee_id: 0,
+                task_id: data.task_id ?? 0,
+                user_id: data.assigned_to,
+                client_id: 0,
+                leader: true,
+                attention: false,
+                promoting: false,
+                pinned: false,
+                notify: true,
+                active: false,
+                activitys: [],
+                duration: '00:00:00',
+                duration_friendly: '-',
+            }];
+    }
+    return mapped;
+}
+/**
+ * Build a full LOG_Time payload from simplified MCP tool params.
+ */
+function buildTimeLogPayload(data) {
+    const now = new Date().toISOString();
+    const durInput = String(data.duration || '0h');
+    const { duration, log_time } = parseShorthandDuration(durInput);
+    return {
+        log_id: data.log_id ?? 0,
+        account_id: data.account_id ?? 1,
+        service_id: data.service_id ?? 0,
+        user_id: data.user_id ?? DEFAULT_USER_ID,
+        company_id: data.company_id ?? 0,
+        client_id: data.client_id ?? 0,
+        group_id: data.group_id ?? 0,
+        event_id: 0,
+        topic_id: 0,
+        thread_id: 0,
+        task_id: data.task_id ?? 0,
+        duration,
+        log_time,
+        allowance: '00:00:00',
+        allowance_ticks: 0,
+        note: data.description ?? data.note ?? '',
+        log_date: data.log_date ?? now,
+        date_added: now,
+        expire_date: '0001-01-01T00:00:00',
+        isnoteonly: false,
+        cost: 0,
+        rate: 0,
+        net: 0,
+        exclude: false,
+        billable: data.billable ?? false,
+        invoiced: false,
+        invoice_id: 0,
+        lat: 0,
+        lng: 0,
+        total_cost: 0,
+        total_revenue: 0,
+        total_margin: 0,
+        agent_id: '00000000-0000-0000-0000-000000000000',
+        progress_id: '00000000-0000-0000-0000-000000000000',
+        staff: [],
+    };
+}
+export class ViviScapeClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.apiKey = apiKey;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            'ApiKey': this.apiKey,
+            'Content-Type': 'application/json',
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new Error(`API ${method} ${path} returned ${res.status}: ${text}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    // ── Prospects ──────────────────────────────────────────────
+    async addProspect(data) {
+        return this.request('POST', '/api/v1/crm/prospect/add', data);
+    }
+    async updateProspect(data) {
+        return this.request('POST', '/api/v1/crm/prospect/update', data);
+    }
+    async getProspect(prospectId) {
+        return this.request('GET', `/api/v1/crm/prospect/id/${prospectId}`);
+    }
+    async getProspectsByRep(repId) {
+        return this.request('GET', `/api/v1/crm/prospects/rep/${repId}`);
+    }
+    async getProspectsByAccount() {
+        return this.request('GET', '/api/v1/crm/prospects/account');
+    }
+    async queryProspects(query, accountId, userId, stages) {
+        return this.request('POST', '/api/v1/crm/prospects/query', {
+            query, account_id: accountId, user_id: userId, stages,
+        });
+    }
+    async removeProspect(prospectId) {
+        return this.request('GET', `/api/v1/crm/prospect/remove/${prospectId}`);
+    }
+    // ── Prospect Notes ─────────────────────────────────────────
+    async addProspectNote(data) {
+        return this.request('POST', '/api/v1/crm/prospect/note/add', data);
+    }
+    async updateProspectNote(data) {
+        return this.request('POST', '/api/v1/crm/prospect/note/update', data);
+    }
+    async getProspectNotes(prospectId) {
+        return this.request('GET', `/api/v1/crm/prospect/notes/${prospectId}`);
+    }
+    async removeProspectNote(noteId) {
+        return this.request('GET', `/api/v1/crm/prospect/note/remove/${noteId}`);
+    }
+    // ── Prospect Followups ─────────────────────────────────────
+    async addFollowup(data) {
+        return this.request('POST', '/api/v1/crm/prospect/followup/add', data);
+    }
+    async updateFollowup(data) {
+        return this.request('POST', '/api/v1/crm/prospect/followup/update', data);
+    }
+    async getFollowups(prospectId) {
+        return this.request('GET', `/api/v1/crm/prospect/followups/list/${prospectId}`);
+    }
+    // ── Companies ──────────────────────────────────────────────
+    async listCompanies() {
+        return this.request('GET', '/api/v1/companies/list');
+    }
+    async addCompany(data) {
+        return this.request('POST', '/api/v1/companies/add', data);
+    }
+    async updateCompany(data) {
+        return this.request('POST', '/api/v1/companies/update', data);
+    }
+    async getClientsByCompany(companyId) {
+        return this.request('GET', `/api/v1/companies/clients/company/${companyId}`);
+    }
+    async addClient(data) {
+        return this.request('POST', '/api/v1/companies/client/add', data);
+    }
+    async getClientById(clientId) {
+        return this.request('GET', `/api/v1/companies/client/id/${clientId}`);
+    }
+    async getClientByEmail(data) {
+        return this.request('POST', '/api/v1/companies/client/email', data);
+    }
+    // ── Projects ───────────────────────────────────────────────
+    async getMyProjects() {
+        return this.request('GET', '/api/v1/projects/user/projects');
+    }
+    async getActiveProjects() {
+        const projects = await this.request('GET', '/api/v1/projects/user/projects');
+        return projects.filter(p => p.bitActive === true);
+    }
+    async getProjectById(projectId) {
+        return this.request('GET', `/api/v1/projects/id?project_id=${projectId}`);
+    }
+    async getProjectStaff(projectId) {
+        return this.request('GET', `/api/v1/projects/project/staff?project_id=${projectId}`);
+    }
+    async addTask(data) {
+        const payload = buildTaskPayload(data);
+        return this.request('POST', '/api/v1/projects/task/add', payload);
+    }
+    async updateTask(data) {
+        if (data.task_id) {
+            const existing = await this.getTask(data.task_id);
+            const payload = { ...existing, ...buildTaskUpdatePayload(data) };
+            return this.request('POST', '/api/v1/projects/task/update', payload);
+        }
+        return this.request('POST', '/api/v1/projects/task/update', buildTaskUpdatePayload(data));
+    }
+    async getProjectTasks(projectId) {
+        return this.request('GET', `/api/v1/projects/tasks/project?project_id=${projectId}`);
+    }
+    async getOpenTasks() {
+        return this.request('POST', '/api/v1/projects/account/tasks/open', {});
+    }
+    async getTask(taskId) {
+        return this.request('GET', `/api/v1/projects/task/get?task_id=${taskId}`);
+    }
+    async getPendingTasks(userId) {
+        return this.request('GET', `/api/v1/projects/user/tasks/pending?user_id=${userId}`);
+    }
+    async getTasksByMilestone(milestoneId) {
+        return this.request('GET', `/api/v1/projects/tasks/milestones?milestone_id=${milestoneId}`);
+    }
+    async getTasksByGroupAndUser(groupId, userId) {
+        return this.request('GET', `/api/v1/projects/tasks/group/user?group_id=${groupId}&user_id=${userId}`);
+    }
+    async getCompanyTasks(companyId) {
+        return this.request('GET', `/api/v1/projects/company/tasks?company_id=${companyId}`);
+    }
+    async getProjectsByCompany(userId, companyId) {
+        return this.request('GET', `/api/v1/projects/user/projects/company?user_id=${userId}&companyid=${companyId}`);
+    }
+    async getActiveProjectsByUser(userId) {
+        return this.request('GET', `/api/v1/projects/user/projects/active?user_id=${userId}`);
+    }
+    async addTimeLog(data) {
+        const payload = buildTimeLogPayload(data);
+        return this.request('POST', '/api/v1/projects/task/logs/add', payload);
+    }
+    async updateTimeLog(data) {
+        if (data.log_id) {
+            const payload = buildTimeLogPayload(data);
+            return this.request('POST', '/api/v1/projects/task/logs/update', payload);
+        }
+        return this.request('POST', '/api/v1/projects/task/logs/update', buildTimeLogPayload(data));
+    }
+    // ── Notes ──────────────────────────────────────────────────
+    async getMyNotes() {
+        return this.request('GET', '/api/v1/notes/me');
+    }
+    async getNoteById(noteId) {
+        return this.request('GET', `/api/v1/notes/id/${noteId}`);
+    }
+    async addNote(data) {
+        return this.request('POST', '/api/v1/notes/add', data);
+    }
+    async updateNote(data) {
+        return this.request('POST', '/api/v1/notes/update', data);
+    }
+    async removeNote(noteId) {
+        return this.request('GET', `/api/v1/notes/remove/${noteId}`);
+    }
+    async queryNotes(data) {
+        return this.request('POST', '/api/v1/notes/query', data);
+    }
+    // ── Account ────────────────────────────────────────────────
+    async getAccountInfo() {
+        return this.request('GET', '/api/v1/account/info');
+    }
+    async getActiveServices() {
+        return this.request('GET', '/api/v1/account/services/active');
+    }
+    async getAllServices() {
+        return this.request('GET', '/api/v1/account/services/list');
+    }
+    async getUsers() {
+        return this.request('GET', '/api/v1/account/users');
+    }
+    // ── Insights ───────────────────────────────────────────────
+    async getHoursByPerson(data) {
+        return this.request('POST', '/api/v1/insights/logs/hours/person', data);
+    }
+    async getTimeLogsByDateRange(data) {
+        return this.request('POST', '/api/v1/insights/logs/account/daterange', data);
+    }
+    async getPersonStats(data) {
+        return this.request('POST', '/api/v1/insights/person/stats', data);
+    }
+    async getHoursByPersonAndService(data) {
+        return this.request('POST', '/api/v1/insights/logs/hours/person/service', data);
+    }
+    async getAllTimeHoursByPersonAndService(data) {
+        return this.request('POST', '/api/v1/insights/logs/hours/alltime/person/service', data);
+    }
+    async getProjectHoursByService(data) {
+        return this.request('POST', '/api/v1/insights/logs/project/hours/service', data);
+    }
+    async getAccountHoursByService(data) {
+        return this.request('POST', '/api/v1/insights/logs/account/hours/service', data);
+    }
+    async getAiLogSummary(data) {
+        return this.request('POST', '/api/v1/insights/ai/log/summary', data);
+    }
+    async getPersonHoursThisWeek(userId) {
+        return this.request('GET', `/api/v1/insights/insights/eval/person/week/${userId}`);
+    }
+    async getPersonHoursThisMonth(userId) {
+        return this.request('GET', `/api/v1/insights/eval/person/month/${userId}`);
+    }
+    async getPersonHoursLastMonth(userId) {
+        return this.request('GET', `/api/v1/insights/eval/person/lastmonth/${userId}`);
+    }
+    async getProjectTimeTotal(projectId) {
+        return this.request('GET', `/api/v1/insights/eval/project/all/${projectId}`);
+    }
+    async getAllUsersTime() {
+        return this.request('GET', '/api/v1/insights/eval/users/all');
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { config } from 'dotenv';
+import { ViviScapeClient } from './api-client.js';
+config();
+const apiUrl = process.env.VIVISCAPE_API_URL || 'https://api.viviscape.io';
+const apiKey = process.env.VIVISCAPE_API_KEY || '';
+if (!apiKey) {
+    console.error('VIVISCAPE_API_KEY is required. Set it in .env or environment.');
+    process.exit(1);
+}
+const client = new ViviScapeClient(apiUrl, apiKey);
+const server = new McpServer({
+    name: 'viviscape',
+    version: '1.0.0',
+});
+function json(data) {
+    return JSON.stringify(data, null, 2);
+}
+// ════════════════════════════════════════════════════════════
+// PROSPECTS
+// ════════════════════════════════════════════════════════════
+server.tool('prospect_add', 'Add a new prospect/lead to the ViviScape CRM', {
+    first_name: z.string().describe('First name'),
+    last_name: z.string().describe('Last name'),
+    email: z.string().describe('Email address'),
+    phone: z.string().optional().describe('Phone number'),
+    company: z.string().optional().describe('Company name'),
+    org: z.string().optional().describe('Organization'),
+    note: z.string().optional().describe('Notes about the prospect'),
+    source: z.string().optional().describe('Lead source (e.g., "Website", "ROI Calculator")'),
+    source_url: z.string().optional().describe('URL where the lead came from'),
+    referred_by: z.string().optional().describe('Referral source'),
+    status: z.string().optional().describe('Status: new, firstcontact, negotiation, pending, won, lost, spam'),
+}, async (params) => {
+    const result = await client.addProspect(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_update', 'Update an existing prospect in the CRM', {
+    prospect_id: z.number().describe('Prospect ID to update'),
+    first_name: z.string().optional(),
+    last_name: z.string().optional(),
+    email: z.string().optional(),
+    phone: z.string().optional(),
+    company: z.string().optional(),
+    org: z.string().optional(),
+    note: z.string().optional(),
+    source: z.string().optional(),
+    status: z.string().optional().describe('Status: new, firstcontact, negotiation, pending, won, lost, spam'),
+    priority: z.number().optional().describe('Priority level'),
+}, async (params) => {
+    const result = await client.updateProspect(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_get', 'Get a prospect by ID', { prospect_id: z.number().describe('Prospect ID') }, async ({ prospect_id }) => {
+    const result = await client.getProspect(prospect_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_query', 'Search/query prospects with filters', {
+    query: z.string().optional().describe('Search text (name, email, company)'),
+    account_id: z.number().optional().describe('Filter by account ID'),
+    user_id: z.number().optional().describe('Filter by user/rep ID'),
+    stages: z.array(z.string()).optional().describe('Filter by stages: new, firstcontact, negotiation, pending, won, lost, spam'),
+}, async (params) => {
+    const result = await client.queryProspects(params.query, params.account_id, params.user_id, params.stages);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_list_by_account', 'Get all prospects for the current account', {}, async () => {
+    const result = await client.getProspectsByAccount();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_list_by_rep', 'Get all prospects assigned to a specific sales rep', { rep_id: z.number().describe('Sales rep user ID') }, async ({ rep_id }) => {
+    const result = await client.getProspectsByRep(rep_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_remove', 'Remove a prospect from the CRM', { prospect_id: z.number().describe('Prospect ID to remove') }, async ({ prospect_id }) => {
+    const result = await client.removeProspect(prospect_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ════════════════════════════════════════════════════════════
+// PROSPECT NOTES
+// ════════════════════════════════════════════════════════════
+server.tool('prospect_note_add', 'Add a note to a prospect', {
+    prospect_id: z.number().describe('Prospect ID'),
+    note: z.string().describe('Note content'),
+    author: z.string().optional().describe('Author name'),
+}, async (params) => {
+    const result = await client.addProspectNote(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_note_update', 'Update a prospect note', {
+    note_id: z.number().describe('Note ID to update'),
+    note: z.string().describe('Updated note content'),
+}, async (params) => {
+    const result = await client.updateProspectNote(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_notes_list', 'Get all notes for a prospect', { prospect_id: z.number().describe('Prospect ID') }, async ({ prospect_id }) => {
+    const result = await client.getProspectNotes(prospect_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_note_remove', 'Remove a prospect note', { note_id: z.number().describe('Note ID to remove') }, async ({ note_id }) => {
+    const result = await client.removeProspectNote(note_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ════════════════════════════════════════════════════════════
+// PROSPECT FOLLOWUPS
+// ════════════════════════════════════════════════════════════
+server.tool('prospect_followup_add', 'Add a followup record for a prospect', {
+    prospect_id: z.number().describe('Prospect ID'),
+    contact_method: z.string().optional().describe('Contact method (e.g., email, phone, meeting)'),
+    outcome: z.string().optional().describe('Outcome of the followup'),
+    subject: z.string().optional().describe('Subject/title'),
+    content: z.string().optional().describe('Followup content/details'),
+    followup_date: z.string().optional().describe('Followup date (ISO 8601)'),
+}, async (params) => {
+    const result = await client.addFollowup(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_followup_update', 'Update a followup record', {
+    followup_id: z.number().describe('Followup ID to update'),
+    contact_method: z.string().optional(),
+    outcome: z.string().optional(),
+    subject: z.string().optional(),
+    content: z.string().optional(),
+    followup_date: z.string().optional(),
+}, async (params) => {
+    const result = await client.updateFollowup(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('prospect_followups_list', 'Get all followup records for a prospect', { prospect_id: z.number().describe('Prospect ID') }, async ({ prospect_id }) => {
+    const result = await client.getFollowups(prospect_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ════════════════════════════════════════════════════════════
+// COMPANIES & CLIENTS
+// ════════════════════════════════════════════════════════════
+server.tool('company_list', 'List all companies', {}, async () => {
+    const result = await client.listCompanies();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('company_add', 'Add a new company', {
+    name: z.string().describe('Company name'),
+    address1: z.string().optional(),
+    address2: z.string().optional(),
+    city: z.string().optional(),
+    state: z.string().optional(),
+    zip: z.string().optional(),
+    phone: z.string().optional(),
+    website: z.string().optional(),
+}, async (params) => {
+    const result = await client.addCompany(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('company_update', 'Update an existing company', {
+    company_id: z.number().describe('Company ID to update'),
+    name: z.string().optional(),
+    address1: z.string().optional(),
+    city: z.string().optional(),
+    state: z.string().optional(),
+    zip: z.string().optional(),
+    phone: z.string().optional(),
+    website: z.string().optional(),
+}, async (params) => {
+    const result = await client.updateCompany(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('client_get', 'Get a client by ID', { client_id: z.number().describe('Client ID') }, async ({ client_id }) => {
+    const result = await client.getClientById(client_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('client_get_by_email', 'Look up a client by email address', { email: z.string().describe('Email address') }, async ({ email }) => {
+    const result = await client.getClientByEmail({ email });
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('client_add', 'Add a new client to a company', {
+    company_id: z.number().describe('Company ID'),
+    first_name: z.string().describe('First name'),
+    last_name: z.string().describe('Last name'),
+    email: z.string().describe('Email'),
+    phone: z.string().optional(),
+    title: z.string().optional().describe('Job title'),
+}, async (params) => {
+    const result = await client.addClient(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('clients_by_company', 'Get all clients for a company', { company_id: z.number().describe('Company ID') }, async ({ company_id }) => {
+    const result = await client.getClientsByCompany(company_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ════════════════════════════════════════════════════════════
+// PROJECTS & TASKS
+// ════════════════════════════════════════════════════════════
+server.tool('project_list', 'Get all projects for current user', {}, async () => {
+    const result = await client.getMyProjects();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('project_list_active', 'Get active projects for current user', {}, async () => {
+    const result = await client.getActiveProjects();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('project_get', 'Get a project by ID', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
+    const result = await client.getProjectById(project_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('project_staff', 'Get staff members assigned to a project', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
+    const result = await client.getProjectStaff(project_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('project_tasks', 'Get all tasks for a project', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
+    const result = await client.getProjectTasks(project_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('tasks_open', 'Get all open tasks across projects', {}, async () => {
+    const result = await client.getOpenTasks();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_add', 'Add a task to a project. The API requires a full Group_Task payload; this tool builds it from simplified params.', {
+    project_id: z.number().describe('Project ID (group_id)'),
+    title: z.string().describe('Task title'),
+    description: z.string().optional().describe('Task description'),
+    notes: z.string().optional().describe('Task notes'),
+    assigned_to: z.number().optional().describe('User ID to assign to (also sets creator). Defaults to Art Hicks (210)'),
+    company_id: z.number().optional().describe('Company ID associated with the project'),
+    service_id: z.number().optional().describe('Service ID classifying the work type'),
+    priority: z.string().optional().describe('Priority: low, medium, high, critical'),
+    estimated_hours: z.string().optional().describe('Estimated time in shorthand (e.g., 6h, 2h30m)'),
+    start_date: z.string().optional().describe('Start date (ISO 8601)'),
+    due_date: z.string().optional().describe('Due date (ISO 8601)'),
+    milestone_id: z.number().optional().describe('Milestone ID'),
+}, async (params) => {
+    const result = await client.addTask(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_update', 'Update a task. Fetches existing task first and merges changes.', {
+    task_id: z.number().describe('Task ID to update'),
+    title: z.string().optional().describe('Task title'),
+    description: z.string().optional(),
+    assigned_to: z.number().optional().describe('User ID to assign to'),
+    priority: z.string().optional().describe('Priority: low, medium, high, critical'),
+    status: z.string().optional().describe('Status: new, inprogress, complete, onhold'),
+    due_date: z.string().optional().describe('Due date (ISO 8601)'),
+}, async (params) => {
+    const result = await client.updateTask(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_get', 'Get a single task by ID', { task_id: z.number().describe('Task ID') }, async ({ task_id }) => {
+    const result = await client.getTask(task_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('tasks_pending', 'Get pending tasks for a user', { user_id: z.number().describe('User ID') }, async ({ user_id }) => {
+    const result = await client.getPendingTasks(user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('tasks_by_milestone', 'Get tasks for a milestone', { milestone_id: z.number().describe('Milestone ID') }, async ({ milestone_id }) => {
+    const result = await client.getTasksByMilestone(milestone_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('tasks_by_group_user', 'Get tasks by project group and user', {
+    group_id: z.number().describe('Project group ID'),
+    user_id: z.number().describe('User ID'),
+}, async ({ group_id, user_id }) => {
+    const result = await client.getTasksByGroupAndUser(group_id, user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('tasks_by_company', 'Get tasks for a company', { company_id: z.number().describe('Company ID') }, async ({ company_id }) => {
+    const result = await client.getCompanyTasks(company_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('projects_by_company', 'Get user projects filtered by company', {
+    user_id: z.number().describe('User ID'),
+    company_id: z.number().describe('Company ID'),
+}, async ({ user_id, company_id }) => {
+    const result = await client.getProjectsByCompany(user_id, company_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('projects_active_by_user', 'Get active projects for a specific user', { user_id: z.number().describe('User ID') }, async ({ user_id }) => {
+    const result = await client.getActiveProjectsByUser(user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ════════════════════════════════════════════════════════════
+// TIME TRACKING
+// ════════════════════════════════════════════════════════════
+server.tool('timelog_add', 'Log time against a task. Duration uses shorthand format (e.g., 1h30m, 30m, 2h). Builds full LOG_Time payload.', {
+    task_id: z.number().describe('Task ID to log time against'),
+    user_id: z.number().optional().describe('User ID who performed the work. Defaults to Art Hicks (210)'),
+    duration: z.string().describe('Duration in shorthand format (e.g., 1h30m, 30m, 2h)'),
+    service_id: z.number().optional().describe('Service ID classifying the work type'),
+    group_id: z.number().optional().describe('Project/group ID'),
+    company_id: z.number().optional().describe('Company ID'),
+    log_date: z.string().optional().describe('Date of the work (ISO 8601)'),
+    description: z.string().optional().describe('Description of work performed'),
+    billable: z.boolean().optional().describe('Whether this time is billable'),
+}, async (params) => {
+    const result = await client.addTimeLog(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('timelog_update', 'Update an existing time log entry. Builds full LOG_Time payload.', {
+    log_id: z.number().describe('Time log ID to update'),
+    task_id: z.number().optional().describe('Task ID'),
+    user_id: z.number().optional().describe('User ID'),
+    duration: z.string().optional().describe('Duration in shorthand format (e.g., 1h30m, 30m, 2h)'),
+    service_id: z.number().optional().describe('Service ID classifying the work type'),
+    group_id: z.number().optional().describe('Project/group ID'),
+    company_id: z.number().optional().describe('Company ID'),
+    log_date: z.string().optional().describe('Date of the work (ISO 8601)'),
+    description: z.string().optional().describe('Description of work performed'),
+    billable: z.boolean().optional().describe('Whether this time is billable'),
+}, async (params) => {
+    const result = await client.updateTimeLog(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ════════════════════════════════════════════════════════════
+// NOTES
+// ════════════════════════════════════════════════════════════
+server.tool('notes_mine', 'Get all notes for the current user', {}, async () => {
+    const result = await client.getMyNotes();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_get', 'Get a note by ID', { note_id: z.number().describe('Note ID') }, async ({ note_id }) => {
+    const result = await client.getNoteById(note_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_add', 'Create a new note', {
+    note: z.string().describe('Note content'),
+    title: z.string().optional().describe('Note title'),
+}, async (params) => {
+    const result = await client.addNote(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_update', 'Update a note', {
+    note_id: z.number().describe('Note ID to update'),
+    note: z.string().describe('Updated content'),
+    title: z.string().optional(),
+}, async (params) => {
+    const result = await client.updateNote(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_remove', 'Delete a note', { note_id: z.number().describe('Note ID to remove') }, async ({ note_id }) => {
+    const result = await client.removeNote(note_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('notes_query', 'Search notes', {
+    query: z.string().optional().describe('Search text'),
+}, async (params) => {
+    const result = await client.queryNotes(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ════════════════════════════════════════════════════════════
+// ACCOUNT
+// ════════════════════════════════════════════════════════════
+server.tool('account_info', 'Get account information', {}, async () => {
+    const result = await client.getAccountInfo();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('account_users', 'Get all users in the account', {}, async () => {
+    const result = await client.getUsers();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('account_services', 'Get active services for the account', {}, async () => {
+    const result = await client.getActiveServices();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ════════════════════════════════════════════════════════════
+// INSIGHTS
+// ════════════════════════════════════════════════════════════
+server.tool('insights_hours_by_person', 'Get logged hours by person', {
+    user_id: z.number().describe('User ID'),
+    start_date: z.string().describe('Start date (ISO 8601)'),
+    end_date: z.string().describe('End date (ISO 8601)'),
+}, async (params) => {
+    const result = await client.getHoursByPerson(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_timelogs', 'Get time logs for the account within a date range', {
+    start_date: z.string().describe('Start date (ISO 8601)'),
+    end_date: z.string().describe('End date (ISO 8601)'),
+}, async (params) => {
+    const result = await client.getTimeLogsByDateRange(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_person_stats', 'Get stats for a person', {
+    user_id: z.number().describe('User ID'),
+    start_date: z.string().optional().describe('Start date (ISO 8601)'),
+    end_date: z.string().optional().describe('End date (ISO 8601)'),
+}, async (params) => {
+    const result = await client.getPersonStats(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_hours_by_person_service', 'Get logged hours by person and service type', {
+    user_id: z.number().describe('User ID'),
+    start_date: z.string().describe('Start date (ISO 8601)'),
+    end_date: z.string().describe('End date (ISO 8601)'),
+    service_id: z.number().optional().describe('Service ID to filter by'),
+}, async (params) => {
+    const result = await client.getHoursByPersonAndService(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_alltime_hours_person_service', 'Get all-time hours per person and service', {
+    user_id: z.number().describe('User ID'),
+    service_id: z.number().optional().describe('Service ID to filter by'),
+}, async (params) => {
+    const result = await client.getAllTimeHoursByPersonAndService(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_project_hours_by_service', 'Get hours by project broken down by service type', {
+    project_id: z.number().describe('Project ID'),
+    start_date: z.string().optional().describe('Start date (ISO 8601)'),
+    end_date: z.string().optional().describe('End date (ISO 8601)'),
+}, async (params) => {
+    const result = await client.getProjectHoursByService(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_account_hours_by_service', 'Get account hours broken down by service type', {
+    start_date: z.string().describe('Start date (ISO 8601)'),
+    end_date: z.string().describe('End date (ISO 8601)'),
+}, async (params) => {
+    const result = await client.getAccountHoursByService(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_ai_summary', 'Get an AI-generated summary of time logs', {
+    user_id: z.number().optional().describe('User ID'),
+    start_date: z.string().optional().describe('Start date (ISO 8601)'),
+    end_date: z.string().optional().describe('End date (ISO 8601)'),
+}, async (params) => {
+    const result = await client.getAiLogSummary(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_person_hours_week', 'Get a person\'s logged hours for the current week', { user_id: z.number().describe('User ID') }, async ({ user_id }) => {
+    const result = await client.getPersonHoursThisWeek(user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_person_hours_month', 'Get a person\'s logged hours for the current month', { user_id: z.number().describe('User ID') }, async ({ user_id }) => {
+    const result = await client.getPersonHoursThisMonth(user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_person_hours_lastmonth', 'Get a person\'s logged hours for last month', { user_id: z.number().describe('User ID') }, async ({ user_id }) => {
+    const result = await client.getPersonHoursLastMonth(user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_project_time_total', 'Get total time logged for a project', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
+    const result = await client.getProjectTimeTotal(project_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('insights_all_users_time', 'Get time totals for all users', {}, async () => {
+    const result = await client.getAllUsersTime();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ════════════════════════════════════════════════════════════
+// START
+// ════════════════════════════════════════════════════════════
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "viviscape-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the ViviScape API — CRM, projects, companies, notes, and insights",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "viviscape-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "viviscape",
+    "crm",
+    "claude"
+  ],
+  "author": "ViviScape LLC",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}