folosat-mcp 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# folosat-mcp
+
+Connect AI assistants (Claude, ChatGPT, Cursor) to [Folosat](https://folosat.com) — your income allocation system, savings goals, group expenses, and wealth overview.
+
+Available in **English and Arabic** — the only bilingual personal finance MCP server.
+
+---
+
+## What this MCP server exposes
+
+### Resources (read-only data your AI can query)
+
+| Resource | What it returns |
+|---|---|
+| `folosat://buckets` | Your 5-bucket income allocation — balances, targets, % used |
+| `folosat://transactions/{period}` | Categorized transactions for a period |
+| `folosat://goals` | All savings goals — progress, contribution history, projected completion |
+| `folosat://groups/{id}/balances` | Who owes whom in a group expense split |
+| `folosat://wealth/networth` | Net worth snapshot and time series |
+| `folosat://budget/{id}/summary` | Budget manager spending vs. plan |
+
+### Tools (actions, always require your approval)
+
+| Tool | What it does |
+|---|---|
+| `create_expense` | Add a new expense to your account |
+| `add_goal_contribution` | Contribute to a savings goal |
+| `get_cashflow_forecast` | 30 or 60-day cash flow projection |
+
+### Built-in prompts
+
+- `/monthly_review` — How was my spending vs. plan this month?
+- `/salary_allocation` — I just got paid — how should I allocate it?
+- `/goal_check` — Am I on track for all my savings goals?
+
+---
+
+## Example conversations
+
+**Check your month:**
+> "How did my spending look this month versus my plan?"
+
+**Plan a purchase:**
+> "I want to buy a laptop for $800. Can I afford it without hurting my savings goals?"
+
+**Group trip:**
+> "Did everyone settle up from the Dubai trip?"
+
+**Salary day:**
+> "I just received my salary of 12,000 SAR. How should I split it across my buckets?"
+
+---
+
+## Status
+
+> **Coming soon.** Full live integration is under active development.
+>
+> The server spec and namespace are published. Authentication and live data access will be available in a future release.
+>
+> [Get Folosat](https://folosat.com) to be notified when the MCP integration launches.
+
+---
+
+## Installation (when available)
+
+```json
+{
+  "mcpServers": {
+    "folosat": {
+      "command": "npx",
+      "args": ["folosat-mcp"]
+    }
+  }
+}
+```
+
+Add this to your Claude Desktop config at:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+---
+
+## Philosophy
+
+Folosat is built around the **Income Growth System** — not just tracking where your money went, but actively directing it toward growing what you earn. The 5-bucket allocation (Obligations / Investment / Personal / Reserve / Savings) gives every riyal and dollar a purpose before you spend it.
+
+The MCP integration brings this system into your AI assistant — so you can ask natural questions about your finances and get answers grounded in your actual data.
+
+---
+
+## Links
+
+- [Folosat app](https://folosat.com)
+- [GitHub](https://github.com/eng-mohaemad/folosat_testing)

package/dist/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Folosat MCP server — stub
+// Full implementation coming in a future release.
+// See README.md for the planned resources, tools, and prompts.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListResourcesRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const server = new Server({ name: "folosat-mcp", version: "0.1.0" }, { capabilities: { resources: {}, tools: {}, prompts: {} } });
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+        {
+            uri: "folosat://buckets",
+            name: "Income Buckets",
+            description: "5-bucket income allocation — balances, targets, % used",
+            mimeType: "application/json",
+        },
+        {
+            uri: "folosat://goals",
+            name: "Savings Goals",
+            description: "All savings goals — progress, contribution history, projected completion",
+            mimeType: "application/json",
+        },
+        {
+            uri: "folosat://wealth/networth",
+            name: "Net Worth",
+            description: "Net worth snapshot and time series",
+            mimeType: "application/json",
+        },
+    ],
+}));
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "create_expense",
+            description: "Add a new expense to Folosat. Requires user confirmation.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    amount: { type: "number" },
+                    category: { type: "string" },
+                    note: { type: "string" },
+                },
+                required: ["amount", "category"],
+            },
+        },
+        {
+            name: "add_goal_contribution",
+            description: "Contribute to a savings goal. Requires user confirmation.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    goal_id: { type: "string" },
+                    amount: { type: "number" },
+                    note: { type: "string" },
+                },
+                required: ["goal_id", "amount"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: [
+        {
+            name: "monthly_review",
+            description: "How was my spending vs. plan this month?",
+        },
+        {
+            name: "salary_allocation",
+            description: "I just got paid — how should I allocate it?",
+            arguments: [{ name: "amount", description: "Salary amount", required: true }],
+        },
+        {
+            name: "goal_check",
+            description: "Am I on track for all my savings goals?",
+        },
+    ],
+}));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("Folosat MCP server running. Full integration coming soon — see https://folosat.com");

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "folosat-mcp",
+  "version": "0.1.0",
+  "description": "Folosat MCP server — connect AI assistants to your income, expenses, savings goals, and group finances",
+  "keywords": [
+    "mcp",
+    "personal-finance",
+    "budgeting",
+    "savings",
+    "groups",
+    "expense-splitting",
+    "wealth",
+    "income",
+    "arabic",
+    "bilingual"
+  ],
+  "homepage": "https://folosat.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eng-mohaemad/folosat_testing"
+  },
+  "license": "MIT",
+  "mcpName": "io.github.eng-mohaemad/folosat-mcp",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "folosat-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/server.json

