@jclvsh/xmark 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @jclvsh/xmark
+
+MCP server and CLI for the [xmark](https://www.xmark.chat) API — chat with your X (Twitter) bookmarks from inside Claude Code, Cursor, or any MCP-compatible client.
+
+## What is xmark?
+
+xmark syncs your X bookmarks, embeds them with OpenAI, and lets you query them in natural language with citations back to the original tweets. This package wraps the [xmark REST API](https://api.xmark.chat/openapi.json) as an MCP server (for AI clients) and a CLI (for terminal use).
+
+## Install
+
+```bash
+# Run the MCP server (stdio transport)
+npx -y -p @jclvsh/xmark xmark-mcp
+
+# Or use the CLI directly
+npx -y -p @jclvsh/xmark xmark --help
+```
+
+## Setup
+
+Set your xmark API key (get one at [/settings/api](https://www.xmark.chat/settings/api)):
+
+```bash
+export XMARK_API_KEY=xm_live_...
+```
+
+Optionally override the API host (default is `https://api.xmark.chat`):
+
+```bash
+export XMARK_API_URL=https://api.xmark.chat
+```
+
+## Tools exposed via MCP
+
+| Tool | What it does |
+|---|---|
+| `search_bookmarks` | Semantic search over the user's bookmarks. |
+| `chat` | Ask a natural-language question with citations. |
+| `sync_bookmarks` | Pull the latest bookmarks from X. |
+| `list_bookmarks` | Paginated bookmark list. |
+| `get_bookmark` | Fetch a single bookmark by ID. |
+| `list_conversations` | Past chat conversations. |
+
+## CLI commands
+
+```bash
+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 conversations
+```
+
+## Pricing
+
+xmark is $5/month flat. The same subscription covers the web app, CLI, MCP server, and developer REST API — no separate API tier.
+
+## Links
+
+- Homepage: https://www.xmark.chat
+- API reference: https://www.xmark.chat/docs
+- OpenAPI spec: https://api.xmark.chat/openapi.json
+- llms.txt: https://api.xmark.chat/llms.txt
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { XmarkClient } from "./client.js";
+const program = new Command();
+program
+    .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) 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),
+    });
+    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);
+});

package/dist/client.d.ts

@@ -0,0 +1,10 @@
+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>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    delete(path: string): Promise<void>;
+    private request;
+    private handleError;
+}

package/dist/client.js

@@ -0,0 +1,73 @@
+const REQUEST_TIMEOUT_MS = 30_000;
+const DEFAULT_BASE_URL = "https://api.xmark.chat";
+export class XmarkClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl) {
+        const key = apiKey ?? process.env.XMARK_API_KEY;
+        if (!key) {
+            throw new Error("XMARK_API_KEY environment variable is required. Get one at https://www.xmark.chat/settings/api");
+        }
+        this.apiKey = key;
+        this.baseUrl = (baseUrl ?? process.env.XMARK_API_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    }
+    async get(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));
+            }
+        }
+        return this.request(url.toString(), { method: "GET" });
+    }
+    async post(path, body) {
+        return this.request(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    async delete(path) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${this.apiKey}` },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        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),
+        });
+        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 json.data;
+    }
+    async handleError(response) {
+        let detail = "";
+        try {
+            const body = (await response.json());
+            if (body?.error) {
+                detail = `${body.error.code}: ${body.error.message}`;
+            }
+        }
+        catch {
+            detail = await response.text().catch(() => "");
+        }
+        throw new Error(`xmark API ${response.status} ${response.statusText}${detail ? ` — ${detail}` : ""}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+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";
+const server = new McpServer({
+    name: "xmark",
+    version: "0.1.0",
+});
+const client = new XmarkClient();
+registerBookmarkTools(server, client);
+registerChatTools(server, client);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/bookmarks.d.ts

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

package/dist/tools/bookmarks.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+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),
+                },
+            ],
+        };
+    });
+    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) }],
+        };
+    });
+    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).", {
+        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) }],
+        };
+    });
+    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) in ${result.durationMs}ms.`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/chat.d.ts

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

package/dist/tools/chat.js

@@ -0,0 +1,44 @@
+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.", {
+        question: z.string().min(1).describe("The question to ask"),
+        conversationId: z
+            .string()
+            .uuid()
+            .optional()
+            .describe("Continue an existing conversation by ID"),
+        maxCitations: z
+            .number()
+            .int()
+            .min(1)
+            .max(20)
+            .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}`,
+                },
+            ],
+        };
+    });
+    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) }],
+        };
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+export interface ApiSuccessResponse<T> {
+    success: true;
+    data: T;
+}
+export interface ApiErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        requestId?: string;
+        field?: string;
+        details?: unknown;
+    };
+}
+export type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
+export interface Bookmark {
+    id: string;
+    tweet_id: string;
+    text: string;
+    author: {
+        username: string;
+        name: string;
+        id: string;
+    };
+    bookmarked_at: string;
+    url?: string;
+    media?: unknown[];
+    topics?: string[];
+}
+export interface BookmarkSearchResult {
+    bookmark: Bookmark;
+    score: number;
+}
+export interface ChatCitation {
+    bookmark_id: string;
+    tweet_url: string;
+    author: string;
+    snippet: string;
+}
+export interface ChatResult {
+    answer: string;
+    citations: ChatCitation[];
+    conversation_id: string;
+}
+export interface SyncResult {
+    count: number;
+    newCount: number;
+    durationMs: number;
+}
+export interface Conversation {
+    id: string;
+    title: string;
+    created_at: string;
+    message_count: number;
+}
+export interface PaginationMeta {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@jclvsh/xmark",
+	"version": "0.1.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",
+	"types": "dist/index.d.ts",
+	"bin": {
+		"xmark-mcp": "dist/index.js",
+		"xmark": "dist/cli.js"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc",
+		"prepublishOnly": "npm run build",
+		"start": "node dist/index.js"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"twitter",
+		"x",
+		"bookmarks",
+		"ai",
+		"claude",
+		"semantic-search",
+		"xmark"
+	],
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.11.0",
+		"commander": "^14.0.3",
+		"zod": "^3.24.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"typescript": "^5.7.0"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jclvsh/xmark.git"
+	},
+	"homepage": "https://www.xmark.chat"
+}