@jclvsh/xmark 0.2.1 → 0.3.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,17 @@ 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
 ```
 
 ## 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.js

@@ -5,13 +5,13 @@ const program = new Command();
 program
     .name("xmark")
     .description("xmark CLI — chat with your X bookmarks from the terminal")
-    .version("0.1.0");
+    .version("0.3.0");
 function client() {
     return new XmarkClient();
 }
 program
     .command("search <query>")
-    .description("Semantic search over your bookmarks ($0.04/call for agents)")
+    .description("Semantic search over your bookmarks")
     .option("-l, --limit <n>", "max results", "10")
     .action(async (query, opts) => {
     const result = await client().post("/bookmarks/search", {
@@ -22,7 +22,7 @@ program
 });
 program
     .command("chat <question...>")
-    .description("Ask a question about your bookmarks ($0.20/call for agents)")
+    .description("Ask a question about your bookmarks")
     .option("-c, --conversation <id>", "continue an existing conversation")
     .action(async (questionParts, opts) => {
     const question = questionParts.join(" ");
@@ -49,17 +49,53 @@ program
     .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", {
+    const result = await client().getPage("/bookmarks", {
         page: parseInt(opts.page, 10),
         pageSize: parseInt(opts.pageSize, 10),
     });
     console.log(JSON.stringify(result, null, 2));
 });
+program
+    .command("get <id>")
+    .description("Fetch a single bookmark by ID")
+    .action(async (id) => {
+    const result = await client().get(`/bookmarks/${id}`);
+    console.log(JSON.stringify(result, null, 2));
+});
+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) => {
+    await client().delete(`/bookmarks/${id}${opts.unbookmark ? "?unbookmark=true" : ""}`);
+    console.log(opts.unbookmark ? "Removed from xmark and X." : "Removed from xmark (local only).");
+});
 program
     .command("conversations")
     .description("List your past chat conversations")
     .action(async () => {
-    const result = await client().get("/conversations");
+    const result = await client().getPage("/conversations");
+    console.log(JSON.stringify(result, null, 2));
+});
+program
+    .command("messages <conversationId>")
+    .description("A conversation's message history, oldest first")
+    .action(async (conversationId) => {
+    const result = await client().get(`/conversations/${conversationId}/messages`);
+    console.log(JSON.stringify(result, null, 2));
+});
+program
+    .command("delete-conversation <id>")
+    .description("Permanently delete a conversation and its messages")
+    .action(async (id) => {
+    await client().delete(`/conversations/${id}`);
+    console.log("Conversation deleted.");
+});
+program
+    .command("usage")
+    .description("Your plan + quota usage (chat this month, syncs today, bookmark count)")
+    .action(async () => {
+    const result = await client().get("/usage");
     console.log(JSON.stringify(result, null, 2));
 });
 program.parseAsync(process.argv).catch((err) => {

package/dist/client.d.ts

@@ -1,8 +1,14 @@
+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;

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.3.0";
 export class XmarkClient {
     apiKey;
     baseUrl;
@@ -21,6 +22,32 @@ 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 fetch(url.toString(), {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.apiKey}`, "User-Agent": USER_AGENT },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            await this.handleError(response);
+        }
+        const json = (await response.json());
+        if (!json.success) {
+            throw new Error(`${json.error.code}: ${json.error.message}`);
+        }
+        return { data: json.data, pagination: json.pagination };
+    }
     async post(path, body) {
         return this.request(`${this.baseUrl}${path}`, {
             method: "POST",
@@ -44,7 +71,7 @@ export class XmarkClient {
             headers: {
                 ...init.headers,
                 Authorization: `Bearer ${this.apiKey}`,
-                "User-Agent": "xmark-mcp/0.1.0",
+                "User-Agent": USER_AGENT,
             },
             signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });

package/dist/index.js

@@ -4,12 +4,14 @@ 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 server = new McpServer({
     name: "xmark",
-    version: "0.1.0",
+    version: "0.3.0",
 });
 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

@@ -4,10 +4,7 @@ export function registerBookmarkTools(server, client) {
         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,
-        });
+        const result = await client.getPage("/bookmarks", { page, pageSize });
         return {
             content: [
                 {
@@ -25,7 +22,7 @@ export function registerBookmarkTools(server, client) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    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 }) => {
@@ -34,7 +31,7 @@ export function registerBookmarkTools(server, client) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    server.tool("sync_bookmarks", "Trigger a fresh sync from X. Pulls latest bookmarks, embeds new ones for semantic search.", {}, async () => {
+    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 () => {
         const result = await client.post("/bookmarks/sync");
         return {
             content: [
@@ -45,4 +42,18 @@ export function registerBookmarkTools(server, client) {
             ],
         };
     });
+    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 }) => {
+        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).",
+                },
+            ],
+        };
+    });
 }

package/dist/tools/chat.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 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()
@@ -36,9 +36,25 @@ export function registerChatTools(server, client) {
         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 });
+        const result = await client.getPage("/conversations", { page, pageSize });
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
+    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 }) => {
+        const result = await client.get(`/conversations/${conversationId}/messages`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    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 }) => {
+        await client.delete(`/conversations/${conversationId}`);
+        return {
+            content: [{ type: "text", text: "Conversation deleted." }],
+        };
+    });
 }

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,8 @@
+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 () => {
+        const result = await client.get("/usage");
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

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.3.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",