eqvitta-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eqvitta Software Solutions
+
+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,93 @@
+# Eqvitta Accounting MCP Server
+
+[![MCP Standard](https://img.shields.io/badge/MCP-Standard%202024--11--05-blue)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node Version](https://img.shields.io/badge/Node-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
+
+Official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for **Eqvitta Cloud Accounting & GST Billing**.
+
+Connect Claude Desktop, Claude Code, and any MCP-compliant AI client directly to your Eqvitta accounting records. Seamlessly generate GST sales & purchase invoices, manage ledgers, post receipts & payments, query trial balances, and reconcile financial statements with strict role-based data isolation.
+
+---
+
+## ⚡ Quick Start with Claude Desktop
+
+### Automatic 1-Click Install (Smithery)
+If using [Smithery](https://smithery.ai):
+```bash
+npx -y @smithery/cli install eqvitta-mcp --client claude
+```
+
+---
+
+### Manual Configuration
+
+Add the server to your `claude_desktop_config.json`:
+
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "eqvitta": {
+      "command": "npx",
+      "args": ["-y", "github:Eqvitta/eqvitta-mcp"],
+      "env": {
+        "EQVITTA_API_KEY": "YOUR_EQVITTA_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+> **How to get your API Key**: Log in to Eqvitta > **Settings** > **API Keys** > Generate a new Key.
+
+---
+
+## 🚀 Key Features
+
+- **GST Invoicing**:
+  - Automatically calculates CGST, SGST, IGST, and rounding off.
+  - Automatically assigns the next sequential invoice number (e.g. `NR/2627/005`).
+  - Creates balanced double-entry ledger postings instantly.
+- **Ledgers & Account Groups**:
+  - Look up ledgers, outstanding balances, party contact details, and account group structures.
+- **Vouchers & Transactions**:
+  - Record Bank / Cash receipts and payments against customers, suppliers, and expense ledgers.
+  - Record outward and inward service invoices.
+- **Real-Time Financial Reports**:
+  - Instant Trial Balance, Profit & Loss summaries, and Ledger Account Statements.
+- **Role-Based Security**:
+  - Multi-tenant tenant isolation. All actions are scoped to companies the API key user is assigned to.
+  - Destructive operations (edits and deletions) are strictly disabled over MCP.
+  - Internal ledger transfers and financial adjustments require elevated administrative privileges (`financialreporteditor` or `company_admin`).
+
+---
+
+## 🛠️ Available MCP Tools
+
+| Category | Tools | Description |
+| :--- | :--- | :--- |
+| **Companies & Ledgers** | `list_companies`, `search_ledgers`, `get_ledger_balance`, `get_ledger_statement`, `update_ledger_contact` | Explore companies, query balances, and view statement entries. |
+| **Inventory & Catalogs** | `search_stocks`, `get_stock_detail`, `search_account_groups` | Search stock items, quantities, HSN/SAC codes, and accounting groups. |
+| **Invoicing** | `create_sales_invoice`, `create_purchase_invoice`, `create_service_outward`, `create_service_inward`, `create_logistic_invoice` | Generate GST-compliant sales, purchase, service, and freight vouchers. |
+| **Receipts & Payments** | `create_receipt_voucher`, `create_payment_voucher` | Record customer payments and supplier payouts against bank/cash accounts. |
+| **Financial Reports** | `get_trial_balance`, `get_financial_statement` | Retrieve structured balance sheet and profit & loss figures. |
+| **Challans** | `search_challans`, `get_challan_detail` | Track delivery and transport challans. |
+| **Admin Transfers** *(Gated)* | `transfer_ledger_journal`, `transfer_group_balances_journal`, `bulk_transfer_transactions_ledger` | Shift ledger entries and transfer balances (only visible to authorized roles). |
+
+---
+
+## 🔒 Security & Architecture
+
+The `eqvitta-mcp` CLI connects to Eqvitta's high-availability remote engine (`https://chatapi.eqvitta.com/webhook/mcp`). 
+- **Zero Local Maintenance**: All schema changes and accounting rule updates are managed on the cloud engine. Your client never requires manual version updates.
+- **Encrypted Communication**: All traffic is encrypted over TLS 1.3.
+- **Least Privilege**: Only tools authorized by the user's role are exposed to the AI model.
+
+---
+
+## 📄 License
+
+MIT License. Copyright (c) 2026 Eqvitta Software Solutions.

package/bin/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * Eqvitta Accounting MCP Server Bridge
+ * Connects Claude Desktop / MCP Clients to Eqvitta's Remote MCP Engine.
+ */
+
+const readline = require('readline');
+
+const ENDPOINT = process.env.EQVITTA_MCP_ENDPOINT || 'https://chatapi.eqvitta.com/webhook/mcp';
+
+// Parse API key from CLI arguments or environment variables
+let apiKey = process.env.EQVITTA_API_KEY || '';
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--api-key' && args[i + 1]) {
+    apiKey = args[i + 1];
+    i++;
+  } else if (args[i].startsWith('--api-key=')) {
+    apiKey = args[i].split('=')[1];
+  } else if (args[i] === '--header' && args[i + 1]) {
+    const parts = args[i + 1].split(':');
+    if (parts[0].trim().toLowerCase() === 'x-api-key') {
+      apiKey = parts.slice(1).join(':').trim();
+    }
+    i++;
+  }
+}
+
+if (!apiKey) {
+  console.error('[eqvitta-mcp] Warning: No EQVITTA_API_KEY provided. Tool access may be limited.');
+}
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: false
+});
+
+rl.on('line', async (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  let request;
+  try {
+    request = JSON.parse(trimmed);
+  } catch (err) {
+    console.error('[eqvitta-mcp] Invalid JSON received on stdin:', trimmed);
+    return;
+  }
+
+  // Handle client notifications that don't expect a response
+  if (request.method === 'notifications/initialized') {
+    return;
+  }
+
+  try {
+    const headers = {
+      'Content-Type': 'application/json'
+    };
+    if (apiKey) {
+      headers['x-api-key'] = apiKey;
+    }
+
+    const res = await fetch(ENDPOINT, {
+      method: 'POST',
+      headers: headers,
+      body: JSON.stringify(request)
+    });
+
+    if (!res.ok) {
+      const errText = await res.text();
+      console.error('[eqvitta-mcp] HTTP Error ' + res.status + ':', errText);
+      const errPayload = {
+        jsonrpc: '2.0',
+        id: request.id ?? null,
+        error: {
+          code: -32603,
+          message: 'HTTP ' + res.status + ': ' + errText
+        }
+      };
+      process.stdout.write(JSON.stringify(errPayload) + '\n');
+      return;
+    }
+
+    const data = await res.json();
+    process.stdout.write(JSON.stringify(data) + '\n');
+  } catch (e) {
+    console.error('[eqvitta-mcp] Request error:', e.message || String(e));
+    const errPayload = {
+      jsonrpc: '2.0',
+      id: request.id ?? null,
+      error: {
+        code: -32603,
+        message: 'Network error communicating with Eqvitta MCP server: ' + (e.message || String(e))
+      }
+    };
+    process.stdout.write(JSON.stringify(errPayload) + '\n');
+  }
+});
+
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "eqvitta-mcp",
+  "version": "1.0.0",
+  "description": "Official Model Context Protocol (MCP) server for Eqvitta Cloud Accounting & GST Billing. Seamlessly manage ledgers, generate GST-compliant invoices, track stock, and generate financial reports directly in Claude.",
+  "type": "commonjs",
+  "main": "bin/cli.js",
+  "bin": {
+    "eqvitta-mcp": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-desktop",
+    "anthropic",
+    "accounting",
+    "gst",
+    "invoicing",
+    "ledger",
+    "india-gst",
+    "eqvitta"
+  ],
+  "author": "Eqvitta <support@eqvitta.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Eqvitta/eqvitta-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Eqvitta/eqvitta-mcp/issues"
+  },
+  "homepage": "https://eqvitta.com",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/smithery.yaml

@@ -0,0 +1,24 @@
+# Smithery configuration for Eqvitta MCP Server
+# https://smithery.ai/docs/config
+
+name: eqvitta-mcp
+description: Official Model Context Protocol (MCP) server for Eqvitta Cloud Accounting & GST Billing.
+version: 1.0.0
+
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      apiKey:
+        type: string
+        description: Your Eqvitta API key (generated in Eqvitta Settings > API Keys)
+    required:
+      - apiKey
+  command: node
+  args:
+    - bin/cli.js
+    - --api-key
+    - ${config.apiKey}
+  env:
+    EQVITTA_API_KEY: ${config.apiKey}