@dropspot/mcp 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drop Spot Technologies
+
+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

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# @dropspot/mcp — Drop Spot MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@dropspot/mcp.svg)](https://www.npmjs.com/package/@dropspot/mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![MCP Standard](https://img.shields.io/badge/MCP-Standard-emerald.svg)](https://modelcontextprotocol.io)
+
+Official **Model Context Protocol (MCP)** server for [Drop Spot](https://godropspot.com) — the passwordless client document intake and automated follow-up platform for accountants, law firms, and service professionals.
+
+Connect Drop Spot directly to **Claude Desktop**, **Cursor AI**, or **Google Antigravity**. Instruct your AI in plain English to prepare client checklists, dispatch secure zero-password upload links, monitor completion status, and review incoming paperwork—with zero coding required.
+
+---
+
+## ⚡ Quickstart
+
+### 1. Get your Drop Spot API Key
+1. Sign in to your Drop Spot workspace at [godropspot.com](https://godropspot.com).
+2. Go to **Settings** → **Developer API & MCP**.
+3. Click **Generate New API Key**, select your desired scopes (or Full Access), and copy your token (`ds_live_...`).
+
+---
+
+### 2. Configure Your AI Client
+
+#### Option A: Claude Desktop
+Add the following to your `claude_desktop_config.json`:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dropspot": {
+      "command": "npx",
+      "args": ["-y", "@dropspot/mcp"],
+      "env": {
+        "DROPSPOT_API_KEY": "ds_live_YOUR_ACTUAL_KEY_HERE",
+        "DROPSPOT_API_BASE_URL": "https://godropspot.com/api/v1"
+      }
+    }
+  }
+}
+```
+
+#### Option B: Cursor AI
+Add to `.cursor/mcp.json` in your project or global settings:
+
+```json
+{
+  "mcpServers": {
+    "dropspot": {
+      "command": "npx",
+      "args": ["-y", "@dropspot/mcp"],
+      "env": {
+        "DROPSPOT_API_KEY": "ds_live_YOUR_ACTUAL_KEY_HERE",
+        "DROPSPOT_API_BASE_URL": "https://godropspot.com/api/v1"
+      }
+    }
+  }
+}
+```
+
+#### Option C: Claude Code (CLI)
+Add Drop Spot to Claude Code:
+
+```bash
+claude mcp add dropspot npx -y @dropspot/mcp --env DROPSPOT_API_KEY=ds_live_YOUR_ACTUAL_KEY_HERE DROPSPOT_API_BASE_URL=https://godropspot.com/api/v1
+```
+
+#### Option D: Windsurf / VS Code / Antigravity
+Add to your client's MCP configuration (`mcpServers`):
+
+```json
+{
+  "mcpServers": {
+    "dropspot": {
+      "command": "npx",
+      "args": ["-y", "@dropspot/mcp"],
+      "env": {
+        "DROPSPOT_API_KEY": "ds_live_YOUR_ACTUAL_KEY_HERE",
+        "DROPSPOT_API_BASE_URL": "https://godropspot.com/api/v1"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🌐 Public Registries & Discovery
+
+Drop Spot is an open, unproxied MCP server available across major AI registries:
+
+- **Smithery.ai:** Direct registry listing indexed via `smithery.yaml` (Arcade.dev-powered, zero proxy latency).
+- **Glama.ai:** Verified MCP listing claimed via `glama.json` ([glama.ai/mcp/servers](https://glama.ai/mcp/servers)).
+- **PulseMCP:** Listed in the community catalog ([pulsemcp.com](https://pulsemcp.com)).
+- **Official Model Context Protocol:** Cataloged on [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers).
+- **npm:** Zero-install direct execution via `npx -y @dropspot/mcp`.
+
+---
+
+## 💬 Prompts Your AI Understands
+
+Once connected, your AI gains native understanding of your Drop Spot workspace:
+
+- *"Create an intake request for Sarah Jenkins using our 2026 Tax Return template."*
+- *"Show me our client list and search for Acme Corp."*
+- *"Update Sarah's phone number to (555) 234-5678 and add a note that she is a VIP client."*
+- *"Check if Sarah uploaded her W-2 form yet."*
+- *"Review Sarah's uploaded W-2 and approve it."*
+- *"Reject item #2 with the note: 'Page 2 is blurry. Please re-upload a clear scan.' "*
+- *"List all our active document requests with pending items."*
+- *"Create a reusable checklist template called 'Quarterly Bookkeeping Close'."*
+
+---
+
+## 🛠️ Available MCP Tools (12 Tools)
+
+| Tool Name | Description |
+| :--- | :--- |
+| `create_intake_request` | Create a new document intake dossier with an itemized checklist. Generates a passwordless magic upload link and optionally emails the client. |
+| `list_intake_requests` | List and filter active document requests in the workspace by status or client email. |
+| `get_intake_request` | Retrieve complete details of a specific request, including each checklist item, upload statuses, and file metadata. |
+| `review_item` | Review an uploaded file: approve it or reject it with custom feedback to prompt the client for a re-upload. |
+| `get_file_download_link` | Generate a short-lived (5-minute) secure presigned URL to inspect or download an uploaded client file. |
+| `list_clients` | Search and browse your firm's client directory by name, email, company, entity type, status, or tag. |
+| `get_client` | Fetch a client record with full accounting CRM metadata, spouses/linked contacts, tags, and intake history. |
+| `create_or_update_client` | Add a new client or update contact & CRM profile (tax entity, FYE, cadence, state, tags, masked ID, pinned notes, linked contacts). |
+| `list_templates` | View your reusable checklist templates (e.g. 1040 Tax Return, KYC, Mortgage Intake). |
+| `get_template` | Inspect a specific checklist template and its default items. |
+| `create_template` | Create a new reusable checklist template with predefined items and categories. |
+| `update_template` | Edit an existing template's name, description, or checklist items. |
+
+---
+
+## 🔒 Security, Privacy & Compliance
+
+- **Zero AI Training:** Client documents and personal data are **never** used to train public or proprietary AI models.
+- **Short-Lived Signed URLs:** File downloads use ephemeral 5-minute pre-signed URLs; file binaries are never permanently exposed over the wire.
+- **Scoped API Tokens:** Generate API keys restricted strictly to specific operations (`requests:read`, `requests:write`, `items:review`, `clients:write`, etc.).
+- **Human-in-the-Loop:** AI tools execute actions on your behalf with scoped permissions, clear item status tracking, and 1-click token revocation.
+
+---
+
+## 📄 License
+MIT © [Drop Spot Technologies](https://godropspot.com)

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,871 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+const API_KEY = process.env.DROPSPOT_API_KEY || '';
+const BASE_URL = (process.env.DROPSPOT_API_BASE_URL || process.env.DROPSPOT_BASE_URL || 'https://portal.godropspot.com').replace(/\/+$/, '');
+async function apiRequest(endpoint, options = {}) {
+    // Support both full paths and /api/v1 paths
+    const cleanEndpoint = endpoint.startsWith('/api/v1')
+        ? (BASE_URL.endsWith('/api/v1') ? endpoint.replace('/api/v1', '') : endpoint)
+        : (BASE_URL.endsWith('/api/v1') ? endpoint : `/api/v1${endpoint}`);
+    const url = `${BASE_URL}${cleanEndpoint}`;
+    const headers = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${API_KEY}`,
+        ...options.headers,
+    };
+    const response = await fetch(url, { ...options, headers });
+    const data = (await response.json());
+    if (!response.ok) {
+        throw new Error(data?.error || `API request failed with HTTP ${response.status}`);
+    }
+    return data;
+}
+const server = new Server({
+    name: 'dropspot-mcp',
+    version: '1.2.0',
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+    },
+});
+// ----------------------------------------------------------------------------
+// 1. LIST TOOLS
+// ----------------------------------------------------------------------------
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'create_intake_request',
+                description: 'Create a new Drop Spot client document intake request (dossier). Generates a zero-password magic upload link and optionally emails the client.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        clientName: {
+                            type: 'string',
+                            description: 'Full name of the client (e.g. "Jane Doe")',
+                        },
+                        clientEmail: {
+                            type: 'string',
+                            description: 'Email address of the client where the magic link will be sent',
+                        },
+                        clientPhone: {
+                            type: 'string',
+                            description: 'Optional phone number for SMS reminders',
+                        },
+                        title: {
+                            type: 'string',
+                            description: 'Title of the intake request (e.g. "2026 Tax Return Documentation")',
+                        },
+                        dueAt: {
+                            type: 'string',
+                            description: 'ISO 8601 deadline date (optional, defaults to 14 days from now)',
+                        },
+                        sendInvitationEmail: {
+                            type: 'boolean',
+                            description: 'Whether to automatically email the client the invitation link (defaults to true)',
+                        },
+                        items: {
+                            type: 'array',
+                            description: 'Checklist of items and documents required from the client',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    title: { type: 'string', description: 'Name of the required document' },
+                                    description: { type: 'string', description: 'Helpful instructions for the client' },
+                                    isRequired: { type: 'boolean', description: 'Whether this item is mandatory (default: true)' },
+                                    allowMultiple: { type: 'boolean', description: 'Allow uploading multiple files for this item' },
+                                    category: { type: 'string', description: 'Grouping category (e.g. "Tax", "Identification")' },
+                                },
+                                required: ['title'],
+                            },
+                        },
+                    },
+                    required: ['clientName', 'clientEmail', 'title', 'items'],
+                },
+            },
+            {
+                name: 'list_intake_requests',
+                description: 'List client intake requests in the Drop Spot workspace. Filter by status or client email.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        status: {
+                            type: 'string',
+                            enum: ['in_process', 'completed', 'canceled'],
+                            description: 'Filter by dossier status',
+                        },
+                        clientEmail: {
+                            type: 'string',
+                            description: 'Filter by specific client email',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Number of requests to return (default: 20, max: 100)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'get_intake_request',
+                description: 'Retrieve full details for an intake request by ID, including checklist items, upload progress, and file metadata.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        requestId: {
+                            type: 'string',
+                            description: 'The UUID of the intake request',
+                        },
+                    },
+                    required: ['requestId'],
+                },
+            },
+            {
+                name: 'review_item',
+                description: 'Approve or reject a document uploaded by a client. If rejected, sends automated feedback asking the client to re-upload.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        itemId: {
+                            type: 'string',
+                            description: 'The UUID of the checklist item to review',
+                        },
+                        decision: {
+                            type: 'string',
+                            enum: ['approve', 'reject'],
+                            description: 'Approval decision',
+                        },
+                        rejectionNote: {
+                            type: 'string',
+                            description: 'Reason for rejection to help client correct the issue (e.g. "Photo is blurry, please retake")',
+                        },
+                    },
+                    required: ['itemId', 'decision'],
+                },
+            },
+            {
+                name: 'get_file_download_link',
+                description: 'Generate a secure, temporary presigned download URL for an uploaded file so an AI or operator can inspect the document contents.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        fileId: {
+                            type: 'string',
+                            description: 'The UUID of the uploaded file record',
+                        },
+                        expiresInSeconds: {
+                            type: 'number',
+                            description: 'Expiration in seconds (default: 300 = 5 minutes for privacy)',
+                        },
+                    },
+                    required: ['fileId'],
+                },
+            },
+            // CLIENTS MANAGEMENT TOOLS
+            {
+                name: 'list_clients',
+                description: 'List and search clients in the Drop Spot directory. Filter by name, email, company, entity type, status, or tag.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        search: {
+                            type: 'string',
+                            description: 'Search string to filter clients by name, email, or company name',
+                        },
+                        entityType: {
+                            type: 'string',
+                            enum: ['individual', 's_corp', 'c_corp', 'partnership', 'llc', 'non_profit', 'trust_estate'],
+                            description: 'Filter by tax entity classification',
+                        },
+                        status: {
+                            type: 'string',
+                            enum: ['active', 'lead', 'archived'],
+                            description: 'Filter by client account status',
+                        },
+                        tag: {
+                            type: 'string',
+                            description: 'Filter by specific tag (e.g. "QBO", "Extension Needed")',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Max number of clients to return (default: 50, max: 100)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'get_client',
+                description: 'Retrieve detailed profile and CRM information for a specific client, including tax entity metadata, spouses/linked contacts, tags, pinned accountant note, and active/completed document requests.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        clientId: {
+                            type: 'string',
+                            description: 'The UUID of the client',
+                        },
+                    },
+                    required: ['clientId'],
+                },
+            },
+            {
+                name: 'create_or_update_client',
+                description: 'Add a new client to the directory or update an existing client with accounting CRM metadata (entity type, filing cadence, FYE, state, tags, masked tax ID, pinned accountant notes, and linked contacts).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: {
+                            type: 'string',
+                            description: 'Full name of the client (e.g. "Jane Doe")',
+                        },
+                        email: {
+                            type: 'string',
+                            description: 'Email address of the client',
+                        },
+                        phone: {
+                            type: 'string',
+                            description: 'Optional phone number',
+                        },
+                        company: {
+                            type: 'string',
+                            description: 'Company or business entity name',
+                        },
+                        notes: {
+                            type: 'string',
+                            description: 'General internal notes about this client',
+                        },
+                        entityType: {
+                            type: 'string',
+                            enum: ['individual', 's_corp', 'c_corp', 'partnership', 'llc', 'non_profit', 'trust_estate'],
+                            description: 'Tax entity classification (e.g. "individual" for 1040, "s_corp" for 1120-S, "c_corp" for 1120, "partnership" for 1065)',
+                        },
+                        status: {
+                            type: 'string',
+                            enum: ['active', 'lead', 'archived'],
+                            description: 'Account status (defaults to "active")',
+                        },
+                        fiscalYearEnd: {
+                            type: 'string',
+                            description: 'Fiscal Year End month/day (e.g. "12/31", "06/30")',
+                        },
+                        filingCadence: {
+                            type: 'string',
+                            enum: ['annual', 'quarterly', 'monthly'],
+                            description: 'Tax filing frequency',
+                        },
+                        stateOfFiling: {
+                            type: 'string',
+                            description: 'US State abbreviation for tax filing (e.g. "FL", "CA", "NY")',
+                        },
+                        taxYear: {
+                            type: 'string',
+                            description: 'Current filing tax year (e.g. "2026")',
+                        },
+                        tags: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Accounting tags (e.g. ["QBO", "Extension Needed", "VIP", "Monthly Books"])',
+                        },
+                        pinnedNote: {
+                            type: 'string',
+                            description: 'Sticky internal accountant note (communication quirks, deadline habits)',
+                        },
+                        qboId: {
+                            type: 'string',
+                            description: 'QuickBooks Online or Xero accounting customer ID',
+                        },
+                        taxSoftwareId: {
+                            type: 'string',
+                            description: 'Drake, UltraTax, or CCH Axcess client ID',
+                        },
+                        maskedId: {
+                            type: 'string',
+                            description: 'Masked tax ID / SSN / EIN (last 4 digits only, e.g. "1234" or "***-**-1234")',
+                        },
+                        linkedContacts: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    name: { type: 'string', description: 'Full name of contact' },
+                                    role: { type: 'string', description: 'Role (e.g. "Spouse", "Bookkeeper", "Owner")' },
+                                    email: { type: 'string', description: 'Contact email' },
+                                    phone: { type: 'string', description: 'Contact phone' },
+                                },
+                                required: ['name', 'role'],
+                            },
+                            description: 'Associated contacts, spouses, bookkeepers, or family members',
+                        },
+                    },
+                    required: ['name', 'email'],
+                },
+            },
+            // TEMPLATES MANAGEMENT TOOLS
+            {
+                name: 'list_templates',
+                description: 'List available checklist templates (including starter packages for tax returns, KYC, and mortgage underwriting).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        includeStarters: {
+                            type: 'boolean',
+                            description: 'Whether to include built-in starter templates (default: true)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'get_template',
+                description: 'Get full details and checklist items for a specific reusable template.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        templateId: {
+                            type: 'string',
+                            description: 'The UUID or starter identifier of the template',
+                        },
+                    },
+                    required: ['templateId'],
+                },
+            },
+            {
+                name: 'create_template',
+                description: 'Create a new reusable document checklist template with predefined items and categories.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: {
+                            type: 'string',
+                            description: 'Template title (e.g. "Q1 Bookkeeping Review")',
+                        },
+                        description: {
+                            type: 'string',
+                            description: 'Description of when to use this checklist',
+                        },
+                        isShared: {
+                            type: 'boolean',
+                            description: 'Whether this template is visible to the entire workspace team (default: true)',
+                        },
+                        items: {
+                            type: 'array',
+                            description: 'The list of checklist items',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    title: { type: 'string', description: 'Name of the required document' },
+                                    description: { type: 'string', description: 'Instructions for the client' },
+                                    isRequired: { type: 'boolean', description: 'Whether item is mandatory (default: true)' },
+                                    allowMultiple: { type: 'boolean', description: 'Allow multiple files (default: false)' },
+                                    category: { type: 'string', description: 'Item category' },
+                                },
+                                required: ['title'],
+                            },
+                        },
+                    },
+                    required: ['name', 'items'],
+                },
+            },
+            {
+                name: 'update_template',
+                description: 'Edit an existing custom checklist template (update name, description, or checklist items).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        templateId: {
+                            type: 'string',
+                            description: 'The UUID of the template to edit',
+                        },
+                        name: {
+                            type: 'string',
+                            description: 'Updated template name',
+                        },
+                        description: {
+                            type: 'string',
+                            description: 'Updated description',
+                        },
+                        items: {
+                            type: 'array',
+                            description: 'Updated list of items',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    title: { type: 'string' },
+                                    description: { type: 'string' },
+                                    isRequired: { type: 'boolean' },
+                                    allowMultiple: { type: 'boolean' },
+                                    category: { type: 'string' },
+                                },
+                                required: ['title'],
+                            },
+                        },
+                    },
+                    required: ['templateId'],
+                },
+            },
+        ],
+    };
+});
+// ----------------------------------------------------------------------------
+// 2. CALL TOOL HANDLERS
+// ----------------------------------------------------------------------------
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!API_KEY) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: 'DROPSPOT_API_KEY environment variable is not configured. Please supply a valid Drop Spot API key.',
+                },
+            ],
+        };
+    }
+    try {
+        switch (name) {
+            case 'create_intake_request': {
+                const payload = {
+                    clientName: args?.clientName,
+                    clientEmail: args?.clientEmail,
+                    clientPhone: args?.clientPhone,
+                    title: args?.title,
+                    dueAt: args?.dueAt,
+                    sendInvitationEmail: args?.sendInvitationEmail ?? true,
+                    items: args?.items,
+                };
+                const res = await apiRequest('/requests', {
+                    method: 'POST',
+                    body: JSON.stringify(payload),
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✅ Intake request created successfully!\n\n` +
+                                `• ID: ${res.data.id}\n` +
+                                `• Title: ${res.data.title}\n` +
+                                `• Client: ${res.data.clientName} (${res.data.clientEmail})\n` +
+                                `• Magic Portal URL: ${res.data.portalUrl}\n` +
+                                `• Due Date: ${new Date(res.data.dueAt).toLocaleDateString()}\n` +
+                                `• Items Requested: ${res.data.items?.length || 0}\n` +
+                                `• Invitation Email Sent: ${res.data.invitationEmailSent ? 'Yes' : 'No'}`,
+                        },
+                    ],
+                };
+            }
+            case 'list_intake_requests': {
+                const params = new URLSearchParams();
+                if (args?.status)
+                    params.set('status', String(args.status));
+                if (args?.clientEmail)
+                    params.set('client_email', String(args.clientEmail));
+                if (args?.limit)
+                    params.set('limit', String(args.limit));
+                const res = await apiRequest(`/requests?${params.toString()}`);
+                const requests = res.data || [];
+                if (requests.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: 'No intake requests found matching the criteria.' }],
+                    };
+                }
+                const formatted = requests
+                    .map((r) => {
+                    return `• [${r.status.toUpperCase()}] ${r.title} — ${r.clientName} (${r.clientEmail})\n` +
+                        `  ID: ${r.id} | Progress: ${r.completedItemsCount}/${r.itemsCount} items approved | Due: ${new Date(r.dueAt).toLocaleDateString()}`;
+                })
+                    .join('\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${requests.length} intake requests:\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_intake_request': {
+                const requestId = String(args?.requestId);
+                const res = await apiRequest(`/requests/${requestId}`);
+                const d = res.data;
+                let itemsReport = (d.items || [])
+                    .map((item, idx) => {
+                    const statusIcon = item.status === 'approved' ? '✅' : item.status === 'rejected' ? '❌' : item.status === 'uploaded' ? '📥' : '⏳';
+                    let fileDetails = '';
+                    if (item.files && item.files.length > 0) {
+                        fileDetails = item.files
+                            .map((f) => `\n    - File: ${f.filename} (${Math.round(f.sizeBytes / 1024)} KB) [File ID: ${f.id}]`)
+                            .join('');
+                    }
+                    const rejection = item.rejectionNote ? `\n    - Note: "${item.rejectionNote}"` : '';
+                    return `${idx + 1}. ${statusIcon} ${item.title} [Status: ${item.status}]${rejection}${fileDetails}`;
+                })
+                    .join('\n');
+                const summary = `📋 Intake Dossier: ${d.title}\n` +
+                    `• ID: ${d.id}\n` +
+                    `• Client: ${d.clientName} <${d.clientEmail}>\n` +
+                    `• Status: ${d.status}\n` +
+                    `• Progress: ${d.progress.approvedItems}/${d.progress.requiredItems} required items approved (${d.progress.percent}%)\n` +
+                    `• Due Date: ${new Date(d.dueAt).toLocaleString()}\n\n` +
+                    `Checklist Items:\n${itemsReport}`;
+                return {
+                    content: [{ type: 'text', text: summary }],
+                };
+            }
+            case 'review_item': {
+                const itemId = String(args?.itemId);
+                const decision = String(args?.decision);
+                const rejectionNote = args?.rejectionNote ? String(args.rejectionNote) : undefined;
+                const res = await apiRequest(`/items/${itemId}/review`, {
+                    method: 'POST',
+                    body: JSON.stringify({ decision, rejectionNote }),
+                });
+                const icon = decision === 'approve' ? '✅' : '❌';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${icon} Item "${res.data.item.title}" has been marked as ${decision.toUpperCase()}.\n` +
+                                (decision === 'reject' ? `• Rejection feedback dispatched to client: "${res.data.item.rejectionNote}"\n` : '') +
+                                `• Dossier Completed: ${res.data.request.completed ? 'YES (All required items approved!)' : 'No (Items remaining)'}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_file_download_link': {
+                const fileId = String(args?.fileId);
+                const expiresIn = args?.expiresInSeconds ? Number(args.expiresInSeconds) : 300;
+                const res = await apiRequest(`/files/${fileId}/download?expires_in=${expiresIn}`);
+                const f = res.data;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `🔗 Secure download link generated (valid for ${Math.round(f.expiresInSeconds / 60)} minutes):\n\n` +
+                                `• Filename: ${f.filename}\n` +
+                                `• MIME Type: ${f.mimeType}\n` +
+                                `• Size: ${(f.sizeBytes / 1024).toFixed(1)} KB\n` +
+                                `• SHA-256: ${f.sha256Hash}\n` +
+                                `• Direct URL: ${f.downloadUrl}`,
+                        },
+                    ],
+                };
+            }
+            // CLIENT HANDLERS
+            case 'list_clients': {
+                const params = new URLSearchParams();
+                if (args?.search)
+                    params.set('search', String(args?.search));
+                if (args?.limit)
+                    params.set('limit', String(args?.limit));
+                if (args?.entityType)
+                    params.set('entityType', String(args?.entityType));
+                if (args?.status)
+                    params.set('status', String(args?.status));
+                const res = await apiRequest(`/clients?${params.toString()}`);
+                let clients = res.data || [];
+                if (args?.tag) {
+                    const searchTag = String(args.tag).toLowerCase();
+                    clients = clients.filter((c) => Array.isArray(c.tags) && c.tags.some((t) => t.toLowerCase() === searchTag));
+                }
+                if (clients.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: 'No clients found in the directory.' }],
+                    };
+                }
+                const formatted = clients
+                    .map((c) => {
+                    const company = c.company ? ` (${c.company})` : '';
+                    const phone = c.phone ? ` | Phone: ${c.phone}` : '';
+                    const entity = c.entityType ? ` | Entity: ${c.entityType}` : '';
+                    const tags = c.tags?.length ? ` | Tags: [${c.tags.join(', ')}]` : '';
+                    return `• ${c.name} <${c.email}>${company}${phone}${entity}${tags}\n  ID: ${c.id}`;
+                })
+                    .join('\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${clients.length} clients:\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_client': {
+                const clientId = String(args?.clientId);
+                const res = await apiRequest(`/clients/${clientId}`);
+                const c = res.data;
+                let requestsSummary = 'No document requests yet.';
+                if (c.requests && c.requests.length > 0) {
+                    requestsSummary = c.requests
+                        .map((r) => `  - [${r.status.toUpperCase()}] ${r.title} (ID: ${r.id})`)
+                        .join('\n');
+                }
+                let contactsSummary = 'No linked contacts.';
+                if (c.linkedContacts && c.linkedContacts.length > 0) {
+                    contactsSummary = c.linkedContacts
+                        .map((lc) => `  - ${lc.name} (${lc.role}) ${lc.email ? `<${lc.email}>` : ''}`)
+                        .join('\n');
+                }
+                const report = `👤 Client Profile: ${c.name}\n` +
+                    `• ID: ${c.id}\n` +
+                    `• Email: ${c.email}\n` +
+                    `• Phone: ${c.phone || 'Not provided'}\n` +
+                    `• Company: ${c.company || 'Not provided'}\n` +
+                    `• Entity Type: ${c.entityType || 'individual'}\n` +
+                    `• Status: ${c.status || 'active'}\n` +
+                    `• Fiscal Year End: ${c.fiscalYearEnd || '12/31'}\n` +
+                    `• Filing Cadence: ${c.filingCadence || 'annual'}\n` +
+                    `• State: ${c.stateOfFiling || 'N/A'}\n` +
+                    `• Tax Year: ${c.taxYear || '2026'}\n` +
+                    `• Masked Tax ID: ${c.maskedId || 'None'}\n` +
+                    `• Tags: ${c.tags?.length ? `[${c.tags.join(', ')}]` : 'None'}\n` +
+                    `• Pinned Note: ${c.pinnedNote ? `"${c.pinnedNote}"` : 'None'}\n` +
+                    `• Notes: ${c.notes || 'None'}\n\n` +
+                    `Linked Contacts & Family:\n${contactsSummary}\n\n` +
+                    `Document Intake Requests:\n${requestsSummary}`;
+                return {
+                    content: [{ type: 'text', text: report }],
+                };
+            }
+            case 'create_or_update_client': {
+                const payload = {
+                    name: args?.name,
+                    email: args?.email,
+                    phone: args?.phone,
+                    company: args?.company,
+                    notes: args?.notes,
+                    entityType: args?.entityType,
+                    status: args?.status,
+                    fiscalYearEnd: args?.fiscalYearEnd,
+                    filingCadence: args?.filingCadence,
+                    stateOfFiling: args?.stateOfFiling,
+                    taxYear: args?.taxYear,
+                    tags: args?.tags,
+                    pinnedNote: args?.pinnedNote,
+                    qboId: args?.qboId,
+                    taxSoftwareId: args?.taxSoftwareId,
+                    maskedId: args?.maskedId,
+                    linkedContacts: args?.linkedContacts,
+                };
+                const res = await apiRequest('/clients', {
+                    method: 'POST',
+                    body: JSON.stringify(payload),
+                });
+                const c = res.data;
+                const actionLabel = c.updatedExisting ? 'Updated existing client record' : 'Created new client record';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✅ ${actionLabel}:\n\n` +
+                                `• ID: ${c.id}\n` +
+                                `• Name: ${c.name}\n` +
+                                `• Email: ${c.email}\n` +
+                                `• Company: ${c.company || 'N/A'}\n` +
+                                `• Entity: ${c.entityType || 'individual'}\n` +
+                                `• Status: ${c.status || 'active'}\n` +
+                                `• Tags: ${c.tags?.length ? `[${c.tags.join(', ')}]` : 'None'}\n` +
+                                `• FYE: ${c.fiscalYearEnd || '12/31'}\n` +
+                                `• Pinned Note: ${c.pinnedNote ? `"${c.pinnedNote}"` : 'None'}`,
+                        },
+                    ],
+                };
+            }
+            // TEMPLATE HANDLERS
+            case 'list_templates': {
+                const params = new URLSearchParams();
+                if (args?.includeStarters !== undefined) {
+                    params.set('includeStarters', String(args.includeStarters));
+                }
+                const res = await apiRequest(`/templates?${params.toString()}`);
+                const templates = res.data || [];
+                if (templates.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: 'No checklist templates found in this workspace.' }],
+                    };
+                }
+                const formatted = templates
+                    .map((t) => {
+                    const badge = t.isStarter ? ' [STARTER]' : '';
+                    return `• ${t.name}${badge}\n` +
+                        `  ID: ${t.id} | Items: ${t.items?.length || 0}\n` +
+                        `  ${t.description || 'No description'}`;
+                })
+                    .join('\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${templates.length} templates:\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_template': {
+                const templateId = String(args?.templateId);
+                const res = await apiRequest(`/templates/${templateId}`);
+                const t = res.data;
+                const itemsList = (t.items || [])
+                    .map((it, idx) => {
+                    const req = it.isRequired ? '(Required)' : '(Optional)';
+                    const multi = it.allowMultiple ? '[Multiple files]' : '';
+                    return `  ${idx + 1}. ${it.title} ${req} ${multi}\n     ${it.description || ''}`;
+                })
+                    .join('\n');
+                const report = `📝 Template: ${t.name}\n` +
+                    `• ID: ${t.id}\n` +
+                    `• Description: ${t.description || 'None'}\n` +
+                    `• Starter Template: ${t.isStarter ? 'Yes' : 'No'}\n\n` +
+                    `Checklist Items (${t.items?.length || 0}):\n${itemsList}`;
+                return {
+                    content: [{ type: 'text', text: report }],
+                };
+            }
+            case 'create_template': {
+                const payload = {
+                    name: args?.name,
+                    description: args?.description,
+                    isShared: args?.isShared ?? true,
+                    items: args?.items,
+                };
+                const res = await apiRequest('/templates', {
+                    method: 'POST',
+                    body: JSON.stringify(payload),
+                });
+                const t = res.data;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✅ Template created successfully!\n\n` +
+                                `• ID: ${t.id}\n` +
+                                `• Name: ${t.name}\n` +
+                                `• Items: ${t.items?.length || 0}\n` +
+                                `• Description: ${t.description || 'None'}`,
+                        },
+                    ],
+                };
+            }
+            case 'update_template': {
+                const templateId = String(args?.templateId);
+                const payload = {};
+                if (args?.name !== undefined)
+                    payload.name = args.name;
+                if (args?.description !== undefined)
+                    payload.description = args.description;
+                if (args?.items !== undefined)
+                    payload.items = args.items;
+                const res = await apiRequest(`/templates/${templateId}`, {
+                    method: 'PATCH',
+                    body: JSON.stringify(payload),
+                });
+                const t = res.data;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✅ Template updated successfully!\n\n` +
+                                `• ID: ${t.id}\n` +
+                                `• Name: ${t.name}\n` +
+                                `• Items: ${t.items?.length || 0}\n` +
+                                `• Description: ${t.description || 'None'}`,
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `❌ Drop Spot MCP Error: ${error.message || String(error)}`,
+                },
+            ],
+        };
+    }
+});
+// ----------------------------------------------------------------------------
+// 3. RESOURCES: Dynamic Drop Spot Dossier Inspection
+// ----------------------------------------------------------------------------
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+        resources: [
+            {
+                uri: 'dropspot://requests/active',
+                name: 'Active Client Intake Requests',
+                description: 'Real-time JSON dossier feed of all open document requests in the active workspace.',
+                mimeType: 'application/json',
+            },
+            {
+                uri: 'dropspot://clients/all',
+                name: 'Workspace Client Directory',
+                description: 'Complete client roster including names, emails, phone numbers, and company metadata.',
+                mimeType: 'application/json',
+            },
+            {
+                uri: 'dropspot://templates/all',
+                name: 'Checklist Templates',
+                description: 'All reusable document checklist templates available in the workspace.',
+                mimeType: 'application/json',
+            },
+        ],
+    };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    if (uri === 'dropspot://requests/active') {
+        const res = await apiRequest('/requests?status=in_process');
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(res.data, null, 2),
+                },
+            ],
+        };
+    }
+    if (uri === 'dropspot://clients/all') {
+        const res = await apiRequest('/clients');
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(res.data, null, 2),
+                },
+            ],
+        };
+    }
+    if (uri === 'dropspot://templates/all') {
+        const res = await apiRequest('/templates');
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(res.data, null, 2),
+                },
+            ],
+        };
+    }
+    throw new Error(`Resource not found: ${uri}`);
+});
+// ----------------------------------------------------------------------------
+// 4. SERVER INITIALIZATION & TRANSPORT
+// ----------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Drop Spot MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error initializing Drop Spot MCP server:', error);
+    process.exit(1);
+});

package/glama.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "name": "@dropspot/mcp",
+  "description": "Model Context Protocol (MCP) server for Drop Spot — automated client document collection, file intake, checklist management, and 1-click reviews.",
+  "maintainers": [
+    "officialdropspot",
+    "leoalfonso14"
+  ]
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@dropspot/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "Model Context Protocol (MCP) server for Drop Spot — automated client document collection, file intake, checklist management, and 1-click reviews for Claude Desktop, Cursor, and AI agents.",
+  "type": "module",
+  "homepage": "https://godropspot.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/officialdropspot/dropspot-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-desktop",
+    "cursor",
+    "antigravity",
+    "file-sharing",
+    "document-collection",
+    "client-portal",
+    "client-intake",
+    "tax-documents",
+    "paperwork-automation",
+    "file-intake"
+  ],
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "smithery.yaml",
+    "glama.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "bin": {
+    "dropspot-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "typescript": "~5.7.2"
+  }
+}

package/smithery.yaml

@@ -0,0 +1,27 @@
+# Smithery configuration file: https://smithery.ai/docs/config
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required:
+      - dropspotApiKey
+    properties:
+      dropspotApiKey:
+        type: string
+        description: "Your Drop Spot API key (format: ds_live_... or ds_test_...)"
+      baseUrl:
+        type: string
+        description: "Drop Spot API base URL"
+        default: "https://portal.godropspot.com"
+  commandFunction: |
+    (config) => ({
+      command: 'npx',
+      args: ['-y', '@dropspot/mcp'],
+      env: {
+        DROPSPOT_API_KEY: config.dropspotApiKey,
+        DROPSPOT_API_BASE_URL: config.baseUrl || 'https://portal.godropspot.com'
+      }
+    })
+  exampleConfig:
+    dropspotApiKey: "ds_live_abcdef1234567890"
+    baseUrl: "https://portal.godropspot.com"