@@ -0,0 +1,112 @@
+{
+  "name": "folosat-mcp",
+  "version": "0.1.0",
+  "description": "Connect AI assistants to Folosat — your income allocation, savings goals, group expenses, and wealth overview. Available in English and Arabic.",
+  "homepage": "https://folosat.com",
+  "icon": "https://folosat.com/icon.png",
+  "categories": ["finance", "productivity", "personal-finance"],
+  "languages": ["en", "ar"],
+  "transport": [
+    {
+      "type": "stdio",
+      "command": "node",
+      "args": ["dist/index.js"]
+    }
+  ],
+  "resources": [
+    {
+      "name": "buckets",
+      "uri": "folosat://buckets",
+      "description": "5-bucket income allocation — Obligations, Investment, Personal, Reserve, Savings. Current balances and % vs. targets."
+    },
+    {
+      "name": "transactions",
+      "uri": "folosat://transactions/{period}",
+      "description": "Categorized transaction history for a given period (e.g. 'current-month', 'last-month', 'last-3-months')."
+    },
+    {
+      "name": "goals",
+      "uri": "folosat://goals",
+      "description": "Savings goals — name, target amount, current amount, contribution history, projected completion date."
+    },
+    {
+      "name": "group_balances",
+      "uri": "folosat://groups/{group_id}/balances",
+      "description": "Who owes whom in a group expense split. Pending settlements and confirmed ones."
+    },
+    {
+      "name": "net_worth",
+      "uri": "folosat://wealth/networth",
+      "description": "Net worth snapshot — wealth containers, savings, debts — and a time series of how it has changed."
+    },
+    {
+      "name": "budget_summary",
+      "uri": "folosat://budget/{budget_id}/summary",
+      "description": "Budget manager spending vs. allocated amounts for the current period."
+    }
+  ],
+  "tools": [
+    {
+      "name": "create_expense",
+      "description": "Add a new expense to Folosat. Requires user confirmation before executing.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "amount": { "type": "number" },
+          "category": { "type": "string" },
+          "note": { "type": "string" },
+          "group_id": { "type": "string", "description": "Optional — assign to a group expense" }
+        },
+        "required": ["amount", "category"]
+      }
+    },
+    {
+      "name": "add_goal_contribution",
+      "description": "Add a contribution to a savings goal. Requires user confirmation before executing.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "goal_id": { "type": "string" },
+          "amount": { "type": "number" },
+          "note": { "type": "string" }
+        },
+        "required": ["goal_id", "amount"]
+      }
+    },
+    {
+      "name": "get_cashflow_forecast",
+      "description": "Read-only forecast — based on current income allocation and spending patterns, projects cash flow for the next 30 or 60 days.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "days": { "type": "number", "enum": [30, 60] }
+        },
+        "required": ["days"]
+      }
+    }
+  ],
+  "prompts": [
+    {
+      "name": "monthly_review",
+      "description": "How was my spending vs. plan this month?",
+      "template": "Review my Folosat data for the current month. Compare actual spending in each bucket against the planned allocation. Highlight any buckets where I overspent or underspent significantly, and give me 1-2 concrete suggestions."
+    },
+    {
+      "name": "salary_allocation",
+      "description": "I just got paid — how should I allocate it?",
+      "template": "I just received a salary of {amount}. Based on my current Folosat bucket setup, obligations, and savings goals, suggest how to distribute this amount across my buckets. Show the breakdown and explain the reasoning."
+    },
+    {
+      "name": "goal_check",
+      "description": "Am I on track for my savings goals?",
+      "template": "Check all my active savings goals in Folosat. For each one, tell me whether I'm on track to hit the target by the deadline, how much I need to contribute per month to stay on track, and flag any that are falling behind."
+    }
+  ],
+  "auth": {
+    "type": "oauth2",
+    "description": "Authenticate with your Folosat account via OAuth 2.1 + PKCE. You will be redirected to folosat.com to authorize access.",
+    "status": "coming-soon"
+  },
+  "status": "coming-soon",
+  "availability": "This MCP server is under active development. Full integration with live Folosat data will be available in a future release. Follow @folosat for updates."
+}