@jclvsh/xmark 0.4.0 → 0.6.0

package/README.md

@@ -16,6 +16,8 @@ npx -y -p @jclvsh/xmark xmark-mcp
 npx -y -p @jclvsh/xmark xmark --help
 ```
 
+Imported as a library, the package resolves only through its `exports` map (`.`, `./hosted`, `./tool-policy`, `./policy`, `./package.json`); deep imports of `dist/*` are not supported.
+
 ## Setup
 
 Set your xmark API key (get one at [/settings/api](https://xmark.dev/settings/api)):
@@ -32,18 +34,18 @@ export XMARK_API_URL=https://api.xmark.dev
 
 ## 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. |
-| `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). |
+| 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.                                     |
+| `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
 

package/dist/client.d.ts

@@ -2,6 +2,8 @@ import type { Paginated } from "./types.js";
 export declare class XmarkClient {
     private apiKey;
     private baseUrl;
+    /** True when the base URL was injected; the network-error hint then names no URL or env var. */
+    private hasInjectedBaseUrl;
     constructor(apiKey?: string, baseUrl?: string);
     get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
     /**
@@ -12,8 +14,15 @@ export declare class XmarkClient {
     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;
+    /** Read the `{ success, data }` envelope, throwing the api's error when `success` is false. */
+    private unwrap;
+    /** Read a JSON body; a timeout while the body streams gets the same message as one during fetch. */
+    private readJson;
+    /**
+     * fetch with auth + UA + timeout, translating timeouts and network failures to readable
+     * errors and a non-2xx response to the api's error.
+     */
+    private send;
     /**
      * Build the fleet-standard `[CODE] message (field: x)` error, the format
      * cli-utils' exitCodeForMessage / parseErrorMessage recover structurally.

package/dist/client.js

@@ -1,16 +1,22 @@
+import { createRequire } from "node:module";
 const REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_BASE_URL = "https://api.xmark.dev";
-const USER_AGENT = "xmark-mcp/0.4.0";
+// Read from package.json (as index.ts does) so the user agent always carries the released version.
+const { version } = createRequire(import.meta.url)("../package.json");
+const USER_AGENT = `xmark-mcp/${version}`;
 export class XmarkClient {
     apiKey;
     baseUrl;
+    /** True when the base URL was injected; the network-error hint then names no URL or env var. */
+    hasInjectedBaseUrl;
     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://xmark.dev/settings/api");
         }
         this.apiKey = key;
