mursa-mcp 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Murali Gurajapu
+
+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,125 @@
+# Mursa MCP
+
+Connect Claude Code, Claude Desktop, Cursor, or any MCP-compatible client to
+your Mursa tasks, calendar, goals, notes, habits, projects, and Gmail.
+
+📖 **Full guide with screenshots:** https://mursa.me/mcp
+
+---
+
+## 60-second install
+
+### 1. Get an API key
+
+1. Open [dashboard.mursa.me](https://dashboard.mursa.me) and sign in.
+2. Go to **Settings → API keys**.
+3. Click **New key** → pick a label, expiry, and scopes → **Create**.
+4. Copy the key (starts with `mursa_mcp_…`). You'll only see it once.
+
+### 2. Add to your client
+
+#### Claude Code (`~/.claude.json`)
+
+```json
+{
+  "mcpServers": {
+    "mursa": {
+      "command": "npx",
+      "args": ["-y", "mursa-mcp"],
+      "env": { "MURSA_API_KEY": "mursa_mcp_…" }
+    }
+  }
+}
+```
+
+Restart Claude Code, run `/mcp` to confirm, call `whoami` to verify.
+
+#### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+or `%APPDATA%/Claude/claude_desktop_config.json` (Windows) with the same block,
+then restart the app.
+
+#### Cursor
+
+Settings → MCP → Add new MCP server, same JSON block.
+
+### 3. That's it
+
+Your agent now has access to whatever scopes your key has.
+
+---
+
+## Tools (28)
+
+| Group | Tools | Scope |
+|---|---|---|
+| Meta | `whoami` | (any) |
+| Tasks (read) | `list_inbox`, `list_myday`, `list_schedule`, `search_tasks` | `tasks:read` |
+| Tasks (write) | `create_task`, `update_task`, `complete_task`, `defer_task`, `schedule_task` | `tasks:write` |
+| Calendar | `list_calendar`, `create_calendar_event` | `calendar:*` |
+| Goals | `list_goals`, `create_goal`, `update_goal`, `delete_goal` | `goals:*` |
+| Notes | `list_notes`, `search_notes`, `create_note`, `update_note` | `notes:*` |
+| Habits | `list_habits` | `habits:read` |
+| Projects | `list_projects` | `projects:read` |
+| Email | `list_emails`, `get_email`, `get_attachment`, `search_emails` | `email:read` |
+| Email | `send_email`, `reply_email` | `email:send` |
+
+`*` as a scope grants everything.
+
+---
+
+## Security
+
+- API keys are sha256-hashed at rest — the raw value is never stored.
+- Per-key scopes + expiry. Revoke any key instantly from the dashboard.
+- Per-action rate limits (60/min reads, 30/min writes, **5/min email send**).
+- Every call audit-logged for 90 days (action, status, latency, IP — no payload).
+- Email attachments capped at 3 MB each / 10 MB total per email.
+- All traffic goes through `mursa.me/api/mcp`; the Supabase function is gated
+  by a shared proxy secret so direct hits return 403.
+
+---
+
+## Run from source (advanced)
+
+```bash
+git clone https://github.com/Murali1889/Prod-Mursa.git
+cd Prod-Mursa/mcp-servers/mursa
+npm install
+echo 'MURSA_API_KEY=mursa_mcp_…' > .env
+```
+
+Then point your client at the absolute path:
+
+```json
+{
+  "mcpServers": {
+    "mursa": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-servers/mursa/server.js"]
+    }
+  }
+}
+```
+
+Override the endpoint for preview deployments or local dev:
+
+```
+MURSA_API_URL=https://mursa-preview.vercel.app/api/mcp
+```
+
+(Default is `https://mursa.me/api/mcp`.)
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Invalid, expired, or revoked API key` | Mint a fresh key in the dashboard, swap `MURSA_API_KEY`, restart your client. |
+| `This API key is missing the required scope: …` | Your key wasn't granted that scope at mint time. Revoke and mint a new one with the scope checked. |
+| `Gmail is not connected. Connect Gmail in Mursa Settings first.` | Connect Gmail from the Mursa app first. |
+| `Rate limit exceeded (5/min for send_email)` | Slow down — strict throttle on outbound mail. |
+
+For server-side deployment (running your own Mursa instance), see `DEPLOY.md`.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mursa-mcp",
+  "version": "0.4.0",
+  "description": "Mursa MCP server — connect Claude, Cursor, and other MCP clients to your Mursa tasks, calendar, goals, notes, habits, projects, and Gmail.",
+  "main": "server.js",
+  "bin": {
+    "mursa-mcp": "server.js"
+  },
+  "type": "commonjs",
+  "files": [
+    "server.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "mursa",
+    "claude",
+    "claude-code",
+    "cursor",
+    "tasks",
+    "productivity"
+  ],
+  "license": "MIT",
+  "homepage": "https://mursa.me/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Murali1889/MCP-mursa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Murali1889/MCP-mursa/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^16.4.5",
+    "zod": "^4.3.6"
+  }
+}

package/server.js

@@ -0,0 +1,432 @@
+#!/usr/bin/env node
+/**
+ * Mursa MCP server (stdio).
+ *
+ * Architecture:
+ *   Claude/Cursor/etc.  ─stdio─>  this Node process
+ *                                       │
+ *                                       │  fetch() with
+ *                                       │  Authorization: Bearer <api key>
+ *                                       ▼
+ *                          Supabase Edge Function: mcp
+ *                                       │ resolves key -> user_id + scopes
+ *                                       ▼
+ *                                Supabase Postgres
+ *
+ * The MCP server holds NO Supabase secrets. It only knows:
+ *   - SUPABASE_URL   (public)
+ *   - MURSA_API_KEY  (opaque per-user key with scopes + expiry)
+ *
+ * Every tool below just maps to one edge-function action.
+ */
+
+require("dotenv").config({ path: require("path").join(__dirname, ".env") });
+
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const {
+  StdioServerTransport,
+} = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = require("zod");
+
+// Default to the public Mursa proxy. Override only if you're self-hosting or
+// pointing at a preview deployment.
+const MURSA_API_URL = process.env.MURSA_API_URL || "https://mursa.me/api/mcp";
+const MURSA_API_KEY = process.env.MURSA_API_KEY;
+
+if (!MURSA_API_KEY) {
+  console.error("[mursa-mcp] MURSA_API_KEY is not set in .env");
+  process.exit(1);
+}
+
+const ENDPOINT = MURSA_API_URL.replace(/\/$/, "");
+
+// ───────────────────────────── call() ─────────────────────────────
+
+async function call(action, args = {}) {
+  let res;
+  try {
+    res = await fetch(ENDPOINT, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${MURSA_API_KEY}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ action, args }),
+    });
+  } catch (e) {
+    throw new Error(`Network error calling ${ENDPOINT}: ${e.message}`);
+  }
+
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    throw new Error(`Non-JSON response (HTTP ${res.status})`);
+  }
+
+  if (!res.ok || body.error) {
+    throw new Error(body.error || `HTTP ${res.status}`);
+  }
+  return body.data;
+}
+
+function jsonContent(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+  };
+}
+
+function errorContent(err) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: `Error: ${err.message || String(err)}` }],
+  };
+}
+
+const server = new McpServer({ name: "mursa", version: "0.3.0" });
+
+function tool(name, description, schema, action) {
+  server.tool(name, description, schema, async (args) => {
+    try {
+      const data = await call(action, args ?? {});
+      return jsonContent(data);
+    } catch (err) {
+      return errorContent(err);
+    }
+  });
+}
+
+// ───────────────────────────── tools ─────────────────────────────
+
+// Meta
+tool("whoami", "Show which Mursa user this API key belongs to.", {}, "whoami");
+
+// Tasks: read
+tool(
+  "list_inbox",
+  "List Inbox tasks (unscheduled, personal, not completed by default).",
+  {
+    status: z.string().optional(),
+    limit: z.number().int().positive().max(200).optional(),
+    includeScheduled: z.boolean().optional(),
+  },
+  "list_inbox"
+);
+
+tool(
+  "list_myday",
+  "List tasks scheduled for a specific day (default today). Date: YYYY-MM-DD.",
+  { date: z.string().optional() },
+  "list_myday"
+);
+
+tool(
+  "list_schedule",
+  "List all scheduled tasks between startDate and endDate inclusive. Dates: YYYY-MM-DD.",
+  { startDate: z.string(), endDate: z.string() },
+  "list_schedule"
+);
+
+tool(
+  "search_tasks",
+  "Search task titles by ILIKE match. Returns most recently updated first.",
+  { query: z.string().min(1), limit: z.number().int().positive().max(100).optional() },
+  "search_tasks"
+);
+
+// Calendar (= time-blocked scheduled tasks)
+tool(
+  "list_calendar",
+  "List calendar events (scheduled tasks with start_time) between two dates. Dates: YYYY-MM-DD.",
+  { startDate: z.string(), endDate: z.string() },
+  "list_calendar"
+);
+
+tool(
+  "create_calendar_event",
+  "Create a calendar event (a task with scheduled_date + start_time/end_time, task_type='meeting' by default).",
+  {
+    title: z.string().min(1),
+    scheduled_date: z.string(),
+    start_time: z.string().optional(),
+    end_time: z.string().optional(),
+    duration_minutes: z.number().int().positive().optional(),
+    description: z.string().optional(),
+    why: z.string().optional(),
+    task_type: z.enum(["deep", "shallow", "admin", "meeting"]).optional(),
+    priority: z.enum(["low", "medium", "high", "urgent"]).optional(),
+  },
+  "create_calendar_event"
+);
+
+// Tasks: write
+tool(
+  "create_task",
+  "Create a task. With scheduled_date -> MyDay; without -> Inbox.",
+  {
+    title: z.string().min(1),
+    description: z.string().optional(),
+    priority: z.enum(["low", "medium", "high", "urgent"]).optional(),
+    due_date: z.string().optional(),
+    labels: z.array(z.string()).optional(),
+    category: z.string().optional(),
+    estimated_hours: z.number().nonnegative().optional(),
+    goal_id: z.string().optional(),
+    project_id: z.string().optional(),
+    scheduled_date: z.string().optional(),
+    start_time: z.string().optional(),
+    end_time: z.string().optional(),
+    duration_minutes: z.number().int().positive().optional(),
+    task_type: z.enum(["deep", "shallow", "admin", "meeting"]).optional(),
+    why: z.string().optional(),
+  },
+  "create_task"
+);
+
+tool(
+  "update_task",
+  "Patch any subset of editable fields on a task.",
+  {
+    task_id: z.string(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    status: z.string().optional(),
+    priority: z.string().optional(),
+    due_date: z.string().nullable().optional(),
+    labels: z.array(z.string()).optional(),
+    category: z.string().optional(),
+    estimated_hours: z.number().nonnegative().optional(),
+    goal_id: z.string().nullable().optional(),
+    project_id: z.string().nullable().optional(),
+    scheduled_date: z.string().nullable().optional(),
+    start_time: z.string().nullable().optional(),
+    end_time: z.string().nullable().optional(),
+    duration_minutes: z.number().int().positive().optional(),
+    task_type: z.string().optional(),
+    why: z.string().optional(),
+    sort_order: z.number().int().optional(),
+  },
+  "update_task"
+);
+
+tool(
+  "complete_task",
+  "Mark a task as completed.",
+  { task_id: z.string() },
+  "complete_task"
+);
+
+tool(
+  "defer_task",
+  "Set a task's due_date to a new date (does not change scheduled_date).",
+  { task_id: z.string(), new_date: z.string() },
+  "defer_task"
+);
+
+tool(
+  "schedule_task",
+  "Move a task onto a specific date (MyDay). Optionally set start/end time and duration.",
+  {
+    task_id: z.string(),
+    scheduled_date: z.string(),
+    start_time: z.string().optional(),
+    end_time: z.string().optional(),
+    duration_minutes: z.number().int().positive().optional(),
+    task_type: z.enum(["deep", "shallow", "admin", "meeting"]).optional(),
+  },
+  "schedule_task"
+);
+
+// Goals
+tool(
+  "list_goals",
+  "List your goals, optionally filtered by status ('active', 'completed', ...).",
+  { status: z.string().optional() },
+  "list_goals"
+);
+
+tool(
+  "create_goal",
+  "Create a goal.",
+  {
+    title: z.string().min(1),
+    description: z.string().optional(),
+    color: z.string().optional(),
+    target_date: z.string().optional(),
+    timeline_days: z.number().int().positive().optional(),
+    project_id: z.string().optional(),
+    status: z.string().optional(),
+    priority: z.number().int().min(1).max(5).optional(),
+    tags: z.array(z.string()).optional(),
+    horizon: z.string().optional(),
+    area: z.string().optional(),
+  },
+  "create_goal"
+);
+
+tool(
+  "update_goal",
+  "Patch a goal.",
+  {
+    goal_id: z.string(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    color: z.string().optional(),
+    progress: z.number().min(0).max(100).optional(),
+    target_date: z.string().nullable().optional(),
+    timeline_days: z.number().int().positive().optional(),
+    status: z.string().optional(),
+    priority: z.number().int().min(1).max(5).optional(),
+    is_archived: z.boolean().optional(),
+    tags: z.array(z.string()).optional(),
+    sort_order: z.number().int().optional(),
+    horizon: z.string().nullable().optional(),
+    area: z.string().nullable().optional(),
+  },
+  "update_goal"
+);
+
+tool(
+  "delete_goal",
+  "Delete a goal. Tasks that reference it are unlinked first (goal_id set to null).",
+  { goal_id: z.string() },
+  "delete_goal"
+);
+
+// Notes
+tool(
+  "list_notes",
+  "List notes, pinned first, then most recently updated.",
+  { limit: z.number().int().positive().max(200).optional() },
+  "list_notes"
+);
+
+tool(
+  "search_notes",
+  "Search note titles and content by ILIKE.",
+  { query: z.string().min(1), limit: z.number().int().positive().max(100).optional() },
+  "search_notes"
+);
+
+tool(
+  "create_note",
+  "Create a note.",
+  {
+    title: z.string().optional(),
+    content: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    color: z.string().optional(),
+  },
+  "create_note"
+);
+
+tool(
+  "update_note",
+  "Patch a note.",
+  {
+    note_id: z.string(),
+    title: z.string().optional(),
+    content: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    color: z.string().optional(),
+    isPinned: z.boolean().optional(),
+  },
+  "update_note"
+);
+
+// Habits & projects (read-only for v1)
+tool("list_habits", "List your active (non-archived) habits.", {}, "list_habits");
+tool("list_projects", "List your projects, most recently updated first.", {}, "list_projects");
+
+// ───────────────────────────── EMAIL (Gmail) ─────────────────────────────
+
+const sendAttachmentSchema = z.object({
+  filename: z.string().min(1),
+  mimeType: z.string().optional(),
+  contentBase64: z.string().min(1),
+});
+
+tool(
+  "list_emails",
+  "List Gmail threads in a label (default INBOX). Returns thread previews (subject/from/snippet/labels/unread).",
+  {
+    maxResults: z.number().int().min(1).max(50).optional(),
+    pageToken: z.string().optional(),
+    q: z.string().optional(),
+    label: z.string().optional(),
+  },
+  "list_emails"
+);
+
+tool(
+  "get_email",
+  "Get the full content of a thread or single message. Returns body text + HTML + attachment metadata (use get_attachment to download).",
+  {
+    threadId: z.string().optional(),
+    messageId: z.string().optional(),
+  },
+  "get_email"
+);
+
+tool(
+  "get_attachment",
+  "Download a single attachment from an email. Returns { size, contentBase64 } — decode the base64 to get the bytes.",
+  {
+    messageId: z.string(),
+    attachmentId: z.string(),
+  },
+  "get_attachment"
+);
+
+tool(
+  "search_emails",
+  "Search Gmail using Gmail's query syntax (e.g. 'from:alice has:attachment newer_than:7d'). Returns message ids; use get_email to fetch.",
+  {
+    query: z.string().min(1),
+    maxResults: z.number().int().min(1).max(50).optional(),
+  },
+  "search_emails"
+);
+
+tool(
+  "send_email",
+  "Send a new email. Attachments are base64-encoded; ≤3MB each, ≤10MB total. Rate-limited to 5/min.",
+  {
+    to: z.union([z.string(), z.array(z.string())]),
+    cc: z.union([z.string(), z.array(z.string())]).optional(),
+    bcc: z.union([z.string(), z.array(z.string())]).optional(),
+    subject: z.string().min(1),
+    bodyText: z.string().optional(),
+    bodyHtml: z.string().optional(),
+    attachments: z.array(sendAttachmentSchema).optional(),
+  },
+  "send_email"
+);
+
+tool(
+  "reply_email",
+  "Reply to an existing thread. Subject and recipient default to the last message's. Rate-limited to 5/min.",
+  {
+    threadId: z.string(),
+    to: z.union([z.string(), z.array(z.string())]).optional(),
+    cc: z.union([z.string(), z.array(z.string())]).optional(),
+    bcc: z.union([z.string(), z.array(z.string())]).optional(),
+    subject: z.string().optional(),
+    bodyText: z.string().optional(),
+    bodyHtml: z.string().optional(),
+    attachments: z.array(sendAttachmentSchema).optional(),
+  },
+  "reply_email"
+);
+
+// ───────────────────────────── main ─────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("[mursa-mcp] fatal:", err);
+  process.exit(1);
+});