@jclvsh/xmark 0.2.1 → 0.4.0

package/README.md

@@ -21,7 +21,7 @@ npx -y -p @jclvsh/xmark xmark --help
 Set your xmark API key (get one at [/settings/api](https://xmark.dev/settings/api)):
 
 ```bash
-export XMARK_API_KEY=xm_live_...
+export XMARK_API_KEY=nt_live_...
 ```
 
 Optionally override the API host (default is `https://api.xmark.dev`):
@@ -39,7 +39,11 @@ export XMARK_API_URL=https://api.xmark.dev
 | `sync_bookmarks` | Pull the latest bookmarks from X. |
 | `list_bookmarks` | Paginated bookmark list. |
 | `get_bookmark` | Fetch a single bookmark by ID. |
+| `delete_bookmark` | Remove a bookmark (local-only, or also on X with `unbookmark`). |
 | `list_conversations` | Past chat conversations. |
+| `get_conversation_messages` | A conversation's message history. |
+| `delete_conversation` | Permanently delete a conversation. |
+| `get_usage` | Plan + quota usage (chat this month, syncs today, bookmark count). |
 
 ## CLI commands
 
@@ -48,12 +52,21 @@ xmark search "what did I save about Claude?"
 xmark chat "summarize what I saved this month about agents"
 xmark sync
 xmark list --page 1 --page-size 20
+xmark get <bookmark-id>
+xmark delete <bookmark-id> --unbookmark
 xmark conversations
+xmark messages <conversation-id>
+xmark delete-conversation <conversation-id>
+xmark usage
 ```
 
+Global flags: `--format table` renders paginated lists as a table (default is `json`).
+
+Structured exit codes for scripting: `2` validation, `3` rate limit, `4` auth, `5` payment/billing, `6` not found, `1` anything else.
+
 ## Pricing
 
-xmark is $5/month flat. The same subscription covers the web app, CLI, MCP server, and developer REST API — no separate API tier.
+Free tier: 20 chat messages/month, 1 sync/day. Pro is $5/month — unlimited chat and sync. The same plan covers the web app, CLI, MCP server, and developer REST API — no separate API tier.
 
 ## Links
 

package/dist/cli-utils.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared CLI + MCP output helpers.
+ *
+ * The CLI consumes these for terminal output (table / JSON / structured exit
+ * codes). MCP tools consume `formatMcpError` so error responses surface the
+ * structured `{success, error: {code, message}}` envelope to the LLM instead
+ * of a flattened message string — lets the model branch on `error.code`
+ * without regex-extracting the bracketed prefix.
+ */
+export declare function formatOutput(data: unknown, format?: string): void;
+/**
+ * Map a fleet error-code prefix to a CLI exit code.
+ *
+ * Convention so shell scripts can branch on failure type without parsing stderr:
+ * - 0: success (not handled here)
+ * - 1: generic / unknown
+ * - 2: input / validation (SERVER_VALIDATION_FAILED, SERVER_BAD_REQUEST)
+ * - 3: rate limit
+ * - 4: auth (AUTH_*, APIKEY_*)
+ * - 5: payment / billing (PAYMENT_*, BILLING_*)
+ * - 6: not found (any *_NOT_FOUND)
+ *
+ * Domain-specific codes (e.g. CAMP_001, LAUNCH_001) are categorized by their
+ * suffix shape — *_NOT_FOUND maps to 6, others fall through to 1.
+ */
+export declare function exitCodeForMessage(message: string): number;
+export declare function handleError(error: unknown): never;
+/**
+ * Parse the `[CODE] message (field: x)` string format that the API client's
+ * handleError builds, recovering the structured fields.
+ *
+ * Returns `{code, message, field?}`. Falls back to `{code: "UNKNOWN_ERROR", message}`
+ * when no bracketed code is present (shouldn't happen for API errors, but safe
+ * for client-side throws like network timeouts).
+ */
+export declare function parseErrorMessage(raw: string): {
+    code: string;
+    message: string;
+    field?: string;
+};
+/**
+ * Format an error caught in an MCP tool handler as the structured response
+ * the MCP SDK returns to the model.
+ *
+ * Returns the canonical v1 error envelope `{success: false, error: {code, message, field?}}`
+ * as JSON text inside the MCP `content` block, plus `isError: true` so the SDK
+ * surfaces it as an error to the model. Lets the LLM read `error.code`
+ * structurally instead of regexing it out of a flattened message.
+ */
+export declare function formatMcpError(error: unknown): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};
+export declare function getFormat(opts: Record<string, unknown>): string;
+export declare function parseList(value: string): string[];

package/dist/cli-utils.js

@@ -0,0 +1,127 @@
+/**
+ * Shared CLI + MCP output helpers.
+ *
+ * The CLI consumes these for terminal output (table / JSON / structured exit
+ * codes). MCP tools consume `formatMcpError` so error responses surface the
+ * structured `{success, error: {code, message}}` envelope to the LLM instead
+ * of a flattened message string — lets the model branch on `error.code`
+ * without regex-extracting the bracketed prefix.
+ */
+export function formatOutput(data, format = "json") {
+    if (format === "table" && typeof data === "object" && data !== null) {
+        const obj = data;
+        if (Array.isArray(obj.data)) {
+            console.table(obj.data);
+            if (obj.pagination) {
+                const p = obj.pagination;
+                console.error(`\npage ${p.page}/${p.total_pages} (${p.total} total)`);
+            }
+            return;
+        }
+        if (obj.data && typeof obj.data === "object") {
+            console.log(JSON.stringify(obj.data, null, 2));
+            return;
+        }
+    }
+    console.log(JSON.stringify(data, null, 2));
+}
+/**
+ * Map a fleet error-code prefix to a CLI exit code.
+ *
+ * Convention so shell scripts can branch on failure type without parsing stderr:
+ * - 0: success (not handled here)
+ * - 1: generic / unknown
+ * - 2: input / validation (SERVER_VALIDATION_FAILED, SERVER_BAD_REQUEST)
+ * - 3: rate limit
+ * - 4: auth (AUTH_*, APIKEY_*)
+ * - 5: payment / billing (PAYMENT_*, BILLING_*)
+ * - 6: not found (any *_NOT_FOUND)
+ *
+ * Domain-specific codes (e.g. CAMP_001, LAUNCH_001) are categorized by their
+ * suffix shape — *_NOT_FOUND maps to 6, others fall through to 1.
+ */
+export function exitCodeForMessage(message) {
+    const codeMatch = message.match(/\[([A-Z]+)_(\d+|[A-Z_]+)\]/);
+    if (!codeMatch)
+        return 1;
+    const prefix = codeMatch[1];
+    const suffix = codeMatch[2];
+    // Suffix-based: *_NOT_FOUND → 6 regardless of prefix
+    if (suffix.includes("NOT_FOUND"))
+        return 6;
+    switch (prefix) {
+        case "AUTH":
+        case "APIKEY":
+            return 4;
+        case "RATE":
+            return 3;
+        case "PAYMENT":
+        case "BILLING":
+            return 5;
+        case "SERVER":
+            // SERVER_002/005 = validation; SERVER_003 = not found; rest = generic
+            if (suffix === "002" || suffix === "005")
+                return 2;
+            if (suffix === "003")
+                return 6;
+            return 1;
+        default:
+            return 1;
+    }
+}
+export function handleError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`error: ${message}`);
+    process.exit(exitCodeForMessage(message));
+}
+/**
+ * Parse the `[CODE] message (field: x)` string format that the API client's
+ * handleError builds, recovering the structured fields.
+ *
+ * Returns `{code, message, field?}`. Falls back to `{code: "UNKNOWN_ERROR", message}`
+ * when no bracketed code is present (shouldn't happen for API errors, but safe
+ * for client-side throws like network timeouts).
+ */
+export function parseErrorMessage(raw) {
+    // Format: "[CODE] message (field: x)" — code optional, field optional
+    const match = raw.match(/^\[([A-Z_0-9]+)\]\s+(.*?)(?:\s+\(field:\s+([^)]+)\))?$/);
+    if (!match)
+        return { code: "UNKNOWN_ERROR", message: raw };
+    return {
+        code: match[1],
+        message: match[2],
+        ...(match[3] && { field: match[3] }),
+    };
+}
+/**
+ * Format an error caught in an MCP tool handler as the structured response
+ * the MCP SDK returns to the model.
+ *
+ * Returns the canonical v1 error envelope `{success: false, error: {code, message, field?}}`
+ * as JSON text inside the MCP `content` block, plus `isError: true` so the SDK
+ * surfaces it as an error to the model. Lets the LLM read `error.code`
+ * structurally instead of regexing it out of a flattened message.
+ */
+export function formatMcpError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const parsed = parseErrorMessage(raw);
+    const envelope = {
+        success: false,
+        error: parsed,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+        isError: true,
+    };
+}
+export function getFormat(opts) {
+    if (opts.json)
+        return "json";
+    return opts.format || "json";
+}
+export function parseList(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}

package/dist/cli.js

@@ -1,68 +1,37 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { Command } from "commander";
 import { XmarkClient } from "./client.js";
-const program = new Command();
-program
+import { handleError } from "./cli-utils.js";
+import { registerBookmarkCommands } from "./commands/bookmarks.js";
+import { registerChatCommands } from "./commands/chat.js";
+import { registerUsageCommands } from "./commands/usage.js";
+const pkg = createRequire(import.meta.url)("../package.json");
+const program = new Command()
     .name("xmark")
     .description("xmark CLI — chat with your X bookmarks from the terminal")
-    .version("0.1.0");
-function client() {
-    return new XmarkClient();
-}
-program
-    .command("search <query>")
-    .description("Semantic search over your bookmarks ($0.04/call for agents)")
-    .option("-l, --limit <n>", "max results", "10")
-    .action(async (query, opts) => {
-    const result = await client().post("/bookmarks/search", {
-        query,
-        limit: parseInt(opts.limit, 10),
-    });
-    console.log(JSON.stringify(result, null, 2));
-});
-program
-    .command("chat <question...>")
-    .description("Ask a question about your bookmarks ($0.20/call for agents)")
-    .option("-c, --conversation <id>", "continue an existing conversation")
-    .action(async (questionParts, opts) => {
-    const question = questionParts.join(" ");
-    const result = await client().post("/chat", {
-        question,
-        ...(opts.conversation && { conversationId: opts.conversation }),
-    });
-    console.log(result.answer);
-    console.log("\nCitations:");
-    for (const c of result.citations) {
-        console.log(`  @${c.author} — ${c.snippet}\n  ${c.tweet_url}`);
-    }
-});
-program
-    .command("sync")
-    .description("Trigger a fresh sync from X")
-    .action(async () => {
-    const result = await client().post("/bookmarks/sync");
-    console.log(`Synced ${result.count} bookmarks (${result.newCount} new, ${result.removedCount} removed) in ${result.durationMs}ms.`);
-});
-program
-    .command("list")
-    .description("List your bookmarks")
-    .option("-p, --page <n>", "page number", "1")
-    .option("-s, --page-size <n>", "items per page", "50")
-    .action(async (opts) => {
-    const result = await client().get("/bookmarks", {
-        page: parseInt(opts.page, 10),
-        pageSize: parseInt(opts.pageSize, 10),
+    .version(pkg.version)
+    .option("--json", "output as JSON (default)")
+    .option("--format <fmt>", "output format: json, table", "json");
+try {
+    // Lazy client: defer the XmarkClient constructor (which throws when
+    // XMARK_API_KEY is missing) until a command actually issues an HTTP call.
+    // `xmark -V`, `xmark --help`, `xmark chat --help` etc. never touch the API,
+    // so they exit cleanly without an API key set.
+    let realClient = null;
+    const client = new Proxy({}, {
+        get(_target, prop, receiver) {
+            if (!realClient)
+                realClient = new XmarkClient();
+            const value = Reflect.get(realClient, prop, receiver);
+            return typeof value === "function" ? value.bind(realClient) : value;
+        },
     });
-    console.log(JSON.stringify(result, null, 2));
-});
-program
-    .command("conversations")
-    .description("List your past chat conversations")
-    .action(async () => {
-    const result = await client().get("/conversations");
-    console.log(JSON.stringify(result, null, 2));
-});
-program.parseAsync(process.argv).catch((err) => {
-    console.error(err instanceof Error ? err.message : err);
-    process.exit(1);
-});
+    registerBookmarkCommands(program, client);
+    registerChatCommands(program, client);
+    registerUsageCommands(program, client);
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    handleError(error);
+}

package/dist/client.d.ts

@@ -1,10 +1,23 @@
+import type { Paginated } from "./types.js";
 export declare class XmarkClient {
     private apiKey;
     private baseUrl;
     constructor(apiKey?: string, baseUrl?: string);
     get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+    /**
+     * GET a paginated list endpoint, preserving the pagination envelope
+     * (`get`/`request` unwrap to `data`, which silently drops it).
+     */
+    getPage<T>(path: string, params?: Record<string, string | number | undefined>): Promise<Paginated<T>>;
     post<T>(path: string, body?: unknown): Promise<T>;
     delete(path: string): Promise<void>;
     private request;
+    /** fetch with auth + UA + timeout, translating timeouts and network failures to readable errors. */
+    private fetchWithGuards;
+    /**
+     * Build the fleet-standard `[CODE] message (field: x)` error, the format
+     * cli-utils' exitCodeForMessage / parseErrorMessage recover structurally.
+     */
+    private apiError;
     private handleError;
 }

package/dist/client.js

@@ -1,5 +1,6 @@
 const REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_BASE_URL = "https://api.xmark.dev";
+const USER_AGENT = "xmark-mcp/0.4.0";
 export class XmarkClient {
     apiKey;
     baseUrl;
@@ -21,6 +22,28 @@ export class XmarkClient {
         }
         return this.request(url.toString(), { method: "GET" });
     }
+    /**
+     * GET a paginated list endpoint, preserving the pagination envelope
+     * (`get`/`request` unwrap to `data`, which silently drops it).
+     */
+    async getPage(path, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined && v !== "")
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const response = await this.fetchWithGuards(url.toString(), { method: "GET" });
+        if (!response.ok) {
+            await this.handleError(response);
+        }
+        const json = (await response.json());
+        if (!json.success) {
+            throw this.apiError(json.error);
+        }
+        return { data: json.data, pagination: json.pagination };
+    }
     async post(path, body) {
         return this.request(`${this.baseUrl}${path}`, {
             method: "POST",
@@ -29,45 +52,76 @@ export class XmarkClient {
         });
     }
     async delete(path) {
-        const response = await fetch(`${this.baseUrl}${path}`, {
-            method: "DELETE",
-            headers: { Authorization: `Bearer ${this.apiKey}` },
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
+        const response = await this.fetchWithGuards(`${this.baseUrl}${path}`, { method: "DELETE" });
         if (!response.ok && response.status !== 204) {
             await this.handleError(response);
         }
     }
     async request(url, init) {
-        const response = await fetch(url, {
-            ...init,
-            headers: {
-                ...init.headers,
-                Authorization: `Bearer ${this.apiKey}`,
-                "User-Agent": "xmark-mcp/0.1.0",
-            },
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
+        const response = await this.fetchWithGuards(url, init);
         if (!response.ok) {
             await this.handleError(response);
         }
         const json = (await response.json());
         if (!json.success) {
-            throw new Error(`${json.error.code}: ${json.error.message}`);
+            throw this.apiError(json.error);
         }
         return json.data;
     }
+    /** fetch with auth + UA + timeout, translating timeouts and network failures to readable errors. */
+    async fetchWithGuards(url, init) {
+        try {
+            return await fetch(url, {
+                ...init,
+                headers: {
+                    ...(init.headers || {}),
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "User-Agent": USER_AGENT,
+                },
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError") {
+                throw new Error("request timed out after 30s");
+            }
+            if (error instanceof TypeError) {
+                throw new Error(`network error: ${error.message}. check XMARK_API_URL and your connection`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Build the fleet-standard `[CODE] message (field: x)` error, the format
+     * cli-utils' exitCodeForMessage / parseErrorMessage recover structurally.
+     */
+    apiError(error) {
+        let message = `[${error.code}] ${error.message}`;
+        if (error.field) {
+            message += ` (field: ${error.field})`;
+        }
+        return new Error(message);
+    }
     async handleError(response) {
-        let detail = "";
+        let errorMessage;
         try {
             const body = (await response.json());
-            if (body?.error) {
-                detail = `${body.error.code}: ${body.error.message}`;
+            if (body.error) {
+                errorMessage = this.apiError(body.error).message;
+            }
+            else {
+                errorMessage = `API error: ${response.status} ${response.statusText}`;
             }
         }
         catch {
-            detail = await response.text().catch(() => "");
+            errorMessage = `API error: ${response.status} ${response.statusText}`;
+        }
+        if (response.status === 429) {
+            const retryAfter = response.headers.get("Retry-After");
+            if (retryAfter) {
+                errorMessage += ` — retry after ${retryAfter}s`;
+            }
         }
-        throw new Error(`xmark API ${response.status} ${response.statusText}${detail ? ` — ${detail}` : ""}`);
+        throw new Error(errorMessage);
     }
 }

package/dist/commands/bookmarks.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { XmarkClient } from "../client.js";
+export declare function registerBookmarkCommands(program: Command, client: XmarkClient): void;

package/dist/commands/bookmarks.js

@@ -0,0 +1,73 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerBookmarkCommands(program, client) {
+    program
+        .command("search <query>")
+        .description("Semantic search over your bookmarks")
+        .option("-l, --limit <n>", "max results", "10")
+        .action(async (query, opts) => {
+        try {
+            const result = await client.post("/bookmarks/search", {
+                query,
+                limit: parseInt(opts.limit, 10),
+            });
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("sync")
+        .description("Trigger a fresh sync from X")
+        .action(async () => {
+        try {
+            const result = await client.post("/bookmarks/sync");
+            console.log(`Synced ${result.count} bookmarks (${result.newCount} new, ${result.removedCount} removed) in ${result.durationMs}ms.`);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("list")
+        .description("List your bookmarks")
+        .option("-p, --page <n>", "page number", "1")
+        .option("-s, --page-size <n>", "items per page", "50")
+        .action(async (opts) => {
+        try {
+            const result = await client.getPage("/bookmarks", {
+                page: parseInt(opts.page, 10),
+                pageSize: parseInt(opts.pageSize, 10),
+            });
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("get <id>")
+        .description("Fetch a single bookmark by ID")
+        .action(async (id) => {
+        try {
+            const result = await client.get(`/bookmarks/${id}`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("delete <id>")
+        .description("Remove a bookmark (local-only unless --unbookmark)")
+        .option("-u, --unbookmark", "also remove the bookmark on X, not just locally")
+        .action(async (id, opts) => {
+        try {
+            await client.delete(`/bookmarks/${id}${opts.unbookmark ? "?unbookmark=true" : ""}`);
+            console.log(opts.unbookmark ? "Removed from xmark and X." : "Removed from xmark (local only).");
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/chat.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { XmarkClient } from "../client.js";
+export declare function registerChatCommands(program: Command, client: XmarkClient): void;

package/dist/commands/chat.js

@@ -0,0 +1,60 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerChatCommands(program, client) {
+    program
+        .command("chat <question...>")
+        .description("Ask a question about your bookmarks")
+        .option("-c, --conversation <id>", "continue an existing conversation")
+        .action(async (questionParts, opts) => {
+        try {
+            const question = questionParts.join(" ");
+            const result = await client.post("/chat", {
+                question,
+                ...(opts.conversation && { conversationId: opts.conversation }),
+            });
+            console.log(result.answer);
+            console.log("\nCitations:");
+            for (const c of result.citations) {
+                console.log(`  @${c.author} — ${c.snippet}\n  ${c.tweet_url}`);
+            }
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("conversations")
+        .description("List your past chat conversations")
+        .action(async () => {
+        try {
+            const result = await client.getPage("/conversations");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("messages <conversationId>")
+        .description("A conversation's message history, oldest first")
+        .action(async (conversationId) => {
+        try {
+            const result = await client.get(`/conversations/${conversationId}/messages`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("delete-conversation <id>")
+        .description("Permanently delete a conversation and its messages")
+        .action(async (id) => {
+        try {
+            await client.delete(`/conversations/${id}`);
+            console.log("Conversation deleted.");
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/usage.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { XmarkClient } from "../client.js";
+export declare function registerUsageCommands(program: Command, client: XmarkClient): void;

package/dist/commands/usage.js

@@ -0,0 +1,15 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerUsageCommands(program, client) {
+    program
+        .command("usage")
+        .description("Your plan + quota usage (chat this month, syncs today, bookmark count)")
+        .action(async () => {
+        try {
+            const result = await client.get("/usage");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/index.js

@@ -1,15 +1,33 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { XmarkClient } from "./client.js";
 import { registerBookmarkTools } from "./tools/bookmarks.js";
 import { registerChatTools } from "./tools/chat.js";
+import { registerUsageTools } from "./tools/usage.js";
+const requireFromHere = createRequire(import.meta.url);
+const pkg = requireFromHere("../package.json");
 const server = new McpServer({
     name: "xmark",
-    version: "0.1.0",
+    version: pkg.version,
+});
+// Lazy client: defer the XmarkClient constructor (which throws when
+// XMARK_API_KEY is missing) until a tool invocation actually issues an HTTP
+// call. MCP discovery (initialize, tools/list) never touches the API, so the
+// server boots cleanly without an API key set and surfaces a structured error
+// only when a tool is invoked.
+let realClient = null;
+const client = new Proxy({}, {
+    get(_target, prop, receiver) {
+        if (!realClient)
+            realClient = new XmarkClient();
+        const value = Reflect.get(realClient, prop, receiver);
+        return typeof value === "function" ? value.bind(realClient) : value;
+    },
 });
-const client = new XmarkClient();
 registerBookmarkTools(server, client);
 registerChatTools(server, client);
+registerUsageTools(server, client);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/bookmarks.js

@@ -1,48 +1,85 @@
 import { z } from "zod";
+import { formatMcpError } from "../cli-utils.js";
 export function registerBookmarkTools(server, client) {
     server.tool("list_bookmarks", "List the authenticated user's X bookmarks. Paginated.", {
         page: z.number().int().min(1).default(1).describe("Page number (1-indexed)"),
         pageSize: z.number().int().min(1).max(100).default(50).describe("Items per page (max 100)"),
     }, async ({ page, pageSize }) => {
-        const result = await client.get("/bookmarks", {
-            page,
-            pageSize,
-        });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(result, null, 2),
-                },
-            ],
-        };
+        try {
+            const result = await client.getPage("/bookmarks", { page, pageSize });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
     });
     server.tool("get_bookmark", "Fetch a single bookmark by ID.", {
         id: z.string().uuid().describe("Bookmark UUID"),
     }, async ({ id }) => {
-        const result = await client.get(`/bookmarks/${id}`);
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
+        try {
+            const result = await client.get(`/bookmarks/${id}`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
     });
-    server.tool("search_bookmarks", "Semantic search over the user's bookmarks. Returns ranked matches with relevance scores. Charged at $0.04/call for agents (first 50/month free).", {
+    server.tool("search_bookmarks", "Semantic search over the user's bookmarks. Returns ranked matches with relevance scores.", {
         query: z.string().min(1).describe("Natural-language search query"),
         limit: z.number().int().min(1).max(50).default(10).describe("Max results to return"),
     }, async ({ query, limit }) => {
-        const result = await client.post("/bookmarks/search", { query, limit });
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
+        try {
+            const result = await client.post("/bookmarks/search", { query, limit });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
     });
-    server.tool("sync_bookmarks", "Trigger a fresh sync from X. Pulls latest bookmarks, embeds new ones for semantic search.", {}, async () => {
-        const result = await client.post("/bookmarks/sync");
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Synced ${result.count} bookmarks (${result.newCount} new, ${result.removedCount} removed) in ${result.durationMs}ms.`,
-                },
-            ],
-        };
+    server.tool("sync_bookmarks", "Trigger a fresh sync from X. Pulls latest bookmarks, embeds new ones for semantic search. Free tier allows one sync per day.", {}, async () => {
+        try {
+            const result = await client.post("/bookmarks/sync");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Synced ${result.count} bookmarks (${result.newCount} new, ${result.removedCount} removed) in ${result.durationMs}ms.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("delete_bookmark", "Remove a bookmark. Local-only by default — the next sync re-creates anything still bookmarked on X. Set unbookmark=true to also remove it on X (sticks across syncs; requires a connected X account).", {
+        id: z.string().uuid().describe("Bookmark UUID"),
+        unbookmark: z.boolean().default(false).describe("Also remove the bookmark on X, not just locally"),
+    }, async ({ id, unbookmark }) => {
+        try {
+            await client.delete(`/bookmarks/${id}${unbookmark ? "?unbookmark=true" : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: unbookmark ? "Bookmark removed from xmark and X." : "Bookmark removed from xmark (local only).",
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
     });
 }

package/dist/tools/chat.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
+import { formatMcpError } from "../cli-utils.js";
 export function registerChatTools(server, client) {
-    server.tool("chat", "Ask a natural-language question about the user's X bookmarks. Returns an answer with citations back to the original tweets. Charged at $0.20/call for agents.", {
+    server.tool("chat", "Ask a natural-language question about the user's X bookmarks. Returns an answer with citations back to the original tweets. Free tier includes 20 chat messages per month.", {
         question: z.string().min(1).describe("The question to ask"),
         conversationId: z
             .string()
@@ -15,30 +16,66 @@ export function registerChatTools(server, client) {
             .default(5)
             .describe("Maximum citations to include in the answer"),
     }, async ({ question, conversationId, maxCitations }) => {
-        const result = await client.post("/chat", {
-            question,
-            ...(conversationId && { conversationId }),
-            maxCitations,
-        });
-        const citations = result.citations
-            .map((c, i) => `[${i + 1}] @${c.author} — ${c.snippet}\n    ${c.tweet_url}`)
-            .join("\n");
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `${result.answer}\n\nCitations:\n${citations}\n\nConversation ID: ${result.conversation_id}`,
-                },
-            ],
-        };
+        try {
+            const result = await client.post("/chat", {
+                question,
+                ...(conversationId && { conversationId }),
+                maxCitations,
+            });
+            const citations = result.citations
+                .map((c, i) => `[${i + 1}] @${c.author} — ${c.snippet}\n    ${c.tweet_url}`)
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${result.answer}\n\nCitations:\n${citations}\n\nConversation ID: ${result.conversation_id}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
     });
     server.tool("list_conversations", "List the user's past chat conversations. Paginated.", {
         page: z.number().int().min(1).default(1),
         pageSize: z.number().int().min(1).max(100).default(50),
     }, async ({ page, pageSize }) => {
-        const result = await client.get("/conversations", { page, pageSize });
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
+        try {
+            const result = await client.getPage("/conversations", { page, pageSize });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("get_conversation_messages", "A conversation's message history, oldest first. Assistant messages carry the IDs of the bookmarks retrieved for that answer.", {
+        conversationId: z.string().uuid().describe("Conversation UUID"),
+    }, async ({ conversationId }) => {
+        try {
+            const result = await client.get(`/conversations/${conversationId}/messages`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("delete_conversation", "Permanently delete a conversation and its messages. Free tier allows one concurrent conversation, so deleting is how a free account starts a fresh chat.", {
+        conversationId: z.string().uuid().describe("Conversation UUID"),
+    }, async ({ conversationId }) => {
+        try {
+            await client.delete(`/conversations/${conversationId}`);
+            return {
+                content: [{ type: "text", text: "Conversation deleted." }],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
     });
 }

package/dist/tools/usage.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { XmarkClient } from "../client.js";
+export declare function registerUsageTools(server: McpServer, client: XmarkClient): void;

package/dist/tools/usage.js

@@ -0,0 +1,14 @@
+import { formatMcpError } from "../cli-utils.js";
+export function registerUsageTools(server, client) {
+    server.tool("get_usage", "The authenticated user's plan and quota usage: chat messages this month, syncs today, bookmark count, and whether an X account is connected. Limits are null on unlimited plans.", {}, async () => {
+        try {
+            const result = await client.get("/usage");
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+}

package/dist/types.d.ts

@@ -20,12 +20,13 @@ export interface Bookmark {
     author: {
         username: string;
         name: string;
-        id: string;
+        id?: string;
+        profile_image_url?: string | null;
     };
-    bookmarked_at: string;
+    bookmarked_at: string | null;
     url?: string;
-    media?: unknown[];
-    topics?: string[];
+    public_metrics?: Record<string, number> | null;
+    media?: unknown[] | null;
 }
 export interface BookmarkSearchResult {
     bookmark: Bookmark;
@@ -50,9 +51,30 @@ export interface SyncResult {
 }
 export interface Conversation {
     id: string;
-    title: string;
+    title: string | null;
     created_at: string;
-    message_count: number;
+    updated_at: string;
+}
+export interface Message {
+    id: string;
+    role: string;
+    content: string;
+    retrieved_bookmark_ids: string[] | null;
+    created_at: string;
+}
+export interface QuotaUsage {
+    used: number;
+    /** null = unlimited */
+    limit: number | null;
+}
+export interface UsageData {
+    plan: string;
+    x_connected: boolean;
+    bookmarks: {
+        total: number;
+    };
+    chat: QuotaUsage;
+    syncs_today: QuotaUsage;
 }
 export interface PaginationMeta {
     page: number;
@@ -60,3 +82,7 @@ export interface PaginationMeta {
     total: number;
     totalPages: number;
 }
+export interface Paginated<T> {
+    data: T[];
+    pagination: PaginationMeta;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/xmark",
-	"version": "0.2.1",
+	"version": "0.4.0",
 	"description": "MCP server and CLI for the xmark API — chat with your X bookmarks from inside Claude Code, Cursor, or any MCP client.",
 	"type": "module",
 	"main": "dist/index.js",
@@ -44,7 +44,8 @@
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/jclvsh/xmark.git"
+		"url": "git+https://github.com/JCLVSH/monorepo.git",
+		"directory": "apps/xmark/packages/mcp"
 	},
 	"homepage": "https://xmark.dev"
 }