-        this.baseUrl = (baseUrl ?? process.env.XMARK_API_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.hasInjectedBaseUrl = Boolean(baseUrl);
+        this.baseUrl = (baseUrl || process.env.XMARK_API_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
     }
     async get(path, params) {
         const url = new URL(`${this.baseUrl}${path}`);
@@ -34,11 +40,8 @@ export class XmarkClient {
                     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());
+        const response = await this.send(url.toString(), { method: "GET" });
+        const json = await this.readJson(response);
         if (!json.success) {
             throw this.apiError(json.error);
         }
@@ -52,26 +55,39 @@ export class XmarkClient {
         });
     }
     async delete(path) {
-        const response = await this.fetchWithGuards(`${this.baseUrl}${path}`, { method: "DELETE" });
-        if (!response.ok && response.status !== 204) {
-            await this.handleError(response);
-        }
+        await this.send(`${this.baseUrl}${path}`, { method: "DELETE" });
     }
     async request(url, init) {
-        const response = await this.fetchWithGuards(url, init);
-        if (!response.ok) {
-            await this.handleError(response);
-        }
-        const json = (await response.json());
+        return this.unwrap(await this.send(url, init));
+    }
+    /** Read the `{ success, data }` envelope, throwing the api's error when `success` is false. */
+    async unwrap(response) {
+        const json = await this.readJson(response);
         if (!json.success) {
             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) {
+    /** Read a JSON body; a timeout while the body streams gets the same message as one during fetch. */
+    async readJson(response) {
         try {
-            return await fetch(url, {
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError") {
+                throw new Error("request timed out after 30s");
+            }
+            throw error;
+        }
+    }
+    /**
+     * fetch with auth + UA + timeout, translating timeouts and network failures to readable
+     * errors and a non-2xx response to the api's error.
+     */
+    async send(url, init) {
+        let response;
+        try {
+            response = await fetch(url, {
                 ...init,
                 headers: {
                     ...(init.headers || {}),
@@ -86,10 +102,16 @@ export class XmarkClient {
                 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 new Error(this.hasInjectedBaseUrl
+                    ? `network error reaching the api: ${error.message}`
+                    : `network error: ${error.message}. check XMARK_API_URL and your connection`);
             }
             throw error;
         }
+        if (!response.ok) {
+            await this.handleError(response);
+        }
+        return response;
     }
     /**
      * Build the fleet-standard `[CODE] message (field: x)` error, the format

package/dist/hosted-transport.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Serve one MCP request over HTTP. LOCKSTEP across every apps/<app>/packages/mcp.
+ *
+ * Stateless: a fresh transport per request, no sessions, JSON responses - so it runs on
+ * serverless functions where consecutive requests from one client can land on different
+ * instances. Only POST is meaningful; the host must not route GET here (a stateless GET
+ * opens an event stream that never ends).
+ */
+export declare function serveStatelessMcp(server: McpServer, request: Request): Promise<Response>;

package/dist/hosted-transport.js

@@ -0,0 +1,17 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+/**
+ * Serve one MCP request over HTTP. LOCKSTEP across every apps/<app>/packages/mcp.
+ *
+ * Stateless: a fresh transport per request, no sessions, JSON responses - so it runs on
+ * serverless functions where consecutive requests from one client can land on different
+ * instances. Only POST is meaningful; the host must not route GET here (a stateless GET
+ * opens an event stream that never ends).
+ */
+export async function serveStatelessMcp(server, request) {
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    await server.connect(transport);
+    return transport.handleRequest(request);
+}

package/dist/hosted.d.ts

@@ -0,0 +1,10 @@
+export interface HostedMcpOptions {
+    /** The caller's xmark API key. The host authenticates it before calling in. */
+    apiKey: string;
+    /** REST base URL the tools call, e.g. https://api.xmark.dev */
+    baseUrl: string;
+    /** Reported as serverInfo.version */
+    version: string;
+}
+/** One hosted MCP request: a per-request client and server over the stateless transport. */
+export declare function handleHostedMcpRequest(request: Request, options: HostedMcpOptions): Promise<Response>;

package/dist/hosted.js

@@ -0,0 +1,9 @@
+import { XmarkClient } from "./client.js";
+import { serveStatelessMcp } from "./hosted-transport.js";
+import { createXmarkServer } from "./server.js";
+/** One hosted MCP request: a per-request client and server over the stateless transport. */
+export function handleHostedMcpRequest(request, options) {
+    const client = new XmarkClient(options.apiKey, options.baseUrl);
+    const server = createXmarkServer({ client, version: options.version, profile: "hosted" });
+    return serveStatelessMcp(server, request);
+}

package/dist/idempotency.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A content-derived Idempotency-Key for create calls.
+ *
+ * The REST API dedupes a request that repeats a key within 24 hours (per key + endpoint)
+ * and answers with the original response plus `Idempotent-Replayed: true`. Deriving the
+ * key from the arguments means a retry after a timeout - by an agent, or by a person
+ * pressing "try again" in an MCP client - returns the record that was already created
+ * instead of creating a second one.
+ */
+export declare function contentIdempotencyKey(args: unknown): Promise<string>;

package/dist/idempotency.js

@@ -0,0 +1,28 @@
+/**
+ * A content-derived Idempotency-Key for create calls.
+ *
+ * The REST API dedupes a request that repeats a key within 24 hours (per key + endpoint)
+ * and answers with the original response plus `Idempotent-Replayed: true`. Deriving the
+ * key from the arguments means a retry after a timeout - by an agent, or by a person
+ * pressing "try again" in an MCP client - returns the record that was already created
+ * instead of creating a second one.
+ */
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value !== null && typeof value === "object") {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort()) {
+            if (source[key] !== undefined)
+                sorted[key] = stable(source[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+export async function contentIdempotencyKey(args) {
+    const bytes = new TextEncoder().encode(JSON.stringify(stable(args)));
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/index.js

@@ -1,17 +1,10 @@
 #!/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";
+import { createXmarkServer } from "./server.js";
 const requireFromHere = createRequire(import.meta.url);
 const pkg = requireFromHere("../package.json");
-const server = new McpServer({
-    name: "xmark",
-    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
@@ -26,8 +19,6 @@ const client = new Proxy({}, {
         return typeof value === "function" ? value.bind(realClient) : value;
     },
 });
-registerBookmarkTools(server, client);
-registerChatTools(server, client);
-registerUsageTools(server, client);
+const server = createXmarkServer({ client, version: pkg.version, profile: "full" });
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/policy.d.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Generic tool-policy machinery. LOCKSTEP across every apps/<app>/packages/mcp
+ * (byte-identical; scripts/check-lockstep-identity.sh enforces it). The per-app
+ * table lives in tool-policy.ts next to this file.
+ *
+ * class:
+ *   read      - retrieves information; changes nothing.
+ *   write     - changes the app's own data, reversibly; nothing leaves the app.
+ *   sensitive - publishes, sends, or deletes on an external platform, deletes a record
+ *               with no user-facing restore, spends money, handles credentials, or
+ *               switches on automatic sending or posting.
+ * hosted: whether the app's hosted endpoint (api.<brand>/mcp) serves the tool.
+ * category: the documentation grouping every docs count is computed from.
+ */
+export type ToolClass = "read" | "write" | "sensitive";
+export type ToolProfile = "full" | "hosted";
+export interface ToolPolicy<Category extends string = string> {
+    class: ToolClass;
+    hosted: boolean;
+    category: Category;
+}
+export type PolicyTable<Category extends string = string> = Record<string, ToolPolicy<Category>>;
+export declare function toolPolicyFor<C extends string>(table: PolicyTable<C>, name: string): ToolPolicy<C>;
+export declare function isToolEnabledIn<C extends string>(table: PolicyTable<C>, name: string, profile: ToolProfile): boolean;
+export declare function toolAnnotationsFor<C extends string>(table: PolicyTable<C>, name: string): {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+};
+/** Tool names in a category, in table order. */
+export declare function toolsInCategoryOf<C extends string>(table: PolicyTable<C>, category: C): string[];
+/**
+ * A stand-in for McpServer that every register*Tools(server, client) function can be
+ * handed. It is the one place a tool is filtered by profile and given its annotations.
+ */
+export declare function createPolicyRegistrar<C extends string>(server: McpServer, table: PolicyTable<C>, profile: ToolProfile): McpServer;

package/dist/policy.js

@@ -0,0 +1,33 @@
+export function toolPolicyFor(table, name) {
+    const policy = table[name];
+    if (!policy) {
+        throw new Error(`tool "${name}" has no entry in tool-policy.ts - classify it before registering`);
+    }
+    return policy;
+}
+export function isToolEnabledIn(table, name, profile) {
+    const { hosted } = toolPolicyFor(table, name);
+    return profile === "full" || hosted;
+}
+export function toolAnnotationsFor(table, name) {
+    const toolClass = toolPolicyFor(table, name).class;
+    return { readOnlyHint: toolClass === "read", destructiveHint: toolClass === "sensitive" };
+}
+/** Tool names in a category, in table order. */
+export function toolsInCategoryOf(table, category) {
+    return Object.keys(table).filter((name) => table[name].category === category);
+}
+/**
+ * A stand-in for McpServer that every register*Tools(server, client) function can be
+ * handed. It is the one place a tool is filtered by profile and given its annotations.
+ */
+export function createPolicyRegistrar(server, table, profile) {
+    const registerAnnotated = server.tool.bind(server);
+    return {
+        tool(name, description, schema, handler) {
+            if (!isToolEnabledIn(table, name, profile))
+                return;
+            registerAnnotated(name, description, schema, toolAnnotationsFor(table, name), handler);
+        },
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { XmarkClient } from "./client.js";
+import { type ToolProfile } from "./policy.js";
+export interface CreateXmarkServerOptions {
+    client: XmarkClient;
+    version: string;
+    /** "full" serves every tool (stdio). "hosted" serves the tools marked hosted in tool-policy.ts. */
+    profile: ToolProfile;
+}
+export declare function createXmarkServer({ client, version, profile }: CreateXmarkServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createPolicyRegistrar } from "./policy.js";
+import { TOOL_POLICY } from "./tool-policy.js";
+import { registerBookmarkTools } from "./tools/bookmarks.js";
+import { registerChatTools } from "./tools/chat.js";
+import { registerUsageTools } from "./tools/usage.js";
+export function createXmarkServer({ client, version, profile }) {
+    const server = new McpServer({ name: "xmark", version });
+    const registrar = createPolicyRegistrar(server, TOOL_POLICY, profile);
+    registerBookmarkTools(registrar, client);
+    registerChatTools(registrar, client);
+    registerUsageTools(registrar, client);
+    return server;
+}

package/dist/tool-policy.d.ts

@@ -0,0 +1,12 @@
+import { type PolicyTable, type ToolClass, type ToolPolicy, type ToolProfile } from "./policy.js";
+export type { ToolClass, ToolPolicy, ToolProfile };
+export declare const TOOL_CATEGORIES: readonly ["bookmarks", "chat", "usage"];
+export type ToolCategory = (typeof TOOL_CATEGORIES)[number];
+export declare const TOOL_POLICY: PolicyTable<ToolCategory>;
+export declare const toolPolicy: (name: string) => ToolPolicy<"usage" | "bookmarks" | "chat">;
+export declare const isToolEnabled: (name: string, profile: ToolProfile) => boolean;
+export declare const toolAnnotations: (name: string) => {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+};
+export declare const toolsInCategory: (category: ToolCategory) => string[];

package/dist/tool-policy.js

@@ -0,0 +1,29 @@
+import { isToolEnabledIn, toolAnnotationsFor, toolPolicyFor, toolsInCategoryOf, } from "./policy.js";
+export const TOOL_CATEGORIES = ["bookmarks", "chat", "usage"];
+const hosted = (category, toolClass) => ({
+    class: toolClass,
+    hosted: true,
+    category,
+});
+export const TOOL_POLICY = {
+    // bookmarks
+    list_bookmarks: hosted("bookmarks", "read"),
+    get_bookmark: hosted("bookmarks", "read"),
+    search_bookmarks: hosted("bookmarks", "read"),
+    sync_bookmarks: hosted("bookmarks", "write"),
+    // unbookmark=true removes the bookmark on X
+    delete_bookmark: hosted("bookmarks", "sensitive"),
+    // chat
+    chat: hosted("chat", "write"),
+    list_conversations: hosted("chat", "read"),
+    get_conversation_messages: hosted("chat", "read"),
+    // permanent delete
+    delete_conversation: hosted("chat", "sensitive"),
+    // usage
+    get_usage: hosted("usage", "read"),
+    get_changelog: hosted("usage", "read"),
+};
+export const toolPolicy = (name) => toolPolicyFor(TOOL_POLICY, name);
+export const isToolEnabled = (name, profile) => isToolEnabledIn(TOOL_POLICY, name, profile);
+export const toolAnnotations = (name) => toolAnnotationsFor(TOOL_POLICY, name);
+export const toolsInCategory = (category) => toolsInCategoryOf(TOOL_POLICY, category);

package/dist/tools/bookmarks.js

@@ -73,7 +73,9 @@ export function registerBookmarkTools(server, client) {
                 content: [
                     {
                         type: "text",
-                        text: unbookmark ? "Bookmark removed from xmark and X." : "Bookmark removed from xmark (local only).",
+                        text: unbookmark
+                            ? "Bookmark removed from xmark and X."
+                            : "Bookmark removed from xmark (local only).",
                     },
                 ],
             };

package/dist/tools/chat.js

@@ -3,11 +3,7 @@ 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. Free tier includes 20 chat messages per month.", {
         question: z.string().min(1).describe("The question to ask"),
-        conversationId: z
-            .string()
-            .uuid()
-            .optional()
-            .describe("Continue an existing conversation by ID"),
+        conversationId: z.string().uuid().optional().describe("Continue an existing conversation by ID"),
         maxCitations: z
             .number()
             .int()

package/dist/tools/usage.js

@@ -11,4 +11,13 @@ export function registerUsageTools(server, client) {
             return formatMcpError(error);
         }
     });
+    server.tool("get_changelog", "machine-readable release history (public) - version, date, type, summary, migration notes on breaking entries. the X-Notice header's structured backstory.", {}, async () => {
+        try {
+            const result = await client.get("/changelog");
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
 }

package/package.json

@@ -1,10 +1,29 @@
 {
 	"name": "@jclvsh/xmark",
-	"version": "0.4.0",
+	"version": "0.6.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",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./hosted": {
+			"types": "./dist/hosted.d.ts",
+			"default": "./dist/hosted.js"
+		},
+		"./policy": {
+			"types": "./dist/policy.d.ts",
+			"default": "./dist/policy.js"
+		},
+		"./tool-policy": {
+			"types": "./dist/tool-policy.d.ts",
+			"default": "./dist/tool-policy.js"
+		},
+		"./package.json": "./package.json"
+	},
 	"bin": {
 		"xmark-mcp": "dist/index.js",
 		"xmark": "dist/cli.js"
@@ -15,8 +34,11 @@
 	],
 	"scripts": {
 		"build": "tsc",
+		"prepare": "tsc",
 		"prepublishOnly": "npm run build",
-		"start": "node dist/index.js"
+		"start": "node dist/index.js",
+		"typecheck": "tsc -p tsconfig.test.json",
+		"test": "vitest run"
 	},
 	"keywords": [
 		"mcp",
@@ -30,13 +52,14 @@
 		"xmark"
 	],
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.11.0",
+		"@modelcontextprotocol/sdk": "^1.26.0",
 		"commander": "^14.0.3",
 		"zod": "^3.24.0"
 	},
 	"devDependencies": {
 		"@types/node": "^22.0.0",
-		"typescript": "^5.7.0"
+		"typescript": "^5.7.0",
+		"vitest": "^4.0.18"
 	},
 	"engines": {
 		"node": ">=18"