niffler-app-mcp 1.0.0

package/README.md

@@ -0,0 +1,160 @@
+# Niffler MCP Server
+
+Connect AI agents like Claude, Cursor, and Windsurf to your Niffler account. Save bookmarks, notes, tasks, and events — organized into categories — all from your AI assistant.
+
+## Getting Started
+
+### 1. Get your API key
+
+Open Niffler > **Settings** > **API Keys** and create a new key. Copy it — it starts with `nif_` and is only shown once.
+
+### 2. Add to your AI client
+
+#### Claude Code
+
+```bash
+claude mcp add niffler -- npx -y niffler-app-mcp
+```
+
+Then set the environment variable:
+
+```bash
+export NIFFLER_API_KEY=nif_your_key_here
+```
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "niffler": {
+      "command": "npx",
+      "args": ["-y", "niffler-app-mcp"],
+      "env": {
+        "NIFFLER_API_KEY": "nif_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Open **Settings** > **MCP Servers** > **Add Server**:
+
+- **Name:** Niffler
+- **Command:** `npx -y niffler-app-mcp`
+- **Environment:** `NIFFLER_API_KEY=nif_your_key_here`
+
+#### Windsurf
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "niffler": {
+      "command": "npx",
+      "args": ["-y", "niffler-app-mcp"],
+      "env": {
+        "NIFFLER_API_KEY": "nif_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### VS Code / Copilot
+
+Add to your `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "niffler": {
+      "command": "npx",
+      "args": ["-y", "niffler-app-mcp"],
+      "env": {
+        "NIFFLER_API_KEY": "nif_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Other MCP Clients
+
+Any MCP-compatible client can connect using:
+
+- **Command:** `npx -y niffler-app-mcp`
+- **Environment variable:** `NIFFLER_API_KEY` (required)
+- **Transport:** stdio
+
+## Available Tools
+
+### Browse & Search
+
+| Tool | Description |
+|------|-------------|
+| `list_categories` | List all your spaces with name, emoji, and type (list or planner) |
+| `get_items` | List items in a category — filter by type, date, or completion |
+| `get_dividers` | List sections within a category |
+| `search` | Full-text search across all items |
+
+### Create
+
+| Tool | Description |
+|------|-------------|
+| `create_category` | Create a new space (list for collections, planner for scheduling) |
+| `create_bookmark` | Save a URL with title and description |
+| `create_note` | Create a markdown note |
+| `create_task` | Create a task with optional due date |
+| `create_event` | Create an event with start/end dates |
+| `create_divider` | Create a section separator to organize items |
+
+### Manage
+
+| Tool | Description |
+|------|-------------|
+| `update_item` | Update any item's title, description, URL, content, or due date |
+| `complete_task` | Mark a task as completed or incomplete |
+| `delete_item` | Permanently delete an item |
+
+### Utility
+
+| Tool | Description |
+|------|-------------|
+| `health_check` | Verify API connectivity and authentication |
+
+## Data Model
+
+The MCP server includes a built-in resource (`niffler://data-model`) that teaches your AI agent how Niffler works. The agent reads it automatically to make smart decisions about:
+
+- **Category types** — `list` for collections and research, `planner` for scheduling and trips
+- **Item types** — bookmarks (URLs), tasks (to-dos), events (calendar), notes (markdown), dividers (sections)
+- **Organization** — how to use sections, date-based placement, and category structure
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NIFFLER_API_KEY` | Yes | Your Niffler API key (starts with `nif_`) |
+| `NIFFLER_API_URL` | No | Custom API endpoint (defaults to Niffler production) |
+
+## Examples
+
+Once connected, you can say things like:
+
+- *"Save this article to my Reading List"*
+- *"Create a task to review the PR by Friday in my Work space"*
+- *"What bookmarks do I have about React?"*
+- *"Set up a new trip planner for Tokyo with sections for Hotels, Restaurants, and Activities"*
+- *"Show me my overdue tasks"*
+- *"Write a note summarizing our meeting discussion"*
+
+## Requirements
+
+- Node.js 18+
+- A Niffler account with an API key (Pro or Early Adopter plan)

package/dist/bin/niffler-mcp.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=niffler-mcp.d.ts.map

package/dist/bin/niffler-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"niffler-mcp.d.ts","sourceRoot":"","sources":["../../bin/niffler-mcp.ts"],"names":[],"mappings":""}

package/dist/bin/niffler-mcp.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/index.js";
+main();
+//# sourceMappingURL=niffler-mcp.js.map

package/dist/bin/niffler-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"niffler-mcp.js","sourceRoot":"","sources":["../../bin/niffler-mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC,IAAI,EAAE,CAAC"}

package/dist/src/client.d.ts

@@ -0,0 +1,90 @@
+import type { CategoriesResponse, ItemsResponse, DividersResponse, SearchResponse, CreateItemResponse, HealthResponse } from "./types.js";
+export declare class NifflerClient {
+    private baseUrl;
+    private apiKey;
+    constructor(apiKey: string, baseUrl: string);
+    private request;
+    listCategories(group?: string): Promise<CategoriesResponse>;
+    createCategory(data: {
+        name: string;
+        emoji?: string;
+        view_type?: "list" | "planner";
+        color?: string;
+        description?: string;
+    }): Promise<{
+        success: boolean;
+        category: {
+            id: string;
+        };
+        message: string;
+    }>;
+    getItems(category: string, filters?: {
+        type?: "all" | "tasks" | "bookmarks" | "notes";
+        date?: string;
+        completed?: "true" | "false" | "all";
+    }): Promise<ItemsResponse>;
+    getDividers(category: string): Promise<DividersResponse>;
+    createBookmark(data: {
+        url: string;
+        title?: string;
+        description?: string;
+        category_name?: string;
+        category_id?: string;
+        after_divider?: string;
+    }): Promise<CreateItemResponse>;
+    createNote(data: {
+        title: string;
+        note_content: string;
+        category_name?: string;
+        category_id?: string;
+        after_divider?: string;
+    }): Promise<CreateItemResponse>;
+    createTask(data: {
+        title: string;
+        due_date?: string;
+        description?: string;
+        category_name?: string;
+        category_id?: string;
+        after_divider?: string;
+    }): Promise<CreateItemResponse>;
+    createEvent(data: {
+        title: string;
+        event_start_date: string;
+        event_end_date: string;
+        event_is_all_day?: boolean;
+        description?: string;
+        category_name?: string;
+        category_id?: string;
+        after_divider?: string;
+    }): Promise<CreateItemResponse>;
+    createDivider(data: {
+        title: string;
+        category_name?: string;
+        category_id?: string;
+        after_divider?: string;
+    }): Promise<CreateItemResponse>;
+    search(query: string, limit?: number): Promise<SearchResponse>;
+    updateItem(itemId: string, updates: {
+        title?: string;
+        description?: string | null;
+        url?: string | null;
+        note_content?: string | null;
+        due_date?: string | null;
+        divider_title?: string;
+    }): Promise<{
+        success: boolean;
+        message: string;
+        item_id: string;
+    }>;
+    completeTask(itemId: string, completed: boolean): Promise<{
+        success: boolean;
+        message: string;
+        item_id: string;
+    }>;
+    deleteItem(itemId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    healthCheck(): Promise<HealthResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/src/client.js

@@ -0,0 +1,85 @@
+export class NifflerClient {
+    baseUrl;
+    apiKey;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            "x-api-key": this.apiKey,
+            "Content-Type": "application/json",
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await res.json();
+        if (!res.ok || data.success === false) {
+            throw new Error(data.error || `API error: ${res.status}`);
+        }
+        return data;
+    }
+    // Categories
+    async listCategories(group) {
+        const params = group ? `?group=${encodeURIComponent(group)}` : "";
+        return this.request("GET", `/categories${params}`);
+    }
+    async createCategory(data) {
+        return this.request("POST", "/categories", data);
+    }
+    // Items
+    async getItems(category, filters) {
+        const params = new URLSearchParams({ category });
+        if (filters?.type)
+            params.set("type", filters.type);
+        if (filters?.date)
+            params.set("date", filters.date);
+        if (filters?.completed)
+            params.set("completed", filters.completed);
+        return this.request("GET", `/items?${params}`);
+    }
+    async getDividers(category) {
+        return this.request("GET", `/dividers?category=${encodeURIComponent(category)}`);
+    }
+    // Create items
+    async createBookmark(data) {
+        return this.request("POST", "/bookmarks", data);
+    }
+    async createNote(data) {
+        return this.request("POST", "/notes", data);
+    }
+    async createTask(data) {
+        return this.request("POST", "/tasks", data);
+    }
+    async createEvent(data) {
+        return this.request("POST", "/events", data);
+    }
+    async createDivider(data) {
+        return this.request("POST", "/dividers", data);
+    }
+    // Search
+    async search(query, limit) {
+        return this.request("POST", "/search", { query, limit });
+    }
+    // Update items
+    async updateItem(itemId, updates) {
+        return this.request("PATCH", `/items/${itemId}`, updates);
+    }
+    async completeTask(itemId, completed) {
+        return this.request("PATCH", `/items/${itemId}/complete`, {
+            is_completed: completed,
+        });
+    }
+    // Delete
+    async deleteItem(itemId) {
+        return this.request("DELETE", `/items/${itemId}`);
+    }
+    // Health
+    async healthCheck() {
+        return this.request("GET", "/health");
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export declare function main(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,wBAAsB,IAAI,kBAkBzB"}

package/dist/src/index.js

@@ -0,0 +1,24 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+const DEFAULT_API_URL = "https://bnmfnuyxpempbsgoimcl.supabase.co/functions/v1/shortcuts-api";
+export async function main() {
+    const apiKey = process.env.NIFFLER_API_KEY;
+    if (!apiKey) {
+        console.error("Error: NIFFLER_API_KEY environment variable is required.");
+        console.error("Get your API key from Niffler > Settings > API Keys.");
+        process.exit(1);
+    }
+    if (!apiKey.startsWith("nif_")) {
+        console.error('Error: NIFFLER_API_KEY must start with "nif_".');
+        process.exit(1);
+    }
+    const apiUrl = process.env.NIFFLER_API_URL || DEFAULT_API_URL;
+    const server = createServer(apiKey, apiUrl);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error instanceof Error ? error.message : "Unknown error");
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,eAAe,GAAG,qEAAqE,CAAC;AAE9F,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC1E,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,eAAe,CAAC;IAE9D,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;IACxF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/src/resources/data-model.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDataModelResource(server: McpServer): void;
+//# sourceMappingURL=data-model.d.ts.map

package/dist/src/resources/data-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-model.d.ts","sourceRoot":"","sources":["../../../src/resources/data-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA4FpE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,QAmB1D"}

package/dist/src/resources/data-model.js

@@ -0,0 +1,104 @@
+const DATA_MODEL_GUIDE = `# Niffler Data Model Guide
+
+Niffler is an organizational tool for saving bookmarks, notes, tasks, and events into structured categories (called "spaces"). This guide helps you choose the right category type and item type.
+
+## Category Types
+
+### List (view_type: "list")
+A vertical list of items, optionally organized into sections using dividers.
+
+**Best for:**
+- Bookmark collections (articles, tools, resources)
+- Research notes
+- Reading lists
+- Shopping lists
+- Reference material
+- Any collection that doesn't need date-based scheduling
+
+**Example categories:** "React Resources", "Recipes to Try", "Gift Ideas", "Meeting Notes"
+
+### Planner (view_type: "planner")
+A calendar-based view showing items organized by date, with a 14-day lookahead and a "Someday" section for undated items.
+
+**Best for:**
+- Weekly task planning
+- Trip itineraries (flights, hotels, activities by day)
+- Project timelines
+- Event scheduling
+- Habit tracking
+- Any collection where items have dates or deadlines
+
+**Example categories:** "This Week", "Japan Trip", "Product Launch", "Workout Plan"
+
+## Item Types
+
+### Bookmark (Link)
+A saved URL with optional title and description.
+- **When to use:** Saving web pages, articles, tools, documentation, videos, any URL
+- **Required:** url
+- **Optional:** title (auto-detected), description
+
+### Task (Reminder)
+An actionable item that can be marked complete.
+- **When to use:** To-dos, action items, follow-ups, things to buy/do
+- **Required:** title
+- **Optional:** due_date (ISO 8601 UTC), description
+- **Note:** In planner categories, tasks with due dates appear on the corresponding day. Tasks without dates go to "Someday".
+
+### Event
+A time-bound occurrence with start and end dates.
+- **When to use:** Meetings, flights, appointments, reservations, deadlines with specific times
+- **Required:** title, event_start_date, event_end_date (both ISO 8601 UTC)
+- **Optional:** event_is_all_day, description
+
+### Note
+A markdown text document stored in Niffler.
+- **When to use:** Summaries, research findings, meeting notes, ideas, any text content
+- **Required:** title, note_content (markdown)
+- **Note:** Supports full markdown: headings, lists, links, code blocks, bold, italic
+
+### Divider (Section)
+A section separator that groups items within a category.
+- **When to use:** Organizing items into named groups (e.g., "Restaurants" / "Hotels" / "Activities" in a travel category)
+- **Required:** title (the section name)
+- **Note:** When creating items, use the after_divider parameter to place them under a specific section
+
+## Organization Patterns
+
+### Flat list
+Just add items to a category. Good for simple collections.
+
+### Sectioned list
+Create dividers first, then add items under each section:
+1. create_divider("Restaurants", category: "Tokyo Trip")
+2. create_divider("Hotels", category: "Tokyo Trip")
+3. create_bookmark(url, after_divider: "Restaurants", category: "Tokyo Trip")
+
+### Planner with dates
+Create items with due dates in a planner category:
+1. create_task("Pack bags", due_date: "2025-03-14T12:00:00Z", category: "Japan Trip")
+2. create_event("Flight to Tokyo", start: "2025-03-15T08:00:00Z", end: "2025-03-15T20:00:00Z", category: "Japan Trip")
+
+## API Conventions
+- Category names are matched case-insensitively
+- If a category doesn't exist and you use category_name, some endpoints auto-create it
+- Dates must be ISO 8601 UTC (ending in Z)
+- Use list_categories first to see existing spaces
+- Use get_dividers to see a category's structure before adding items
+- Item IDs are UUIDs — get them from get_items or search results
+`;
+export function registerDataModelResource(server) {
+    server.resource("data-model", "niffler://data-model", {
+        description: "Guide to Niffler's data model: category types (list vs planner), item types (bookmark, task, event, note, divider), and organization patterns. Read this first to understand how to structure content in Niffler.",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "niffler://data-model",
+                mimeType: "text/markdown",
+                text: DATA_MODEL_GUIDE,
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=data-model.js.map

package/dist/src/resources/data-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-model.js","sourceRoot":"","sources":["../../../src/resources/data-model.ts"],"names":[],"mappings":"AAEA,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwFxB,CAAC;AAEF,MAAM,UAAU,yBAAyB,CAAC,MAAiB;IACzD,MAAM,CAAC,QAAQ,CACb,YAAY,EACZ,sBAAsB,EACtB;QACE,WAAW,EACT,mNAAmN;QACrN,QAAQ,EAAE,eAAe;KAC1B,EACD,KAAK,IAAI,EAAE,CAAC,CAAC;QACX,QAAQ,EAAE;YACR;gBACE,GAAG,EAAE,sBAAsB;gBAC3B,QAAQ,EAAE,eAAe;gBACzB,IAAI,EAAE,gBAAgB;aACvB;SACF;KACF,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/src/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(apiKey: string, apiUrl: string): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/src/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQpE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAkBtE"}

package/dist/src/server.js

@@ -0,0 +1,23 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { NifflerClient } from "./client.js";
+import { registerCategoryTools } from "./tools/categories.js";
+import { registerItemCreationTools } from "./tools/items.js";
+import { registerReadTools } from "./tools/read.js";
+import { registerManageTools } from "./tools/manage.js";
+import { registerDataModelResource } from "./resources/data-model.js";
+export function createServer(apiKey, apiUrl) {
+    const server = new McpServer({
+        name: "Niffler",
+        version: "1.0.0",
+    });
+    const client = new NifflerClient(apiKey, apiUrl);
+    // Register all tools
+    registerCategoryTools(server, client);
+    registerItemCreationTools(server, client);
+    registerReadTools(server, client);
+    registerManageTools(server, client);
+    // Register resources
+    registerDataModelResource(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/src/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,MAAc;IACzD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjD,qBAAqB;IACrB,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpC,qBAAqB;IACrB,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAElC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/tools/categories.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { NifflerClient } from "../client.js";
+export declare function registerCategoryTools(server: McpServer, client: NifflerClient): void;
+//# sourceMappingURL=categories.d.ts.map

package/dist/src/tools/categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../../src/tools/categories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,QA0E7E"}

package/dist/src/tools/categories.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+export function registerCategoryTools(server, client) {
+    server.tool("list_categories", "List all Niffler spaces/categories. Returns name, emoji, view type (list or planner), and group. Use this first to see what exists before creating items.", {
+        group: z
+            .string()
+            .optional()
+            .describe('Filter by group name. Use "All" for all categories, or a specific group name.'),
+    }, async ({ group }) => {
+        const data = await client.listCategories(group);
+        const lines = data.categories.map((c) => `${c.emoji} ${c.name} (${c.view_type})${c.group_name ? ` [${c.group_name}]` : ""}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${data.categories.length} categories:\n\n${lines.join("\n")}\n\n${data.has_groups
+                        ? `Groups: ${data.groups.join(", ")}`
+                        : "No groups configured."}`,
+                },
+            ],
+        };
+    });
+    server.tool("create_category", "Create a new Niffler space/category. Use 'list' for collections, bookmarks, research notes. Use 'planner' for scheduling, tasks with dates, events, trip planning.", {
+        name: z.string().describe("Category name (e.g. 'Travel Research', 'Weekly Tasks')"),
+        emoji: z
+            .string()
+            .optional()
+            .describe("Emoji icon for the category (e.g. '✈️', '📋'). Defaults to '📁'."),
+        view_type: z
+            .enum(["list", "planner"])
+            .optional()
+            .describe("Category type. 'list' for collections/bookmarks/notes. 'planner' for calendar-based tasks/events. Defaults to 'list'."),
+        color: z
+            .string()
+            .optional()
+            .describe("Hex color for the category (e.g. '#6366f1'). Optional."),
+        description: z.string().optional().describe("Short description of the category. Optional."),
+    }, async ({ name, emoji, view_type, color, description }) => {
+        const data = await client.createCategory({
+            name,
+            emoji,
+            view_type,
+            color,
+            description,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Created category "${name}" (${view_type || "list"}) with ID: ${data.category.id}`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=categories.js.map

package/dist/src/tools/categories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.js","sourceRoot":"","sources":["../../../src/tools/categories.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,UAAU,qBAAqB,CAAC,MAAiB,EAAE,MAAqB;IAC5E,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,2JAA2J,EAC3J;QACE,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,+EAA+E,CAChF;KACJ,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAClB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAC/B,CAAC,CAAC,EAAE,EAAE,CACJ,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACrF,CAAC;QAEF,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,SAAS,IAAI,CAAC,UAAU,CAAC,MAAM,mBAAmB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OACtE,IAAI,CAAC,UAAU;wBACb,CAAC,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;wBACrC,CAAC,CAAC,uBACN,EAAE;iBACH;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,oKAAoK,EACpK;QACE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;QACnF,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,kEAAkE,CAAC;QAC/E,SAAS,EAAE,CAAC;aACT,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;aACzB,QAAQ,EAAE;aACV,QAAQ,CACP,uHAAuH,CACxH;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,wDAAwD,CAAC;QACrE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;KAC5F,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE;QACvD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC;YACvC,IAAI;YACJ,KAAK;YACL,SAAS;YACT,KAAK;YACL,WAAW;SACZ,CAAC,CAAC;QAEH,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,qBAAqB,IAAI,MAAM,SAAS,IAAI,MAAM,cAAc,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE;iBACzF;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/src/tools/items.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { NifflerClient } from "../client.js";
+export declare function registerItemCreationTools(server: McpServer, client: NifflerClient): void;
+//# sourceMappingURL=items.d.ts.map

package/dist/src/tools/items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"items.d.ts","sourceRoot":"","sources":["../../../src/tools/items.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,QAqNjF"}

package/dist/src/tools/items.js

@@ -0,0 +1,169 @@
+import { z } from "zod";
+export function registerItemCreationTools(server, client) {
+    server.tool("create_bookmark", "Save a URL/link to Niffler. Best for web pages, articles, tools, resources. The bookmark is saved to the specified category (or default if none given).", {
+        url: z.string().describe("The URL to bookmark"),
+        title: z.string().optional().describe("Title for the bookmark. Auto-detected if omitted."),
+        description: z.string().optional().describe("Short description or note about this link"),
+        category_name: z
+            .string()
+            .optional()
+            .describe("Category name to save into. Creates the category if it doesn't exist."),
+        category_id: z.string().optional().describe("Category ID (alternative to category_name)"),
+        after_divider: z
+            .string()
+            .optional()
+            .describe("Place the bookmark after this section/divider name. Use 'Top of category' for the top."),
+    }, async ({ url, title, description, category_name, category_id, after_divider }) => {
+        const data = await client.createBookmark({
+            url,
+            title,
+            description,
+            category_name,
+            category_id,
+            after_divider,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Bookmark saved: ${title || url} (ID: ${data.bookmark?.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("create_note", "Create a markdown note in Niffler. Best for text content, summaries, research notes, meeting notes, ideas. Supports full markdown.", {
+        title: z.string().describe("Note title"),
+        note_content: z
+            .string()
+            .describe("Markdown content for the note. Supports headings, lists, links, code blocks, etc."),
+        category_name: z
+            .string()
+            .optional()
+            .describe("Category name to save into. Creates the category if it doesn't exist."),
+        category_id: z.string().optional().describe("Category ID (alternative to category_name)"),
+        after_divider: z
+            .string()
+            .optional()
+            .describe("Place the note after this section/divider name."),
+    }, async ({ title, note_content, category_name, category_id, after_divider }) => {
+        const data = await client.createNote({
+            title,
+            note_content,
+            category_name,
+            category_id,
+            after_divider,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Note created: "${title}" (ID: ${data.note?.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("create_task", "Create a task/reminder in Niffler. Best for action items, to-dos, things to follow up on. Optionally set a due date. Works great in planner categories.", {
+        title: z.string().describe("Task description (e.g. 'Review PR #42', 'Buy groceries')"),
+        due_date: z
+            .string()
+            .optional()
+            .describe("Due date in ISO 8601 format (e.g. '2025-03-15T12:00:00Z'). For planner categories, this determines which day it appears on."),
+        description: z.string().optional().describe("Additional details about the task"),
+        category_name: z
+            .string()
+            .optional()
+            .describe("Category name to save into. Creates the category if it doesn't exist."),
+        category_id: z.string().optional().describe("Category ID (alternative to category_name)"),
+        after_divider: z
+            .string()
+            .optional()
+            .describe("Place the task after this section/divider name."),
+    }, async ({ title, due_date, description, category_name, category_id, after_divider }) => {
+        const data = await client.createTask({
+            title,
+            due_date,
+            description,
+            category_name,
+            category_id,
+            after_divider,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Task created: "${title}"${due_date ? ` (due: ${due_date})` : ""} (ID: ${data.task?.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("create_event", "Create a calendar event in Niffler. Best for meetings, appointments, scheduled activities. Requires start and end dates. Works great in planner categories.", {
+        title: z.string().describe("Event title (e.g. 'Team standup', 'Flight to NYC')"),
+        event_start_date: z
+            .string()
+            .describe("Event start date/time in ISO 8601 UTC (e.g. '2025-03-15T09:00:00Z')"),
+        event_end_date: z
+            .string()
+            .describe("Event end date/time in ISO 8601 UTC (e.g. '2025-03-15T10:00:00Z')"),
+        event_is_all_day: z
+            .boolean()
+            .optional()
+            .describe("Whether this is an all-day event. Defaults to false."),
+        description: z.string().optional().describe("Additional details about the event"),
+        category_name: z
+            .string()
+            .optional()
+            .describe("Category name to save into. Creates the category if it doesn't exist."),
+        category_id: z.string().optional().describe("Category ID (alternative to category_name)"),
+        after_divider: z
+            .string()
+            .optional()
+            .describe("Place the event after this section/divider name."),
+    }, async ({ title, event_start_date, event_end_date, event_is_all_day, description, category_name, category_id, after_divider, }) => {
+        const data = await client.createEvent({
+            title,
+            event_start_date,
+            event_end_date,
+            event_is_all_day,
+            description,
+            category_name,
+            category_id,
+            after_divider,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Event created: "${title}" (${event_start_date} → ${event_end_date}) (ID: ${data.event?.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("create_divider", "Create a section divider in a Niffler category. Dividers organize items into named groups within a category. For example: 'Restaurants', 'Hotels', 'Activities' in a travel category.", {
+        title: z.string().describe("Section name (e.g. 'Restaurants', 'Day 1', 'High Priority')"),
+        category_name: z
+            .string()
+            .optional()
+            .describe("Category name to create the divider in."),
+        category_id: z.string().optional().describe("Category ID (alternative to category_name)"),
+        after_divider: z
+            .string()
+            .optional()
+            .describe("Place this divider after an existing divider."),
+    }, async ({ title, category_name, category_id, after_divider }) => {
+        const data = await client.createDivider({
+            title,
+            category_name,
+            category_id,
+            after_divider,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Divider created: "${title}" (ID: ${data.divider?.id})`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=items.js.map

package/dist/src/tools/items.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"items.js","sourceRoot":"","sources":["../../../src/tools/items.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/manage.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { NifflerClient } from "../client.js";
+export declare function registerManageTools(server: McpServer, client: NifflerClient): void;
+//# sourceMappingURL=manage.d.ts.map

package/dist/src/tools/manage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manage.d.ts","sourceRoot":"","sources":["../../../src/tools/manage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,QA8F3E"}

package/dist/src/tools/manage.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+export function registerManageTools(server, client) {
+    server.tool("update_item", "Update an existing Niffler item. Can change title, description, URL, note content, due date, or divider title. Get the item ID from list_items or search first.", {
+        item_id: z.string().uuid().describe("The item's UUID (get this from get_items or search)"),
+        title: z.string().optional().describe("New title"),
+        description: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("New description (or null to clear)"),
+        url: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("New URL (or null to clear). Only for bookmark items."),
+        note_content: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("New markdown content (or null to clear). Only for note items."),
+        due_date: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("New due date in ISO 8601 (or null to clear). Only for task items."),
+        divider_title: z
+            .string()
+            .optional()
+            .describe("New section/divider title. Only for divider items."),
+    }, async ({ item_id, title, description, url, note_content, due_date, divider_title }) => {
+        const updates = {};
+        if (title !== undefined)
+            updates.title = title;
+        if (description !== undefined)
+            updates.description = description;
+        if (url !== undefined)
+            updates.url = url;
+        if (note_content !== undefined)
+            updates.note_content = note_content;
+        if (due_date !== undefined)
+            updates.due_date = due_date;
+        if (divider_title !== undefined)
+            updates.divider_title = divider_title;
+        const data = await client.updateItem(item_id, updates);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Item updated: ${data.item_id} — ${Object.keys(updates).join(", ")} changed.`,
+                },
+            ],
+        };
+    });
+    server.tool("complete_task", "Mark a task as completed or uncompleted in Niffler. Get the task ID from get_items or search first.", {
+        item_id: z.string().uuid().describe("The task's UUID"),
+        completed: z.boolean().describe("true to mark complete, false to mark incomplete"),
+    }, async ({ item_id, completed }) => {
+        await client.completeTask(item_id, completed);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Task ${item_id} marked as ${completed ? "completed ✅" : "incomplete ☐"}.`,
+                },
+            ],
+        };
+    });
+    server.tool("delete_item", "Permanently delete an item from Niffler. This cannot be undone. Get the item ID from get_items or search first.", {
+        item_id: z.string().uuid().describe("The item's UUID to delete"),
+    }, async ({ item_id }) => {
+        await client.deleteItem(item_id);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Item ${item_id} deleted permanently.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=manage.js.map

package/dist/src/tools/manage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manage.js","sourceRoot":"","sources":["../../../src/tools/manage.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/read.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { NifflerClient } from "../client.js";
+export declare function registerReadTools(server: McpServer, client: NifflerClient): void;
+//# sourceMappingURL=read.d.ts.map

package/dist/src/tools/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/tools/read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,QAuJzE"}

package/dist/src/tools/read.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+export function registerReadTools(server, client) {
+    server.tool("get_items", "List items in a Niffler category. Returns bookmarks, tasks, notes, and events. Filter by type, date, or completion status.", {
+        category: z.string().describe("Category name (case-insensitive match)"),
+        type: z
+            .enum(["all", "tasks", "bookmarks", "notes"])
+            .optional()
+            .describe("Filter by item type. Defaults to 'all'."),
+        date: z
+            .string()
+            .optional()
+            .describe("Filter by date: 'today', 'tomorrow', 'someday' (no date), or a specific date 'YYYY-MM-DD'. Useful for planner categories."),
+        completed: z
+            .enum(["true", "false", "all"])
+            .optional()
+            .describe("Filter tasks by completion: 'true', 'false', or 'all'. Defaults to 'all'."),
+    }, async ({ category, type, date, completed }) => {
+        const data = await client.getItems(category, { type, date, completed });
+        if (data.items.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No items found in "${data.category_name}"${type ? ` (type: ${type})` : ""}${date ? ` (date: ${date})` : ""}.`,
+                    },
+                ],
+            };
+        }
+        const lines = data.items.map((item) => {
+            const prefix = item.type === "task"
+                ? item.is_completed
+                    ? "✅"
+                    : "☐"
+                : item.type === "event"
+                    ? "📅"
+                    : item.type === "note"
+                        ? "📝"
+                        : "🔗";
+            let line = `${prefix} ${item.title}`;
+            if (item.url)
+                line += ` — ${item.url}`;
+            if (item.due_date)
+                line += ` (due: ${item.due_date})`;
+            if (item.description)
+                line += `\n   ${item.description}`;
+            line += ` [id: ${item.id}]`;
+            return line;
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${data.category_name} — ${data.count} items:\n\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    });
+    server.tool("get_dividers", "List sections/dividers in a Niffler category. For list categories, returns section names. For planner categories, returns the next 14 days. Use this to understand category structure before adding items.", {
+        category: z.string().describe("Category name (case-insensitive match)"),
+    }, async ({ category }) => {
+        const data = await client.getDividers(category);
+        if (data.is_calendar) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `"${data.category_name}" is a planner category.\nAvailable date slots:\n${data.names.join("\n")}`,
+                    },
+                ],
+            };
+        }
+        if (!data.has_dividers) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `"${data.category_name}" has no sections/dividers. Items are in a flat list.`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `"${data.category_name}" sections:\n${data.names.join("\n")}`,
+                },
+            ],
+        };
+    });
+    server.tool("search", "Full-text search across all Niffler items (bookmarks, notes, tasks, events). Searches titles, descriptions, URLs, and note content.", {
+        query: z.string().describe("Search query text"),
+        limit: z
+            .number()
+            .optional()
+            .describe("Max results to return (1-50, default 10)"),
+    }, async ({ query, limit }) => {
+        const data = await client.search(query, limit);
+        if (data.results.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No results found for "${query}".`,
+                    },
+                ],
+            };
+        }
+        const lines = data.results.map((r) => {
+            let line = `${r.category_emoji || "📁"} [${r.category_name}] ${r.title}`;
+            if (r.url)
+                line += ` — ${r.url}`;
+            if (r.type === "task")
+                line += r.is_completed ? " ✅" : " ☐";
+            if (r.due_date)
+                line += ` (due: ${r.due_date})`;
+            line += ` [id: ${r.id}]`;
+            return line;
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${data.results.length} results for "${query}":\n\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=read.js.map

package/dist/src/tools/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/tools/read.ts"],"names":[],"mappings":"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"}

package/dist/src/types.d.ts

@@ -0,0 +1,90 @@
+export interface Category {
+    id: string;
+    name: string;
+    emoji: string;
+    color: string;
+    description: string | null;
+    group_name: string | null;
+    view_type: "list" | "planner";
+}
+export interface Item {
+    id: string;
+    title: string;
+    url?: string;
+    description?: string;
+    note_content?: string;
+    due_date?: string;
+    is_completed: boolean;
+    type: "bookmark" | "task" | "note" | "event";
+    event_start_date?: string;
+    event_end_date?: string;
+    event_is_all_day?: boolean;
+    created_at: string;
+}
+export interface Divider {
+    id: string;
+    name: string;
+    sort_order: number;
+}
+export interface SearchResult extends Item {
+    category_name: string;
+    category_emoji: string;
+    score: number;
+}
+export interface ApiResponse<T = unknown> {
+    success: boolean;
+    error?: string;
+    [key: string]: T | boolean | string | undefined;
+}
+export interface CategoriesResponse {
+    success: boolean;
+    categories: Category[];
+    names: string[];
+    groups: string[];
+    has_groups: boolean;
+}
+export interface ItemsResponse {
+    success: boolean;
+    category_name: string;
+    count: number;
+    items: Item[];
+}
+export interface DividersResponse {
+    success: boolean;
+    category_id: string;
+    category_name: string;
+    is_calendar: boolean;
+    dividers?: Divider[];
+    names: string[];
+    has_dividers: boolean;
+}
+export interface SearchResponse {
+    success: boolean;
+    query: string;
+    results: SearchResult[];
+}
+export interface CreateItemResponse {
+    success: boolean;
+    bookmark?: {
+        id: string;
+    };
+    note?: {
+        id: string;
+    };
+    task?: {
+        id: string;
+    };
+    event?: {
+        id: string;
+    };
+    divider?: {
+        id: string;
+    };
+    message?: string;
+}
+export interface HealthResponse {
+    success: boolean;
+    message: string;
+    user_id: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "niffler-app-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Niffler – save, organize, and retrieve bookmarks, notes, tasks, and events via AI agents",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "bin": {
+    "niffler-mcp": "dist/bin/niffler-mcp.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/bin/niffler-mcp.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "niffler",
+    "bookmarks",
+    "ai-agent",
+    "claude"
+  ],
+  "license": "MIT"
+}