kanithan-xplit-mcp 1.1.1

package/README.md

@@ -0,0 +1,67 @@
+# Kanithan Xplit MCP Server
+
+The official Model Context Protocol (MCP) server for the Kanithan Xplit Expense, Habit & Trip Tracker.
+
+This server allows AI agents (like Claude Desktop, Cline, and Cursor) to securely interact with your personal Kanithan database to log expenses and habits directly via conversational prompts.
+
+## Setup Instructions
+
+### 1. Generate an API Token
+First, log into your Kanithan account and navigate to **Settings > API Access**. Generate a new Personal Access Token (PAT) with the necessary scopes (e.g., `expenses:write`, `habits:read`). 
+
+Copy this token—it will start with `knth_`.
+
+### 2. Configure Your AI Agent
+
+You do not need to clone this repository. Simply add the following configuration to your MCP client (like Claude Desktop's `claude_desktop_config.json` or Cline's `cline_mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "kanithan": {
+      "command": "npx",
+      "args": ["-y", "kanithan-xplit-mcp"],
+      "env": {
+        "KANITHAN_XPLIT_API_TOKEN": "knth_YOUR_GENERATED_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+By default, the server connects to the production Kanithan API. If you are a developer testing locally or on the dev environment, you can override the API URL by adding the `KANITHAN_API_URL` environment variable:
+
+```json
+      "env": {
+        "KANITHAN_XPLIT_API_TOKEN": "knth_YOUR_GENERATED_TOKEN_HERE",
+        "KANITHAN_API_URL": "https://family-expense-tracker-fe21f.web.app/api/v1"
+      }
+```
+
+## Supported Tools
+
+### Habit Tools
+- `list_habits` — Discover your configured habits and their internal IDs.
+- `log_habit` — Log a specific value or boolean status to a habit on a given date.
+- `get_habit_summary` — **NEW** Get a monthly breakdown for a habit: completed days, total value, and per-day detail.
+
+### Expense Tools
+- `log_expense` — Log a daily expense into your family dashboard.
+- `delete_expense` — **NEW** Permanently delete an expense by ID (owner only).
+- `edit_expense` — **NEW** Update amount, category, date, or note on an existing expense (owner only).
+
+### Trip Tools
+- `list_trips` — List all trips you are a member of (use this to get `tripId`).
+- `create_trip` — Create a new trip with a name, description, and dates.
+- `add_trip_expense` — Add an expense to a specific trip, with payer and optional splits.
+- `get_trip_settlement` — Get the full settlement report: who paid, net balances, and who owes whom.
+
+## API Documentation
+
+Interactive Swagger UI is available after app deployment at:
+
+```
+https://app.kanithan.in/api/v1/swagger.html
+```
+
+The raw OpenAPI 3.0 spec is at `/api/v1/openapi.json`.

package/bin/index.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const API_URL = process.env.KANITHAN_API_URL || "https://kanithan-prod.web.app/api/v1";
+const API_TOKEN = process.env.KANITHAN_XPLIT_API_TOKEN;
+const API_BASE = "https://api-uzsx2irlva-el.a.run.app"; 
+
+if (!API_TOKEN) {
+  console.error("Error: KANITHAN_XPLIT_API_TOKEN environment variable is required.");
+  process.exit(1);
+}
+
+const server = new Server(
+  {
+    name: "kanithan-xplit-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Register Tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "list_groups",
+        description: "List all expense groups you are a member of. Use this to find the correct groupId before calling add_group_expense or get_group_settlement.",
+        inputSchema: {
+          type: "object",
+          properties: {}
+        }
+      },
+      {
+        name: "create_group",
+        description: "Create a new expense group",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Name of the group" },
+            description: { type: "string", description: "Optional description" },
+            startDate: { type: "string", description: "YYYY-MM-DD" },
+            endDate: { type: "string", description: "YYYY-MM-DD (optional)" }
+          },
+          required: ["name", "startDate"]
+        }
+      },
+      {
+        name: "add_group_expense",
+        description: "Add an expense to a specific group. Call list_groups first to get the groupId.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            groupId: { type: "string", description: "The ID of the group" },
+            amount: { type: "number" },
+            category: { type: "string" },
+            description: { type: "string" },
+            date: { type: "string", description: "YYYY-MM-DD" },
+            paidBy: { type: "string", description: "Display name of person who paid" },
+            splits: {
+              type: "array",
+              description: "Optional: how to split the expense among members",
+              items: {
+                type: "object",
+                properties: {
+                  userName: { type: "string" },
+                  amount: { type: "number" }
+                }
+              }
+            }
+          },
+          required: ["groupId", "amount", "category", "date", "paidBy"]
+        }
+      },
+      {
+        name: "get_group_settlement",
+        description: "Get the full settlement report for a group: who paid what, net balances, and who needs to pay whom to settle up.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            groupId: { type: "string", description: "The ID of the group" }
+          },
+          required: ["groupId"]
+        }
+      },
+      {
+        name: "delete_expense",
+        description: "Permanently delete an expense by its ID. Only the owner of the expense can delete it.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            expenseId: { type: "string", description: "The ID of the expense to delete" }
+          },
+          required: ["expenseId"]
+        }
+      },
+      {
+        name: "edit_expense",
+        description: "Update one or more fields of an existing expense (amount, category, date, note). Provide the expenseId plus any fields you want to change. Only the owner of the expense can edit it.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            expenseId: { type: "string", description: "The ID of the expense to edit" },
+            amount: { type: "number", description: "New amount" },
+            category: { type: "string", description: "New category" },
+            date: { type: "string", description: "New date in YYYY-MM-DD format" },
+            note: { type: "string", description: "New note or description" }
+          },
+          required: ["expenseId"]
+        }
+      }
+    ]
+  };
+});
+
+// Handle Tool Execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  const headers = {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${API_TOKEN}`
+  };
+
+  try {
+    let response;
+    
+    switch (name) {
+      case "list_groups":
+        response = await fetch(`${API_URL}/trips`, { headers });
+        break;
+        
+      case "create_group":
+        response = await fetch(`${API_URL}/trips`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(args)
+        });
+        break;
+        
+      case "add_group_expense": {
+        const { groupId, ...expenseArgs } = args;
+        response = await fetch(`${API_URL}/trips/${groupId}/expenses`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(expenseArgs)
+        });
+        break;
+      }
+        
+      case "get_group_settlement": {
+        const { groupId: tId } = args;
+        response = await fetch(`${API_URL}/trips/${tId}/settlement`, { headers });
+        break;
+      }
+
+      case "delete_expense": {
+        const { expenseId } = args;
+        response = await fetch(`${API_URL}/expenses/${expenseId}`, {
+          method: "DELETE",
+          headers
+        });
+        break;
+      }
+
+      case "edit_expense": {
+        const { expenseId: eId, ...updateFields } = args;
+        response = await fetch(`${API_URL}/expenses/${eId}`, {
+          method: "PATCH",
+          headers,
+          body: JSON.stringify(updateFields)
+        });
+        break;
+      }
+        
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+
+    }
+
+    const result = await response.json();
+    
+    if (!response.ok) {
+      throw new Error(`API Error: ${JSON.stringify(result)}`);
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error executing tool ${name}: ${error.message}`
+        }
+      ],
+      isError: true
+    };
+  }
+});
+
+// Start Server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("Kanithan MCP Server running on stdio");

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "kanithan-xplit-mcp",
+  "version": "1.1.1",
+  "description": "MCP Server for Xplit.",
+  "main": "bin/index.mjs",
+  "type": "module",
+  "bin": {
+    "kanithan-xplit-mcp": "./bin/index.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "kanithan",
+    "expense-tracker",
+    "ai",
+    "claude",
+    "cline"
+  ],
+  "author": "Joseph Vijayakumar",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0"
+  }
+}