nextora-mcp 1.0.0

package/README.md

@@ -0,0 +1,76 @@
+# Nextora MCP Server
+
+Connect your AI assistant (Claude Desktop, Cursor, Cline, etc.) to Nextora to record transactions and analyze receipts by chatting.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `list_categories` | List available income/expense categories |
+| `add_transaction` | Record a new income or expense |
+| `upload_receipt` | Analyze a receipt image and auto-record the transaction |
+| `get_balance` | Get income/expense/net summary for a date range |
+| `list_transactions` | List recent transactions with filters |
+
+## Setup
+
+### 1. Generate an API Key
+
+Log in to Nextora → Settings → API Keys → Generate Key.
+Copy the key — it is shown **once only**.
+
+### 2. Configure Claude Desktop
+
+Edit `~/.claude/settings.json` (or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "nextora": {
+      "command": "npx",
+      "args": ["-y", "nextora-mcp"],
+      "env": {
+        "NEXTORA_API_URL": "https://your-nextora-domain.com/api",
+        "NEXTORA_API_KEY": "nxt_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Or run with Docker
+
+```bash
+docker run --rm -i \
+  -e NEXTORA_API_URL="https://your-domain/api" \
+  -e NEXTORA_API_KEY="nxt_your_key_here" \
+  blacksptech/nextora-mcp:latest
+```
+
+Config ที่ user ใช้กับ Claude Desktop
+{
+  "mcpServers": {
+    "nextora": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i",
+        "-e", "NEXTORA_API_URL=https://your-domain.com/api",
+        "-e", "NEXTORA_API_KEY=nxt_xxx",
+        "blacksptech/nextora-mcp:latest"
+      ]
+    }
+  }
+}
+
+## Example conversations
+
+> "บันทึกค่ากาแฟ 80 บาท วันนี้"  
+> "Add a food expense of 80 baht for coffee today"
+
+> "ส่งรูปใบเสร็จนี้แล้วบันทึกเลย /home/user/receipt.jpg"  
+> "Upload this receipt and record it: /Users/me/Downloads/receipt.png"
+
+> "ยอดรายรับรายจ่ายเดือนนี้เป็นยังไง"  
+> "What's my income vs expense this month?"
+
+> "แสดงรายการ 10 รายการล่าสุด"  
+> "Show my last 10 transactions"

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+import { type AxiosInstance } from "axios";
+export declare function createApiClient(): AxiosInstance;
+export type TransactionType = "Income" | "Expense";
+export interface Category {
+    id: string;
+    name: string;
+    type: TransactionType;
+    parentId: string | null;
+}
+export interface Transaction {
+    id: string;
+    categoryId: string;
+    categoryName: string;
+    type: TransactionType;
+    amount: number;
+    transactionDate: string;
+    description: string | null;
+    createdAt: string;
+}
+export interface CreateTransactionRequest {
+    categoryId: string;
+    type: TransactionType;
+    amount: number;
+    transactionDate: string;
+    description?: string | null;
+    assetId?: string | null;
+    landProjectId?: string | null;
+}
+export interface TransactionFilter {
+    from?: string;
+    to?: string;
+    categoryId?: string;
+}
+export interface AnalyzeReceiptRequest {
+    imageBase64: string;
+    mimeType: string;
+}
+export interface AnalyzeReceiptResult {
+    amount: number | null;
+    type: TransactionType;
+    description: string | null;
+    transactionDate: string | null;
+    categoryHint: string | null;
+    vendor: string | null;
+    success: boolean;
+    errorMessage: string | null;
+}
+export interface ReportNetSummary {
+    totalIncome: number;
+    totalExpense: number;
+    netProfit: number;
+    from: string;
+    to: string;
+}

package/dist/client.js

@@ -0,0 +1,17 @@
+import axios from "axios";
+export function createApiClient() {
+    const apiUrl = process.env.NEXTORA_API_URL;
+    const apiKey = process.env.NEXTORA_API_KEY;
+    if (!apiUrl)
+        throw new Error("NEXTORA_API_URL environment variable is required");
+    if (!apiKey)
+        throw new Error("NEXTORA_API_KEY environment variable is required");
+    return axios.create({
+        baseURL: apiUrl.replace(/\/$/, ""),
+        headers: {
+            "X-Api-Key": apiKey,
+            "Content-Type": "application/json",
+        },
+        timeout: 30_000,
+    });
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createApiClient } from "./client.js";
+import { listCategoriesSchema, listCategories } from "./tools/list_categories.js";
+import { addTransactionSchema, addTransaction } from "./tools/add_transaction.js";
+import { uploadReceiptSchema, uploadReceipt } from "./tools/upload_receipt.js";
+import { getBalanceSchema, getBalance } from "./tools/get_balance.js";
+import { listTransactionsSchema, listTransactions } from "./tools/list_transactions.js";
+const server = new McpServer({
+    name: "nextora",
+    version: "1.0.0",
+});
+const client = createApiClient();
+server.tool("list_categories", "List available transaction categories. Call this before add_transaction if you're unsure which category to use.", listCategoriesSchema.shape, async (args) => {
+    const text = await listCategories(client, args);
+    return { content: [{ type: "text", text }] };
+});
+server.tool("add_transaction", "Record a new income or expense transaction in Nextora.", addTransactionSchema.shape, async (args) => {
+    const text = await addTransaction(client, args);
+    return { content: [{ type: "text", text }] };
+});
+server.tool("upload_receipt", "Analyze a receipt image file and automatically record the transaction. Requires an AI provider configured in Nextora Settings.", uploadReceiptSchema.shape, async (args) => {
+    const text = await uploadReceipt(client, args);
+    return { content: [{ type: "text", text }] };
+});
+server.tool("get_balance", "Get income, expense and net profit summary for a date range. Defaults to the current month.", getBalanceSchema.shape, async (args) => {
+    const text = await getBalance(client, args);
+    return { content: [{ type: "text", text }] };
+});
+server.tool("list_transactions", "List recent transactions with optional date range and type filters.", listTransactionsSchema.shape, async (args) => {
+    const text = await listTransactions(client, args);
+    return { content: [{ type: "text", text }] };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Startup message goes to stderr so it doesn't pollute the MCP JSON-RPC stdio stream
+    process.stderr.write("Nextora MCP server running (stdio)\n");
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err}\n`);
+    process.exit(1);
+});

package/dist/tools/add_transaction.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import type { AxiosInstance } from "axios";
+export declare const addTransactionSchema: z.ZodObject<{
+    type: z.ZodEnum<["Income", "Expense"]>;
+    amount: z.ZodNumber;
+    categoryName: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    transactionDate: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "Income" | "Expense";
+    amount: number;
+    categoryName: string;
+    description?: string | undefined;
+    transactionDate?: string | undefined;
+}, {
+    type: "Income" | "Expense";
+    amount: number;
+    categoryName: string;
+    description?: string | undefined;
+    transactionDate?: string | undefined;
+}>;
+export declare function addTransaction(client: AxiosInstance, args: z.infer<typeof addTransactionSchema>): Promise<string>;

package/dist/tools/add_transaction.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+export const addTransactionSchema = z.object({
+    type: z.enum(["Income", "Expense"]).describe("Income or Expense"),
+    amount: z.number().positive().describe("Amount in the account's currency (positive number)"),
+    categoryName: z.string().describe("Category name (partial match OK). Call list_categories first if unsure."),
+    description: z.string().optional().describe("Optional note about this transaction"),
+    transactionDate: z.string().optional().describe("Date as YYYY-MM-DD. Defaults to today if omitted."),
+});
+export async function addTransaction(client, args) {
+    // 1. Find the best matching category
+    const catResponse = await client.get("/transaction-categories");
+    const allCategories = catResponse.data.filter((c) => c.type === args.type);
+    const nameLower = args.categoryName.toLowerCase();
+    let category = allCategories.find((c) => c.name.toLowerCase() === nameLower);
+    if (!category) {
+        category = allCategories.find((c) => c.name.toLowerCase().includes(nameLower));
+    }
+    if (!category) {
+        // Fallback: use first category of matching type
+        category = allCategories[0];
+    }
+    if (!category) {
+        const available = catResponse.data.map((c) => `${c.name} (${c.type})`).join(", ");
+        return `No ${args.type} category found matching "${args.categoryName}". Available categories: ${available}. Please call list_categories and retry.`;
+    }
+    // 2. Determine date
+    const transactionDate = args.transactionDate ?? new Date().toISOString().slice(0, 10);
+    // 3. Create transaction
+    const req = {
+        categoryId: category.id,
+        type: args.type,
+        amount: args.amount,
+        transactionDate,
+        description: args.description ?? null,
+    };
+    const response = await client.post("/transactions", req);
+    const tx = response.data;
+    return [
+        `✅ Transaction recorded successfully!`,
+        ``,
+        `  ID:          ${tx.id}`,
+        `  Type:        ${tx.type}`,
+        `  Amount:      ${tx.amount.toLocaleString()}`,
+        `  Category:    ${tx.categoryName}`,
+        `  Date:        ${tx.transactionDate}`,
+        tx.description ? `  Description: ${tx.description}` : null,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/tools/get_balance.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import type { AxiosInstance } from "axios";
+export declare const getBalanceSchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    from?: string | undefined;
+    to?: string | undefined;
+}, {
+    from?: string | undefined;
+    to?: string | undefined;
+}>;
+export declare function getBalance(client: AxiosInstance, args: z.infer<typeof getBalanceSchema>): Promise<string>;

package/dist/tools/get_balance.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export const getBalanceSchema = z.object({
+    from: z.string().optional().describe("Start date YYYY-MM-DD (default: first day of current month)"),
+    to: z.string().optional().describe("End date YYYY-MM-DD (default: today)"),
+});
+export async function getBalance(client, args) {
+    const today = new Date();
+    const defaultFrom = new Date(today.getFullYear(), today.getMonth(), 1)
+        .toISOString()
+        .slice(0, 10);
+    const defaultTo = today.toISOString().slice(0, 10);
+    const from = args.from ?? defaultFrom;
+    const to = args.to ?? defaultTo;
+    const response = await client.get("/reports/net-summary", {
+        params: { from, to },
+    });
+    const s = response.data;
+    const fmt = (n) => n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+    const netLabel = s.netProfit >= 0 ? "Net Profit  ✅" : "Net Loss    ⚠️";
+    return [
+        `💰 Financial Summary (${s.from} → ${s.to})`,
+        ``,
+        `  Total Income:   ${fmt(s.totalIncome)}`,
+        `  Total Expense:  ${fmt(s.totalExpense)}`,
+        `  ${netLabel}: ${fmt(Math.abs(s.netProfit))}`,
+    ].join("\n");
+}

package/dist/tools/list_categories.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { AxiosInstance } from "axios";
+export declare const listCategoriesSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodOptional<z.ZodEnum<["Income", "Expense", "All"]>>>;
+}, "strip", z.ZodTypeAny, {
+    type: "Income" | "Expense" | "All";
+}, {
+    type?: "Income" | "Expense" | "All" | undefined;
+}>;
+export declare function listCategories(client: AxiosInstance, args: z.infer<typeof listCategoriesSchema>): Promise<string>;

package/dist/tools/list_categories.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export const listCategoriesSchema = z.object({
+    type: z.enum(["Income", "Expense", "All"]).optional().default("All")
+        .describe("Filter by transaction type"),
+});
+export async function listCategories(client, args) {
+    const response = await client.get("/transaction-categories");
+    let categories = response.data;
+    if (args.type !== "All") {
+        categories = categories.filter((c) => c.type === args.type);
+    }
+    if (categories.length === 0) {
+        return `No ${args.type === "All" ? "" : args.type + " "}categories found.`;
+    }
+    const lines = categories.map((c) => `• [${c.id}] ${c.name} (${c.type})${c.parentId ? " [sub-category]" : ""}`);
+    return `Found ${categories.length} categor${categories.length === 1 ? "y" : "ies"}:\n\n${lines.join("\n")}`;
+}

package/dist/tools/list_transactions.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { AxiosInstance } from "axios";
+export declare const listTransactionsSchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    type: z.ZodDefault<z.ZodOptional<z.ZodEnum<["Income", "Expense", "All"]>>>;
+}, "strip", z.ZodTypeAny, {
+    type: "Income" | "Expense" | "All";
+    limit: number;
+    from?: string | undefined;
+    to?: string | undefined;
+}, {
+    type?: "Income" | "Expense" | "All" | undefined;
+    from?: string | undefined;
+    to?: string | undefined;
+    limit?: number | undefined;
+}>;
+export declare function listTransactions(client: AxiosInstance, args: z.infer<typeof listTransactionsSchema>): Promise<string>;

package/dist/tools/list_transactions.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export const listTransactionsSchema = z.object({
+    from: z.string().optional().describe("Start date YYYY-MM-DD"),
+    to: z.string().optional().describe("End date YYYY-MM-DD"),
+    limit: z.number().int().min(1).max(50).optional().default(20)
+        .describe("Maximum number of results to return (1–50, default 20)"),
+    type: z.enum(["Income", "Expense", "All"]).optional().default("All")
+        .describe("Filter by transaction type"),
+});
+export async function listTransactions(client, args) {
+    const params = {};
+    if (args.from)
+        params.from = args.from;
+    if (args.to)
+        params.to = args.to;
+    const response = await client.get("/transactions", { params });
+    let transactions = response.data;
+    if (args.type !== "All") {
+        transactions = transactions.filter((t) => t.type === args.type);
+    }
+    // Take most recent N
+    const sliced = transactions.slice(-args.limit).reverse();
+    if (sliced.length === 0) {
+        return `No transactions found${args.from ? ` from ${args.from}` : ""}${args.to ? ` to ${args.to}` : ""}.`;
+    }
+    const fmt = (n) => n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+    const lines = sliced.map((t) => {
+        const sign = t.type === "Income" ? "+" : "-";
+        const desc = t.description ? ` — ${t.description}` : "";
+        return `  ${t.transactionDate}  ${sign}${fmt(t.amount).padStart(12)}  ${t.categoryName}${desc}`;
+    });
+    const totalIncome = sliced.filter((t) => t.type === "Income").reduce((s, t) => s + t.amount, 0);
+    const totalExpense = sliced.filter((t) => t.type === "Expense").reduce((s, t) => s + t.amount, 0);
+    return [
+        `📊 Last ${sliced.length} transaction${sliced.length !== 1 ? "s" : ""}:`,
+        ``,
+        ...lines,
+        ``,
+        `  Income: +${fmt(totalIncome)}  |  Expense: -${fmt(totalExpense)}  |  Net: ${fmt(totalIncome - totalExpense)}`,
+    ].join("\n");
+}

package/dist/tools/upload_receipt.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { AxiosInstance } from "axios";
+export declare const uploadReceiptSchema: z.ZodObject<{
+    imagePath: z.ZodString;
+    autoRecord: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    descriptionOverride: z.ZodOptional<z.ZodString>;
+    amountOverride: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    imagePath: string;
+    autoRecord: boolean;
+    descriptionOverride?: string | undefined;
+    amountOverride?: number | undefined;
+}, {
+    imagePath: string;
+    autoRecord?: boolean | undefined;
+    descriptionOverride?: string | undefined;
+    amountOverride?: number | undefined;
+}>;
+export declare function uploadReceipt(client: AxiosInstance, args: z.infer<typeof uploadReceiptSchema>): Promise<string>;

package/dist/tools/upload_receipt.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { readFileSync } from "fs";
+import { extname } from "path";
+export const uploadReceiptSchema = z.object({
+    imagePath: z.string().describe("Absolute path to the receipt image file (JPG, PNG, WEBP, or PDF)"),
+    autoRecord: z.boolean().optional().default(true).describe("Automatically create the transaction after analysis. Set to false to preview only."),
+    descriptionOverride: z.string().optional().describe("Override the AI-suggested description"),
+    amountOverride: z.number().positive().optional().describe("Override the AI-detected amount"),
+});
+const MIME_MAP = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".pdf": "application/pdf",
+};
+export async function uploadReceipt(client, args) {
+    // 1. Read image file
+    let imageBuffer;
+    try {
+        imageBuffer = readFileSync(args.imagePath);
+    }
+    catch {
+        return `❌ Could not read file at "${args.imagePath}". Please check the path exists and is accessible.`;
+    }
+    const ext = extname(args.imagePath).toLowerCase();
+    const mimeType = MIME_MAP[ext] ?? "image/jpeg";
+    const imageBase64 = imageBuffer.toString("base64");
+    // 2. Analyze via API
+    const analyzeReq = { imageBase64, mimeType };
+    const analyzeRes = await client.post("/transactions/analyze-image", analyzeReq);
+    const result = analyzeRes.data;
+    if (!result.success) {
+        return `❌ Receipt analysis failed: ${result.errorMessage}\n\nTip: Make sure an AI provider (OpenAI, Claude, or Gemini) is configured in Settings.`;
+    }
+    const amount = args.amountOverride ?? result.amount;
+    const description = args.descriptionOverride ?? (result.description ?? result.vendor ?? null);
+    const type = result.type ?? "Expense";
+    const dateStr = result.transactionDate ?? new Date().toISOString().slice(0, 10);
+    // Build preview
+    const preview = [
+        `📋 Receipt Analysis Result:`,
+        ``,
+        `  Type:        ${type}`,
+        `  Amount:      ${amount?.toLocaleString() ?? "(not detected)"}`,
+        `  Date:        ${dateStr}`,
+        result.vendor ? `  Vendor:      ${result.vendor}` : null,
+        description ? `  Description: ${description}` : null,
+        result.categoryHint ? `  Category:    ${result.categoryHint} (suggested)` : null,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    if (!args.autoRecord) {
+        return `${preview}\n\n💡 autoRecord is false — call again with autoRecord: true to save this transaction.`;
+    }
+    if (!amount || amount <= 0) {
+        return `${preview}\n\n❌ Could not determine amount from receipt. Please call add_transaction manually with the correct amount.`;
+    }
+    // 3. Find matching category
+    const catResponse = await client.get("/transaction-categories");
+    const typeCategories = catResponse.data.filter((c) => c.type === type);
+    let category;
+    if (result.categoryHint) {
+        const hint = result.categoryHint.toLowerCase();
+        category = typeCategories.find((c) => c.name.toLowerCase().includes(hint));
+    }
+    category ??= typeCategories[0];
+    if (!category) {
+        return `${preview}\n\n❌ No ${type} categories configured. Please create one in Settings first.`;
+    }
+    // 4. Create transaction
+    const req = {
+        categoryId: category.id,
+        type,
+        amount,
+        transactionDate: dateStr,
+        description,
+    };
+    const txRes = await client.post("/transactions", req);
+    const tx = txRes.data;
+    return [
+        preview,
+        ``,
+        `✅ Transaction recorded!`,
+        `  ID:       ${tx.id}`,
+        `  Category: ${tx.categoryName}`,
+    ].join("\n");
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "nextora-mcp",
+  "version": "1.0.0",
+  "description": "Nextora MCP Server — record transactions and analyze receipts via AI",
+  "type": "module",
+  "files": ["dist"],
+  "bin": {
+    "nextora-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.0",
+    "axios": "^1.9.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}

package/readme.how_use_mcp.md

@@ -0,0 +1,294 @@
+# วิธีใช้งาน Nextora MCP Server กับ AI ต่างๆ
+
+## ขั้นตอนแรก: สร้าง API Key
+
+1. Login เข้า Nextora → **Settings → API Keys**
+2. กด **"สร้าง Key"** → ตั้งชื่อ เช่น `My Claude Desktop`
+3. **Copy key ที่แสดง** — จะแสดงครั้งเดียวเท่านั้น (รูปแบบ: `nxt_xxxxxxxxxx...`)
+4. จดค่า API URL ของ Nextora ไว้ด้วย เช่น `https://your-domain.com/api`
+
+---
+
+## 1. Claude Desktop (แนะนำ — รองรับ native)
+
+Claude Desktop คือแอปบน Mac/Windows ที่รองรับ MCP โดยตรง
+
+### ขั้นตอน
+
+**Mac:** เปิดไฟล์ `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** เปิดไฟล์ `%APPDATA%\Claude\claude_desktop_config.json`
+
+เพิ่ม config นี้:
+
+```json
+{
+  "mcpServers": {
+    "nextora": {
+      "command": "npx",
+      "args": ["-y", "nextora-mcp"],
+      "env": {
+        "NEXTORA_API_URL": "https://your-domain.com/api",
+        "NEXTORA_API_KEY": "nxt_your_key_here"
+      }
+    }
+  }
+}
+```
+
+> ถ้าไม่มี `npx` หรือ Node.js → ดาวน์โหลดที่ [nodejs.org](https://nodejs.org) (LTS)
+
+**Restart Claude Desktop** แล้วจะเห็น 🔧 icon ด้านล่าง chat — หมายความว่า tools พร้อมใช้
+
+### ลองใช้
+
+```
+"บันทึกค่ากาแฟ 80 บาท วันนี้"
+"ส่งรูปใบเสร็จนี้แล้วบันทึกด้วย: /Users/me/Downloads/receipt.jpg"
+"ยอดรายรับรายจ่ายเดือนนี้เป็นเท่าไหร่"
+"แสดงรายการล่าสุด 10 รายการ"
+```
+
+---
+
+## 2. Cursor IDE
+
+Cursor เป็น Code Editor ที่รองรับ MCP tools
+
+### ขั้นตอน
+
+เปิด **Cursor Settings** → ค้นหา **MCP** → เพิ่ม server ใหม่:
+
+```json
+{
+  "mcpServers": {
+    "nextora": {
+      "command": "npx",
+      "args": ["-y", "nextora-mcp"],
+      "env": {
+        "NEXTORA_API_URL": "https://your-domain.com/api",
+        "NEXTORA_API_KEY": "nxt_your_key_here"
+      }
+    }
+  }
+}
+```
+
+หรือเพิ่มที่ไฟล์ `.cursor/mcp.json` ใน project root:
+
+```json
+{
+  "mcpServers": {
+    "nextora": {
+      "command": "npx",
+      "args": ["-y", "nextora-mcp"],
+      "env": {
+        "NEXTORA_API_URL": "https://your-domain.com/api",
+        "NEXTORA_API_KEY": "nxt_your_key_here"
+      }
+    }
+  }
+}
+```
+
+เปิด Cursor Chat (Cmd/Ctrl+L) → พิมพ์คำสั่งได้เลย
+
+---
+
+## 3. Cline (VS Code Extension)
+
+Cline คือ VS Code extension ที่ทรงพลัง รองรับ MCP tools ครบ
+
+### ขั้นตอน
+
+1. ติดตั้ง extension **Cline** จาก VS Code Marketplace
+2. เปิด Cline Panel (icon ด้านซ้าย)
+3. กด **Settings icon** → **MCP Servers** → **Edit Config**
+4. เพิ่ม:
+
+```json
+{
+  "mcpServers": {
+    "nextora": {
+      "command": "npx",
+      "args": ["-y", "nextora-mcp"],
+      "env": {
+        "NEXTORA_API_URL": "https://your-domain.com/api",
+        "NEXTORA_API_KEY": "nxt_your_key_here"
+      }
+    }
+  }
+}
+```
+
+5. Save → กด **Restart MCP Servers**
+6. เห็น `nextora` ใน MCP Servers list → พร้อมใช้
+
+> **Cline รองรับ OpenAI, Claude, Gemini, Ollama ฯลฯ** — ตั้งค่า AI provider ใน Cline Settings ได้อิสระ
+
+---
+
+## 4. Continue.dev (VS Code / JetBrains)
+
+Continue เป็น open-source AI coding assistant รองรับ MCP
+
+### ขั้นตอน
+
+เปิดไฟล์ `~/.continue/config.json` แล้วเพิ่ม:
+
+```json
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "nextora-mcp"],
+          "env": {
+            "NEXTORA_API_URL": "https://your-domain.com/api",
+            "NEXTORA_API_KEY": "nxt_your_key_here"
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 5. ChatGPT / OpenAI (ผ่าน Bridge)
+
+OpenAI ยังไม่รองรับ MCP โดยตรงใน ChatGPT web app ณ ขณะนี้ (กรกฎาคม 2026) แต่มีวิธีอ้อม:
+
+### Option A: ใช้ผ่าน OpenAI API + MCP-to-OpenAI Bridge
+
+ถ้าเขียน code เอง สามารถใช้ library เชื่อม MCP กับ OpenAI Function Calling:
+
+```typescript
+import OpenAI from "openai";
+// แปลง MCP tools เป็น OpenAI function definitions แล้วส่ง tool results กลับ
+```
+
+### Option B: ใช้ Cline ที่ตั้งค่า OpenAI เป็น provider
+
+Cline รองรับทั้ง MCP tools และ OpenAI API — ตั้งค่า Cline ให้ใช้ OpenAI แล้ว connect Nextora MCP เข้าไป:
+
+1. ติดตั้ง Cline
+2. Settings → AI Provider → เลือก **OpenAI**, ใส่ API Key ของ OpenAI
+3. เพิ่ม Nextora MCP server ตามขั้นตอนใน [ส่วนที่ 3]
+
+> วิธีนี้ใช้ OpenAI เป็น brain แต่ได้ Nextora tools ครบ
+
+---
+
+## 6. Open WebUI (Self-hosted)
+
+สำหรับคนที่รัน Open WebUI (Ollama / Local LLM):
+
+```json
+{
+  "tools": [
+    {
+      "type": "mcp",
+      "server": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["-y", "nextora-mcp"],
+        "env": {
+          "NEXTORA_API_URL": "https://your-domain.com/api",
+          "NEXTORA_API_KEY": "nxt_your_key_here"
+        }
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 7. Docker Run (ถ้าไม่ต้องการติดตั้ง Node.js)
+
+```bash
+# ใช้ image จาก Docker Hub
+docker run --rm -i \
+  -e NEXTORA_API_URL="https://your-domain.com/api" \
+  -e NEXTORA_API_KEY="nxt_your_key_here" \
+  blacksptech/nextora-mcp:latest
+```
+
+จากนั้นเปลี่ยน command ใน config เป็น:
+
+```json
+{
+  "mcpServers": {
+    "nextora": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "NEXTORA_API_URL=https://your-domain.com/api",
+        "-e", "NEXTORA_API_KEY=nxt_your_key_here",
+        "blacksptech/nextora-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 8. ตัวอย่างบทสนทนา
+
+### บันทึกรายจ่าย
+```
+You: บันทึกค่าน้ำมัน 500 บาท เมื่อวานนี้
+AI: ✅ บันทึกแล้ว
+    Type:     Expense
+    Amount:   500
+    Category: Transport
+    Date:     2026-07-03
+```
+
+### วิเคราะห์ใบเสร็จ
+```
+You: ส่งรูปใบเสร็จนี้แล้วบันทึกด้วย: /Users/me/receipt.png
+AI: 📋 ผลการวิเคราะห์:
+    Type:    Expense
+    Amount:  1,250
+    Vendor:  ห้างสรรพสินค้า ABC
+    Date:    2026-07-04
+    ✅ บันทึกแล้ว (Category: Shopping)
+```
+
+### ดูสรุปการเงิน
+```
+You: ยอดเดือนนี้เป็นยังไง
+AI: 💰 สรุปเดือนกรกฎาคม 2026
+    รายรับ:     45,000.00
+    รายจ่าย:    32,450.00
+    กำไรสุทธิ:  12,550.00 ✅
+```
+
+### ดูรายการล่าสุด
+```
+You: แสดง 5 รายการล่าสุด
+AI: 📊 5 รายการล่าสุด:
+    2026-07-04  -1,250.00  Shopping     ห้างฯ ABC
+    2026-07-04    -500.00  Transport    น้ำมัน
+    2026-07-03     -80.00  Food         กาแฟ
+    2026-07-02  +45,000.00 Salary       เงินเดือน
+    2026-07-01    -350.00  Utilities    ค่าไฟ
+```
+
+---
+
+## 9. Troubleshooting
+
+| ปัญหา | สาเหตุ | วิธีแก้ |
+|---|---|---|
+| `NEXTORA_API_URL is required` | ไม่ได้ set env var | ตรวจสอบ config ว่า env ครบ |
+| `Invalid API key` | Key ผิดหรือถูก revoke | ไปที่ Settings → API Keys → สร้างใหม่ |
+| `No AI API key configured` | ใช้ upload_receipt แต่ยังไม่ได้ set AI provider | Settings → Receipt scanning → เพิ่ม OpenAI/Claude key |
+| Tool ไม่ขึ้นใน AI client | Restart client หลัง save config | ปิด-เปิด Claude Desktop / VS Code ใหม่ |
+| `npx` ไม่ทำงาน | ไม่มี Node.js | ติดตั้ง Node.js LTS จาก nodejs.org |
+| Timeout | Network ช้าหรือ Nextora ไม่ตอบ | ตรวจ NEXTORA_API_URL ว่าเข้าถึงได้ |

package/readme.mcp_server.md

@@ -0,0 +1,266 @@
+# Nextora MCP Server — วิธีการเขียนและโครงสร้าง
+
+## 1. MCP คืออะไร
+
+**Model Context Protocol (MCP)** คือมาตรฐานเปิด (Open Standard) ที่ Anthropic พัฒนาขึ้น เพื่อให้ AI Assistant สื่อสารกับระบบภายนอกได้แบบ standardized ทำหน้าที่คล้าย USB-C — "port" เดียว เชื่อมได้ทุก AI ที่รองรับ
+
+```
+AI Client (Claude Desktop / Cursor / Cline)
+        │
+        │  JSON-RPC 2.0 over stdio / HTTP-SSE
+        ▼
+   MCP Server (nextora-mcp)
+        │
+        │  HTTP REST + X-Api-Key
+        ▼
+   Nextora API (.NET 10)
+        │
+        ▼
+   PostgreSQL
+```
+
+---
+
+## 2. โครงสร้างโปรเจกต์
+
+```
+mcp-server/
+├── src/
+│   ├── index.ts            ← Entry point — สร้าง server + register tools + connect transport
+│   ├── client.ts           ← Axios HTTP client wrapper + TypeScript types
+│   └── tools/
+│       ├── list_categories.ts   ← Tool: list_categories
+│       ├── add_transaction.ts   ← Tool: add_transaction
+│       ├── upload_receipt.ts    ← Tool: upload_receipt
+│       ├── get_balance.ts       ← Tool: get_balance
+│       └── list_transactions.ts ← Tool: list_transactions
+├── package.json
+├── tsconfig.json
+└── Dockerfile
+```
+
+---
+
+## 3. เทคโนโลยีที่ใช้
+
+| Package | เวอร์ชัน | หน้าที่ |
+|---|---|---|
+| `@modelcontextprotocol/sdk` | ^1.15 | MCP SDK (server, transport, tool registry) |
+| `axios` | ^1.9 | HTTP client ยิง REST API ไปที่ Nextora |
+| `zod` | ^3.24 | Schema validation สำหรับ tool arguments |
+| `typescript` | ^5.8 | Type safety ทั้ง project |
+| `tsx` | ^4.19 | Dev runner (run TypeScript โดยตรง) |
+
+**Runtime**: Node.js 22+, ES Module (`"type": "module"`)
+
+---
+
+## 4. วิธีการเขียน MCP Server
+
+### 4.1 สร้าง McpServer instance
+
+```typescript
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const server = new McpServer({
+  name: "nextora",     // ชื่อที่ AI client เห็น
+  version: "1.0.0",
+});
+```
+
+### 4.2 Register Tool
+
+แต่ละ tool ต้องมี 4 ส่วน:
+
+```typescript
+server.tool(
+  "tool_name",                    // 1. ชื่อ tool (snake_case)
+  "Description for AI to read",  // 2. คำอธิบาย — AI ใช้ตัดสินใจว่าจะเรียก tool ไหน
+  schemaObject.shape,             // 3. Zod schema ของ arguments
+  async (args) => {               // 4. Handler function
+    const text = await doSomething(args);
+    return { content: [{ type: "text", text }] };
+  }
+);
+```
+
+### 4.3 Schema ด้วย Zod
+
+```typescript
+// src/tools/add_transaction.ts
+import { z } from "zod";
+
+export const addTransactionSchema = z.object({
+  type: z.enum(["Income", "Expense"]).describe("Income or Expense"),
+  amount: z.number().positive().describe("Amount (positive number)"),
+  categoryName: z.string().describe("Category name, partial match OK"),
+  description: z.string().optional().describe("Optional note"),
+  transactionDate: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+});
+```
+
+> `.describe(...)` คือสิ่งที่ AI อ่านเพื่อเข้าใจว่า field นี้ใส่อะไร — เขียนให้ชัด
+
+### 4.4 API Client (Authentication)
+
+```typescript
+// src/client.ts
+import axios from "axios";
+
+export function createApiClient() {
+  return axios.create({
+    baseURL: process.env.NEXTORA_API_URL,
+    headers: {
+      "X-Api-Key": process.env.NEXTORA_API_KEY,  // API Key auth
+      "Content-Type": "application/json",
+    },
+    timeout: 30_000,
+  });
+}
+```
+
+API Key ถูกส่งผ่าน header `X-Api-Key` ทุก request (ไม่ใช่ JWT Bearer)
+
+### 4.5 Tool Logic ตัวอย่าง: add_transaction
+
+```typescript
+export async function addTransaction(client, args) {
+  // 1. หา category จากชื่อ (partial match)
+  const cats = await client.get("/transaction-categories");
+  const category = cats.data.find(c =>
+    c.type === args.type &&
+    c.name.toLowerCase().includes(args.categoryName.toLowerCase())
+  );
+
+  // 2. สร้าง transaction
+  const response = await client.post("/transactions", {
+    categoryId: category.id,
+    type: args.type,
+    amount: args.amount,
+    transactionDate: args.transactionDate ?? today,
+    description: args.description,
+  });
+
+  // 3. return plain text สำหรับ AI อ่าน
+  return `✅ Transaction recorded!\n  ID: ${response.data.id}\n  Amount: ${args.amount}`;
+}
+```
+
+### 4.6 Transport: stdio
+
+```typescript
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("Nextora MCP server running\n");
+  // stderr = ข้อความ log, ไม่รบกวน JSON-RPC stream ที่ไปที่ stdout
+}
+```
+
+**Stdio transport** = AI client launch process นี้ขึ้นมา แล้วคุยกันผ่าน stdin/stdout เป็น JSON-RPC 2.0
+
+---
+
+## 5. Tools ที่ implement
+
+### 5.1 `list_categories`
+- เรียก `GET /api/transaction-categories`
+- รองรับ filter by type (Income / Expense / All)
+- Return: รายการ category พร้อม ID
+
+### 5.2 `add_transaction`
+- รับ: type, amount, categoryName (partial), description?, date?
+- Logic: หา category → สร้าง transaction
+- Smart matching: ชื่อ category ไม่ต้องตรงพอดี
+
+### 5.3 `upload_receipt`
+- รับ: imagePath (absolute path ในเครื่อง AI client)
+- อ่านไฟล์ → base64 → ส่งไป `POST /api/transactions/analyze-image`
+- API วิเคราะห์ด้วย Claude / OpenAI / Gemini Vision
+- ถ้า `autoRecord: true` (default) → สร้าง transaction อัตโนมัติ
+
+### 5.4 `get_balance`
+- เรียก `GET /api/reports/net-summary?from=&to=`
+- Default: เดือนปัจจุบัน
+- Return: รายรับ / รายจ่าย / กำไร-ขาดทุน
+
+### 5.5 `list_transactions`
+- เรียก `GET /api/transactions?from=&to=`
+- รองรับ filter by date, type, limit
+- Return: ตาราง + summary
+
+---
+
+## 6. Backend ที่เพิ่มเพื่อรองรับ MCP
+
+### 6.1 API Key Authentication
+
+เพิ่ม scheme ใหม่ใน ASP.NET Core:
+
+```
+Header: X-Api-Key: nxt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+`ApiKeyAuthenticationHandler` จะ:
+1. Hash raw key ด้วย SHA-256
+2. ค้นหาใน `api_keys` table
+3. Load user + permissions จาก DB
+4. Build `ClaimsPrincipal` เหมือน JWT (ใช้ policy เดิมได้เลย)
+
+### 6.2 Receipt Analysis Endpoint
+
+`POST /api/transactions/analyze-image`
+
+```json
+{
+  "imageBase64": "...",
+  "mimeType": "image/jpeg"
+}
+```
+
+ส่งต่อไปยัง AI provider ที่ org configure ไว้:
+- **Claude**: `POST https://api.anthropic.com/v1/messages` model `claude-haiku-4-5-20251001`
+- **OpenAI**: `POST https://api.openai.com/v1/chat/completions` model `gpt-4o-mini`
+- **Gemini**: `POST https://generativelanguage.googleapis.com/...gemini-1.5-flash`
+
+---
+
+## 7. Build & Run
+
+```bash
+# Install dependencies
+cd mcp-server
+npm install
+
+# Dev (run directly)
+NEXTORA_API_URL=http://localhost:8080/api \
+NEXTORA_API_KEY=nxt_xxx \
+npm run dev
+
+# Build for production
+npm run build
+node dist/index.js
+
+# Docker
+docker build -t nextora-mcp .
+docker run -i \
+  -e NEXTORA_API_URL="https://your-domain/api" \
+  -e NEXTORA_API_KEY="nxt_xxx" \
+  nextora-mcp
+```
+
+> `-i` (interactive / stdin open) จำเป็นสำหรับ stdio transport
+
+---
+
+## 8. Pattern สำคัญ
+
+| Pattern | เหตุผล |
+|---|---|
+| `stderr` สำหรับ log | stdout ถูก JSON-RPC ใช้งานอยู่ — ห้าม `console.log` |
+| Zod `.describe()` ครบทุก field | AI อ่านเพื่อเข้าใจว่าต้องส่งอะไร |
+| Return plain text | AI อ่านแล้วตอบ user ได้ทันที ไม่ต้อง parse JSON |
+| `autoRecord: true` default | UX ดีกว่า — user บอก "ส่งใบเสร็จ" ก็บันทึกเลย |
+| Partial category match | ลด friction — user พิมพ์ "กาแฟ" แทน ID |