invoicesnest-mcp 1.0.0

package/README.md

@@ -0,0 +1,291 @@
+# InvoicesNest MCP Server
+
+![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blueviolet) ![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue) ![Node.js](https://img.shields.io/badge/Node.js-18%2B-green) ![Status](https://img.shields.io/badge/Status-Stable-brightgreen) ![License](https://img.shields.io/badge/License-Proprietary-red)
+
+> **Version**: `1.1.0` | **Status**: `Stable` | **Transport**: `stdio` | **API Compatibility**: `InvoicesNest Backend >= v1.0`
+
+Official Model Context Protocol (MCP) server for InvoicesNest.
+
+Connect AI assistants such as Claude Desktop, Cursor, VS Code Copilot, and future MCP-compatible clients directly to your InvoicesNest workspace. The server exposes AI-native tools for invoices, clients, recurring billing, analytics, and business resources while keeping all business logic inside the InvoicesNest backend.
+
+---
+
+## Architecture Diagram
+
+```
+       [ Claude / Cursor / VS Code ]
+                    │
+                    │ Model Context Protocol (stdio)
+                    ▼
+         [ InvoicesNest MCP Server ]
+                    │
+                    │ REST API calls (bypass tunnel headers)
+                    ▼
+        [ InvoicesNest API Server ]
+                    │
+                    │ prisma
+                    ▼
+               [ Database ]
+```
+
+---
+
+## Design Philosophy
+
+The MCP server is intentionally thin. It does not implement business rules or calculations directly. Instead, it exposes AI-friendly interfaces and validates request signatures. The InvoicesNest Backend remains the single source of truth. This architecture keeps AI clients lightweight while ensuring consistent business behavior across Web, Mobile, API, and MCP integrations.
+
+---
+
+## Compatible Clients
+
+*   **Claude Desktop**
+*   **Cursor IDE**
+*   **VS Code** (using MCP clients)
+*   **Continue.dev**
+*   **Cline**
+*   **Roo Code**
+
+---
+
+## Installation & Build
+
+Ensure you have Node.js (v18+) and npm installed.
+
+1.  Navigate into the `invoice-mcp` folder:
+    ```bash
+    cd invoice-mcp
+    ```
+2.  Install dependencies:
+    ```bash
+    npm install
+    ```
+3.  Build the TypeScript files:
+    ```bash
+    npm run build
+    ```
+4.  Start the MCP server locally:
+    ```bash
+    npm start
+    ```
+
+---
+
+## Project Tree
+
+```
+invoice-mcp/
+├── build/                 # Compiled JavaScript output
+├── src/
+│   ├── api/               # Decoupled REST API wrappers
+│   │   ├── business.api.ts
+│   │   ├── client.api.ts
+│   │   ├── dashboard.api.ts
+│   │   └── invoice.api.ts
+│   ├── schemas/           # Zod parameter validation schemas
+│   │   ├── client.schema.ts
+│   │   └── invoice.schema.ts
+│   ├── tools/             # 21 MCP Tool handlers
+│   ├── types/             # Shared TypeScript typings
+│   ├── utils/             # Loggers, error formatters, and helpers
+│   ├── config.ts          # Central environment constants
+│   ├── index.ts           # Bootstraps Stdio server transport
+│   ├── server.ts          # Main MCP server routes registration
+│   ├── prompts/           # Reserved for future MCP Prompt handlers
+│   └── resources/         # Reserved for future MCP Resource handlers
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## Environment Variables
+
+| Variable | Requirement | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `INVOICESNEST_ACCESS_TOKEN` | **Required** | — | Your JWT account access token from settings dashboard. |
+| `INVOICESNEST_BACKEND_URL` | **Required** | — | Base URL of your InvoicesNest API backend (e.g. `https://api.invoicesnest.com`). |
+| `LOG_LEVEL` | Optional | `info` | Logging verbosity (`info`, `error`, `debug`). |
+| `REQUEST_TIMEOUT` | Optional | `30000` | Backend API request timeout in milliseconds. |
+
+---
+
+## Exposed MCP Resources
+
+The MCP Server exposes the following read-only context resources to your LLMs:
+
+| Resource URI | MIME Type | Description |
+| :--- | :--- | :--- |
+| `invoicesnest://business/profile` | `application/json` | Active business profiles details (Name, address, email). |
+| `invoicesnest://business/invoice-template` | `application/json` | Active template configurations. |
+| `invoicesnest://business/payment-methods` | `application/json` | Allowed payment options. |
+| `invoicesnest://business/branding` | `application/json` | Logo references and colors codes. |
+| `invoicesnest://business/products` | `application/json` | Product inventory lists. |
+| `invoicesnest://business/services` | `application/json` | Business services catalog. |
+| `invoicesnest://business/tax-rules` | `application/json` | Default tax configurations. |
+| `invoicesnest://business/payment-terms` | `text/plain` | Standard deadline payment guidelines. |
+| `invoicesnest://business/currencies` | `application/json` | Supported currency codes and symbols. |
+| `invoicesnest://business/company-settings` | `application/json` | Timezone metadata records. |
+| `invoicesnest://business/number-format` | `text/plain` | Invoice serial numbering prefixes. |
+| `invoicesnest://business/date-format` | `text/plain` | Selected date representation layout. |
+| `invoicesnest://business/email-template` | `text/html` | HTML template layouts for client deliveries. |
+
+---
+
+## Exposed MCP Tools (21 total)
+
+| # | Tool Name | Parameters | Description |
+| :- | :--- | :--- | :--- |
+| 1 | `health_check` | None | Diagnoses access token status and API connection health. |
+| 2 | `who_am_i` | None | Returns active user session, workspaces list, and permission levels. |
+| 3 | `list_capabilities` | None | Outlines active API capabilities and supported modules. |
+| 4 | `get_business_context` | None | Retrieves active merchant profile, currency, and invoice prefix. |
+| 5 | `search_everything` | `query` | Unified parallel search across Invoices, Clients, and Recurring profiles. |
+| 6 | `explain_invoice` | `id` or `invoiceNumber` | Breaks down tax, discount, subtotal, grand total, and overdue status. |
+| 7 | `recommend_payment_followup` | None | Returns overdue age data for LLM to formulate custom payment reminders. |
+| 8 | `generate_business_summary` | None | Aggregates Revenue, Outstanding, MRR, Top Client, Collection Rate. |
+| 9 | `create_invoice` | client details, items | Generates a new mathematically-validated invoice. |
+| 10 | `get_invoice` | `id` or `invoiceNumber` | Reads complete invoice JSON metadata. |
+| 11 | `search_invoices` | `query` | Searches invoices by number, client name, or email. |
+| 12 | `update_invoice` | `id`, update fields | Performs partial field updates on an existing invoice. |
+| 13 | `delete_invoice` | `id` or `invoiceNumber` | Deletes an invoice (subject to backend deletion policy). |
+| 14 | `duplicate_invoice` | `id`, `newInvoiceNumber` | Clones an invoice and assigns the next serial number. |
+| 15 | `create_client` | name, email, phone, address | Registers a new client CRM contact. |
+| 16 | `search_clients` | `query` | Searches saved clients by name or email. |
+| 17 | `recurring_invoice` | `action`, profile data | Manages recurring billing profiles (list, create, pause, resume, skip, delete). |
+| 18 | `payment_status` | `status` | Filters invoices by PAID, PENDING, or OVERDUE. |
+| 19 | `get_revenue_stats` | None | Calculates collected revenue and outstanding cashflow per currency. |
+| 20 | `get_dashboard_summary` | None | Returns invoice count distributions across all statuses. |
+| 21 | `send_invoice` | `id` or `invoiceNumber` | Emails PDF invoice directly to the client's address. |
+
+---
+
+## Developer Tool Schema Examples
+
+### 1. `create_invoice` Input Example
+```json
+{
+  "clientName": "ABC Corp Ltd",
+  "clientEmail": "billing@abccorp.com",
+  "items": [
+    {
+      "description": "API Integration Consulting",
+      "quantity": 10,
+      "rate": 150
+    }
+  ],
+  "taxRate": 15,
+  "discountRate": 5,
+  "sendEmailToClient": true
+}
+```
+
+### 2. `recurring_invoice` Input Example
+```json
+{
+  "action": "create",
+  "createData": {
+    "clientName": "John Doe LLC",
+    "clientEmail": "john@doe.com",
+    "frequency": "MONTHLY",
+    "items": [
+      {
+        "description": "Monthly Retainer Services",
+        "quantity": 1,
+        "rate": 2000
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Interactive AI Prompt Library (55+ Real-World Prompt Scenarios)
+
+### Invoicing & Drafts
+1.  *Create an invoice for ABC Ltd worth $450 with description "Consulting Work".*
+2.  *Draft invoice for Ali Khan: 2 hours of Web Development at $100/hr, tax rate 15%.*
+3.  *Duplicate invoice INV-0012 but set the status to draft.*
+4.  *Update the due date of invoice INV-1002 to next Friday.*
+5.  *Delete invoice with serial number INV-0056.*
+6.  *Set the shipping cost of invoice INV-0089 to $25.*
+7.  *Apply a 10% discount on invoice INV-0023 and recalculate.*
+8.  *Add 3 items to invoice INV-1120: Item A for $100, Item B for $200, Item C for $300.*
+9.  *Find my recent draft invoices.*
+10. *Get the exact JSON details of invoice INV-0011.*
+
+### Client Management & CRM
+11. *Create a client Ali Khan, email ali@example.com, address 123 Street Lahore.*
+12. *Search for a client named Smith.*
+13. *Find the contact details of customer XYZ Corp.*
+14. *Change the email address of client John Doe to john@newmail.com.*
+15. *Add phone number +92-300-1234567 to client Ali Ahmed.*
+16. *Register a new business client: name "Future Tech LLC", email "info@futuretech.co".*
+17. *Does client Ali already exist? Search the database.*
+18. *List all saved clients in my CRM.*
+19. *Update client address for 'Zubair Butt' to 'Main Boulevard Gulberg'.*
+20. *Find the client ID of 'Usman Ghani'.*
+
+### Payments & Overdue Tracking
+21. *Show unpaid invoices.*
+22. *List all overdue invoices.*
+23. *Which invoices are still pending payment?*
+24. *How many invoices were paid in USD?*
+25. *Check if invoice INV-0005 has been paid yet.*
+26. *List all PAID invoices.*
+27. *Recommend payment reminders based on currently overdue invoices.*
+28. *Draft a polite email to overdue client John Doe.*
+29. *Find all invoices with outstanding amount higher than $1000.*
+30. *List overdue invoices delayed by more than 30 days.*
+
+### Business Reports & Summaries
+31. *How is my business doing? Give me a full business summary.*
+32. *What is my collection rate this month?*
+33. *Calculate my total collected revenue and outstanding cashflow.*
+34. *Who is my top-paying client by cumulative paid totals?*
+35. *Who is my worst payer client in terms of overdue balances?*
+36. *What is my average invoice value?*
+37. *Estimate my Monthly Recurring Revenue (MRR) based on active profiles.*
+38. *Tell me how much revenue is pending in EUR.*
+39. *Explain invoice INV-1020: detail the tax portion and discount value.*
+40. *Summarize active invoice statistics.*
+
+### Recurring Invoices
+41. *List all active recurring billing profiles.*
+42. *Pause the recurring invoice for client Ali Khan.*
+43. *Resume the recurring profile with ID active-recur-id.*
+44. *Skip the next scheduled run for recurring invoice recurring-uuid-here.*
+45. *Trigger an immediate run of recurring invoice profile rec_9982.*
+46. *Delete the recurring billing template for Client John.*
+47. *Create a monthly recurring invoice for Client Zubair for $500, starting today.*
+48. *Show all paused recurring profiles.*
+49. *How much recurring revenue do we get from Client ABC LLC?*
+50. *What is the billing frequency of recurring profile rec-1020?*
+
+### Debugging & System Context
+51. *Run an MCP connection health check.*
+52. *Who am I logged in as? Show my workspace and permissions.*
+53. *What are the capabilities of the InvoicesNest API?*
+54. *Check if my JWT access token is valid.*
+55. *What is the default currency of my business context?*
+
+---
+
+## Public Release & Security Roadmap (v1.2)
+
+For public directory listing and enterprise distribution, the authentication model will transition from JWT session cookies to:
+1.  **Scoped MCP API Keys:** Dynamic creation of token prefix `inv_mcp_...` restricted to read-only or read-write permissions (e.g. `invoices:read`, `clients:write`).
+2.  **OAuth2 Authorization Code Flow:** Enable direct browser-based oauth handshakes for external AI clients (ChatGPT GPTs store, Claude Workspaces) without manual credential mapping.
+
+---
+
+## License
+
+Proprietary — Copyright © InvoicesNest. All rights reserved.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for full release history.

package/build/api/business.api.js

@@ -0,0 +1,15 @@
+import { callBackendApi } from "./client.js";
+let cachedMetadata = null;
+let cacheExpiry = 0;
+const CACHE_TTL_MS = 10000; // 10 seconds cache TTL
+export const BusinessApi = {
+    async getMetadata(forceRefresh = false) {
+        const now = Date.now();
+        if (!forceRefresh && cachedMetadata && now < cacheExpiry) {
+            return cachedMetadata;
+        }
+        cachedMetadata = await callBackendApi("/api/v1/invoices/metadata", "GET");
+        cacheExpiry = now + CACHE_TTL_MS;
+        return cachedMetadata;
+    }
+};

package/build/api/client.api.js

@@ -0,0 +1,9 @@
+import { callBackendApi } from "./client.js";
+export const ClientApi = {
+    async list() {
+        return await callBackendApi("/api/v1/clients", "GET");
+    },
+    async create(payload) {
+        return await callBackendApi("/api/v1/clients", "POST", payload);
+    }
+};

package/build/api/client.js

@@ -0,0 +1,42 @@
+import { CONFIG } from "../config.js";
+import { Logger } from "../utils/logger.js";
+export async function callBackendApi(endpoint, method = "GET", body) {
+    const startTime = Date.now();
+    const token = CONFIG.ACCESS_TOKEN;
+    const backendUrl = CONFIG.BACKEND_URL;
+    const headers = {
+        "Authorization": `Bearer ${token}`,
+        "Content-Type": "application/json",
+        "bypass-tunnel-reminder": "true",
+        "ngrok-skip-browser-warning": "true"
+    };
+    const url = `${backendUrl.replace(/\/$/, "")}${endpoint}`;
+    Logger.info(`Initiating backend request: [${method}] ${url}`, body);
+    try {
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined
+        });
+        const duration = Date.now() - startTime;
+        Logger.info(`Backend response received in ${duration}ms: Status ${response.status}`);
+        const responseText = await response.text();
+        let responseData;
+        try {
+            responseData = JSON.parse(responseText);
+        }
+        catch (e) {
+            responseData = responseText;
+        }
+        if (!response.ok) {
+            const errorMsg = responseData?.message || responseData?.error || responseText || `HTTP error ${response.status}`;
+            throw new Error(errorMsg);
+        }
+        return responseData.data !== undefined ? responseData.data : responseData;
+    }
+    catch (err) {
+        const duration = Date.now() - startTime;
+        Logger.error(`Backend request failed after ${duration}ms`, err);
+        throw err;
+    }
+}

package/build/api/dashboard.api.js

@@ -0,0 +1,6 @@
+import { callBackendApi } from "./client.js";
+export const DashboardApi = {
+    async getInvoices() {
+        return await callBackendApi("/api/v1/invoices", "GET");
+    }
+};

package/build/api/invoice.api.js

@@ -0,0 +1,40 @@
+import { callBackendApi } from "./client.js";
+export const InvoiceApi = {
+    async list() {
+        return await callBackendApi("/api/v1/invoices", "GET");
+    },
+    async get(id) {
+        return await callBackendApi(`/api/v1/invoices/${id}`, "GET");
+    },
+    async create(payload) {
+        return await callBackendApi("/api/v1/invoices", "POST", payload);
+    },
+    async update(id, payload) {
+        return await callBackendApi(`/api/v1/invoices/${id}`, "PUT", payload);
+    },
+    async delete(id) {
+        return await callBackendApi(`/api/v1/invoices/${id}`, "DELETE");
+    },
+    async sendEmail(id) {
+        return await callBackendApi(`/api/v1/invoices/${id}/resend-email`, "POST");
+    },
+    // Recurring endpoints
+    async listRecurring() {
+        return await callBackendApi("/api/v1/recurring", "GET");
+    },
+    async createRecurring(payload) {
+        return await callBackendApi("/api/v1/recurring", "POST", payload);
+    },
+    async updateRecurring(id, payload) {
+        return await callBackendApi(`/api/v1/recurring/${id}`, "PUT", payload);
+    },
+    async deleteRecurring(id) {
+        return await callBackendApi(`/api/v1/recurring/${id}`, "DELETE");
+    },
+    async runRecurring(id) {
+        return await callBackendApi(`/api/v1/recurring/${id}/run`, "POST");
+    },
+    async skipRecurring(id) {
+        return await callBackendApi(`/api/v1/recurring/${id}/skip-next`, "POST");
+    }
+};

package/build/auth.js

@@ -0,0 +1,10 @@
+import { CONFIG } from "./config.js";
+export function getAccessToken() {
+    if (!CONFIG.ACCESS_TOKEN) {
+        throw new Error("Missing INVOICESNEST_ACCESS_TOKEN. Set it in your environment before starting the MCP server.");
+    }
+    return CONFIG.ACCESS_TOKEN;
+}
+export function getBackendUrl() {
+    return CONFIG.BACKEND_URL;
+}

package/build/config.js

@@ -0,0 +1,11 @@
+import dotenv from "dotenv";
+dotenv.config();
+export const CONFIG = {
+    VERSION: "v1",
+    API_COMPATIBILITY: "v1",
+    BACKEND_URL: process.env.INVOICESNEST_BACKEND_URL || "https://abed-223-123-76-202.ngrok-free.app",
+    ACCESS_TOKEN: process.env.INVOICESNEST_ACCESS_TOKEN || "",
+};
+if (!CONFIG.ACCESS_TOKEN) {
+    console.error("WARNING: INVOICESNEST_ACCESS_TOKEN is not configured. MCP requests will fail until authorized.");
+}

package/build/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { server } from "./server.js";
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("InvoicesNest Model Context Protocol (MCP) server running on stdio transport");
+}
+main().catch((error) => {
+    console.error("MCP Server lifecycle crash:", error);
+    process.exit(1);
+});

package/build/schemas/client.schema.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export const createClientSchema = z.object({
+    name: z.string().min(1, "Client name is required"),
+    email: z.string().email("Valid email is required"),
+    phone: z.string().optional(),
+    address: z.string().optional(),
+    taxId: z.string().optional(),
+    notes: z.string().optional(),
+    businessId: z.string().optional()
+});

package/build/schemas/dashboard.schema.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export const getDashboardSummarySchema = z.object({});
+export const getRevenueStatsSchema = z.object({});
+export const paymentStatusSchema = z.object({
+    status: z.enum(["PAID", "PENDING", "OVERDUE"])
+});
+export const sendInvoiceSchema = z.object({
+    id: z.string().optional(),
+    invoiceNumber: z.string().optional()
+});
+export const searchInvoicesSchema = z.object({
+    query: z.string().optional()
+});

package/build/schemas/invoice.schema.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export const createInvoiceSchema = z.object({
+    clientName: z.string().min(1, "Client name is required"),
+    clientEmail: z.string().email("Valid email is required").optional().or(z.literal("")),
+    clientAddress: z.string().optional(),
+    clientPhone: z.string().optional(),
+    invoiceNumber: z.string().optional(),
+    invoiceDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD").optional(),
+    dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD").optional().or(z.literal("")),
+    currency: z.string().length(3, "Currency code must be 3 characters").optional(),
+    taxRate: z.number().min(0, "Tax rate cannot be negative").max(100, "Tax rate cannot exceed 100").optional(),
+    discountRate: z.number().min(0, "Discount rate cannot be negative").max(100, "Discount rate cannot exceed 100").optional(),
+    shipping: z.number().min(0, "Shipping cost cannot be negative").optional(),
+    amountPaid: z.number().min(0, "Amount paid cannot be negative").optional(),
+    notes: z.string().optional(),
+    terms: z.string().optional(),
+    status: z.enum(["DRAFT", "SENT", "PAID"]).optional(),
+    sendEmailToClient: z.boolean().optional(),
+    businessId: z.string().optional(),
+    items: z.array(z.object({
+        description: z.string().min(1, "Description is required"),
+        quantity: z.number().min(0.01, "Quantity must be at least 0.01").optional(),
+        rate: z.number().min(0, "Rate cannot be negative").optional()
+    })).min(1, "At least one item is required")
+});
+export const updateInvoiceSchema = z.object({
+    id: z.string().optional(),
+    invoiceNumber: z.string().optional(),
+    updateData: z.object({
+        clientName: z.string().optional(),
+        clientEmail: z.string().email().optional().or(z.literal("")),
+        clientAddress: z.string().optional(),
+        clientPhone: z.string().optional(),
+        status: z.enum(["DRAFT", "SENT", "PAID", "OVERDUE"]).optional(),
+        notes: z.string().optional(),
+        terms: z.string().optional(),
+        dueDate: z.string().optional().or(z.literal("")),
+        taxRate: z.number().optional(),
+        discountRate: z.number().optional(),
+        shipping: z.number().optional(),
+        amountPaid: z.number().optional()
+    })
+});