@ulinkly/mcp-server 0.1.12 → 0.1.13

package/dist/auth/token-store.d.ts

@@ -5,6 +5,12 @@ import type { OAuthTokens } from "./oauth.js";
  * Returns undefined if file missing, auth missing, or expired.
  */
 export declare function loadTokensFromDisk(): OAuthTokens | undefined;
+/**
+ * Load just the refresh token from ~/.ulink/config.json, ignoring access token expiry.
+ * Used by check_auth_status to attempt token refresh when access token is expired.
+ * Returns undefined if no config, no auth, or no refresh token found.
+ */
+export declare function loadRefreshTokenFromDisk(): string | undefined;
 /**
  * Persist OAuthTokens to ~/.ulink/config.json using encrypted storage.
  * Preserves projects, supabaseUrl, supabaseAnonKey and all other fields.

package/dist/auth/token-store.js

@@ -88,6 +88,37 @@ export function loadTokensFromDisk() {
         return undefined;
     }
 }
+/**
+ * Load just the refresh token from ~/.ulink/config.json, ignoring access token expiry.
+ * Used by check_auth_status to attempt token refresh when access token is expired.
+ * Returns undefined if no config, no auth, or no refresh token found.
+ */
+export function loadRefreshTokenFromDisk() {
+    try {
+        const raw = readFileSync(CONFIG_PATH, "utf-8");
+        const config = JSON.parse(raw);
+        // Try encrypted format first
+        if (typeof config.auth_encrypted === "string") {
+            try {
+                const decrypted = decrypt(config.auth_encrypted);
+                const auth = JSON.parse(decrypted);
+                return auth.refreshToken || undefined;
+            }
+            catch {
+                // Decryption failed — fall through to legacy
+            }
+        }
+        // Legacy plaintext format
+        const auth = config.auth;
+        if (auth?.refreshToken) {
+            return auth.refreshToken;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Persist OAuthTokens to ~/.ulink/config.json using encrypted storage.
  * Preserves projects, supabaseUrl, supabaseAnonKey and all other fields.

package/dist/client/ulink-api.js

@@ -81,6 +81,7 @@ export async function apiRequest(method, path, body) {
     const auth = await ensureAuth();
     const headers = {
         [auth.header]: auth.value,
+        "X-ULink-Source": "mcp_server",
     };
     if (body !== undefined) {
         headers["Content-Type"] = "application/json";

package/dist/index.js

@@ -9,12 +9,14 @@ import { registerLinkTools } from "./tools/links.js";
 import { registerDomainTools } from "./tools/domains.js";
 import { registerApiKeyTools } from "./tools/api-keys.js";
 import { registerAccountTools } from "./tools/account.js";
+import { registerAuthTools } from "./tools/auth.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageJson = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 const server = new McpServer({
     name: "ulink",
     version: String(packageJson.version),
 });
+registerAuthTools(server);
 registerProjectTools(server);
 registerLinkTools(server);
 registerDomainTools(server);
@@ -23,7 +25,7 @@ registerAccountTools(server);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("ULink MCP Server running on stdio (21 tools registered)");
+    console.error("ULink MCP Server running on stdio (24 tools registered)");
 }
 main().catch((error) => {
     console.error("Fatal error:", error);

package/dist/tools/__tests__/auth.test.d.ts

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

package/dist/tools/__tests__/auth.test.js

@@ -0,0 +1,245 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createMockServer } from "./_helpers.js";
+vi.mock("../../auth/api-key.js", () => ({
+    getApiKey: vi.fn(),
+}));
+vi.mock("../../auth/oauth.js", () => ({
+    browserOAuthFlow: vi.fn(),
+    refreshAccessToken: vi.fn(),
+}));
+vi.mock("../../auth/token-store.js", () => ({
+    loadTokensFromDisk: vi.fn(),
+    loadRefreshTokenFromDisk: vi.fn(),
+    saveTokensToDisk: vi.fn(),
+}));
+vi.mock("../../client/ulink-api.js", () => ({
+    apiRequest: vi.fn(),
+}));
+import { getApiKey } from "../../auth/api-key.js";
+import { browserOAuthFlow, refreshAccessToken } from "../../auth/oauth.js";
+import { loadTokensFromDisk, loadRefreshTokenFromDisk, saveTokensToDisk, } from "../../auth/token-store.js";
+import { apiRequest } from "../../client/ulink-api.js";
+import { registerAuthTools } from "../auth.js";
+const mockedGetApiKey = vi.mocked(getApiKey);
+const mockedBrowserOAuthFlow = vi.mocked(browserOAuthFlow);
+const mockedRefreshAccessToken = vi.mocked(refreshAccessToken);
+const mockedLoadTokensFromDisk = vi.mocked(loadTokensFromDisk);
+const mockedLoadRefreshTokenFromDisk = vi.mocked(loadRefreshTokenFromDisk);
+const mockedSaveTokensToDisk = vi.mocked(saveTokensToDisk);
+const mockedApiRequest = vi.mocked(apiRequest);
+describe("Auth tools", () => {
+    let getHandler;
+    beforeEach(() => {
+        vi.resetAllMocks();
+        const mock = createMockServer();
+        getHandler = mock.getHandler;
+        registerAuthTools(mock.server);
+    });
+    // ---------------------------------------------------------------------------
+    // check_auth_status
+    // ---------------------------------------------------------------------------
+    describe("check_auth_status", () => {
+        it("returns api_key method when ULINK_API_KEY is set", async () => {
+            mockedGetApiKey.mockReturnValue("test-api-key-123");
+            const handler = getHandler("check_auth_status");
+            const result = await handler({});
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.authenticated).toBe(true);
+            expect(parsed.method).toBe("api_key");
+        });
+        it("returns authenticated when valid tokens on disk", async () => {
+            mockedGetApiKey.mockReturnValue(undefined);
+            mockedLoadTokensFromDisk.mockReturnValue({
+                accessToken: "access-tok",
+                refreshToken: "refresh-tok",
+                expiresAt: Date.now() + 3600_000,
+            });
+            const handler = getHandler("check_auth_status");
+            const result = await handler({});
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.authenticated).toBe(true);
+            expect(parsed.method).toBe("oauth");
+            expect(parsed.expiresAt).toBeDefined();
+        });
+        it("attempts refresh when tokens expired but refresh token available", async () => {
+            mockedGetApiKey.mockReturnValue(undefined);
+            mockedLoadTokensFromDisk.mockReturnValue(undefined);
+            mockedLoadRefreshTokenFromDisk.mockReturnValue("old-refresh-tok");
+            const newTokens = {
+                accessToken: "new-access",
+                refreshToken: "new-refresh",
+                expiresAt: Date.now() + 3600_000,
+            };
+            mockedRefreshAccessToken.mockResolvedValue(newTokens);
+            const handler = getHandler("check_auth_status");
+            const result = await handler({});
+            expect(mockedRefreshAccessToken).toHaveBeenCalledWith("old-refresh-tok");
+            expect(mockedSaveTokensToDisk).toHaveBeenCalledWith(newTokens);
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.authenticated).toBe(true);
+            expect(parsed.method).toBe("oauth");
+        });
+        it("returns unauthenticated when no tokens and refresh fails", async () => {
+            mockedGetApiKey.mockReturnValue(undefined);
+            mockedLoadTokensFromDisk.mockReturnValue(undefined);
+            mockedLoadRefreshTokenFromDisk.mockReturnValue("stale-refresh");
+            mockedRefreshAccessToken.mockRejectedValue(new Error("Token refresh failed (401)"));
+            const handler = getHandler("check_auth_status");
+            const result = await handler({});
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.authenticated).toBe(false);
+            expect(parsed.message).toContain("Not authenticated");
+        });
+        it("returns unauthenticated when no tokens and no refresh token", async () => {
+            mockedGetApiKey.mockReturnValue(undefined);
+            mockedLoadTokensFromDisk.mockReturnValue(undefined);
+            mockedLoadRefreshTokenFromDisk.mockReturnValue(undefined);
+            const handler = getHandler("check_auth_status");
+            const result = await handler({});
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.authenticated).toBe(false);
+            expect(parsed.message).toContain("Not authenticated");
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // authenticate
+    // ---------------------------------------------------------------------------
+    describe("authenticate", () => {
+        it("returns already authenticated when API key set", async () => {
+            mockedGetApiKey.mockReturnValue("test-api-key");
+            const handler = getHandler("authenticate");
+            const result = await handler({});
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.authenticated).toBe(true);
+            expect(parsed.message).toContain("Already authenticated via API key");
+        });
+        it("returns already authenticated when valid tokens exist", async () => {
+            mockedGetApiKey.mockReturnValue(undefined);
+            mockedLoadTokensFromDisk.mockReturnValue({
+                accessToken: "access-tok",
+                refreshToken: "refresh-tok",
+                expiresAt: Date.now() + 3600_000,
+            });
+            const handler = getHandler("authenticate");
+            const result = await handler({});
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.authenticated).toBe(true);
+            expect(parsed.message).toContain("Already authenticated");
+        });
+        it("triggers browserOAuthFlow and saves tokens when no auth exists", async () => {
+            mockedGetApiKey.mockReturnValue(undefined);
+            mockedLoadTokensFromDisk.mockReturnValue(undefined);
+            const tokens = {
+                accessToken: "new-access",
+                refreshToken: "new-refresh",
+                expiresAt: Date.now() + 3600_000,
+            };
+            mockedBrowserOAuthFlow.mockResolvedValue(tokens);
+            const handler = getHandler("authenticate");
+            const result = await handler({});
+            expect(mockedBrowserOAuthFlow).toHaveBeenCalled();
+            expect(mockedSaveTokensToDisk).toHaveBeenCalledWith(tokens);
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.authenticated).toBe(true);
+            expect(parsed.message).toContain("Successfully authenticated");
+        });
+        it("returns error when OAuth times out", async () => {
+            mockedGetApiKey.mockReturnValue(undefined);
+            mockedLoadTokensFromDisk.mockReturnValue(undefined);
+            mockedBrowserOAuthFlow.mockRejectedValue(new Error("OAuth flow timed out after 5 minutes"));
+            const handler = getHandler("authenticate");
+            const result = await handler({});
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("timed out");
+        });
+        it("returns error when OAuth fails", async () => {
+            mockedGetApiKey.mockReturnValue(undefined);
+            mockedLoadTokensFromDisk.mockReturnValue(undefined);
+            mockedBrowserOAuthFlow.mockRejectedValue(new Error("OAuth error: access_denied"));
+            const handler = getHandler("authenticate");
+            const result = await handler({});
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("Authentication failed");
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // get_onboarding_status
+    // ---------------------------------------------------------------------------
+    describe("get_onboarding_status", () => {
+        it("returns error when not authenticated", async () => {
+            mockedGetApiKey.mockReturnValue(undefined);
+            mockedLoadTokensFromDisk.mockReturnValue(undefined);
+            const handler = getHandler("get_onboarding_status");
+            const result = await handler({ projectId: "proj-1" });
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("Not authenticated");
+        });
+        it("calls correct API endpoint with projectId", async () => {
+            mockedGetApiKey.mockReturnValue("test-key");
+            mockedApiRequest.mockResolvedValue({
+                domain_setup_completed: false,
+                platform_selection_completed: false,
+                platform_config_completed: false,
+                platform_implementation_viewed: false,
+                cli_verified: false,
+                sdk_setup_viewed: false,
+            });
+            const handler = getHandler("get_onboarding_status");
+            await handler({ projectId: "proj-1" });
+            expect(mockedApiRequest).toHaveBeenCalledWith("GET", "/projects/proj-1/onboarding");
+        });
+        it("computes nextStep as domain_setup when nothing done", async () => {
+            mockedGetApiKey.mockReturnValue("test-key");
+            mockedApiRequest.mockResolvedValue({
+                domain_setup_completed: false,
+                platform_selection_completed: false,
+                platform_config_completed: false,
+                platform_implementation_viewed: false,
+                cli_verified: false,
+                sdk_setup_viewed: false,
+            });
+            const handler = getHandler("get_onboarding_status");
+            const result = await handler({ projectId: "proj-1" });
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.nextStep).toBe("domain_setup");
+            expect(parsed.completedSteps).toBe(0);
+            expect(parsed.completionPercentage).toBe(0);
+        });
+        it("computes nextStep as platform_config when first 2 steps done", async () => {
+            mockedGetApiKey.mockReturnValue("test-key");
+            mockedApiRequest.mockResolvedValue({
+                domain_setup_completed: true,
+                platform_selection_completed: true,
+                platform_config_completed: false,
+                platform_implementation_viewed: false,
+                cli_verified: false,
+                sdk_setup_viewed: false,
+            });
+            const handler = getHandler("get_onboarding_status");
+            const result = await handler({ projectId: "proj-1" });
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.nextStep).toBe("platform_config");
+            expect(parsed.completedSteps).toBe(2);
+            expect(parsed.completionPercentage).toBe(33);
+        });
+        it("returns complete with 100% when all steps done", async () => {
+            mockedGetApiKey.mockReturnValue("test-key");
+            mockedApiRequest.mockResolvedValue({
+                domain_setup_completed: true,
+                platform_selection_completed: true,
+                platform_config_completed: true,
+                platform_implementation_viewed: true,
+                cli_verified: true,
+                sdk_setup_viewed: true,
+            });
+            const handler = getHandler("get_onboarding_status");
+            const result = await handler({ projectId: "proj-1" });
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.nextStep).toBe("complete");
+            expect(parsed.completedSteps).toBe(6);
+            expect(parsed.totalSteps).toBe(6);
+            expect(parsed.completionPercentage).toBe(100);
+        });
+    });
+});
+//# sourceMappingURL=auth.test.js.map

package/dist/tools/auth.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAuthTools(server: McpServer): void;

package/dist/tools/auth.js

@@ -0,0 +1,219 @@
+import { z } from "zod";
+import { getApiKey } from "../auth/api-key.js";
+import { browserOAuthFlow, refreshAccessToken, } from "../auth/oauth.js";
+import { loadTokensFromDisk, loadRefreshTokenFromDisk, saveTokensToDisk, } from "../auth/token-store.js";
+import { apiRequest } from "../client/ulink-api.js";
+export function registerAuthTools(server) {
+    // -----------------------------------------------------------------------
+    // check_auth_status
+    // -----------------------------------------------------------------------
+    server.registerTool("check_auth_status", {
+        title: "Check Auth Status",
+        description: "Check whether valid ULink authentication credentials exist. Returns authentication state without triggering any login flow. Call this first to determine if the authenticate tool needs to be called.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {},
+    }, async () => {
+        try {
+            // 1. Check API key
+            const apiKey = getApiKey();
+            if (apiKey) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ authenticated: true, method: "api_key" }),
+                        }],
+                };
+            }
+            // 2. Check disk tokens
+            const tokens = loadTokensFromDisk();
+            if (tokens) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                authenticated: true,
+                                method: "oauth",
+                                expiresAt: tokens.expiresAt,
+                            }),
+                        }],
+                };
+            }
+            // 3. Attempt refresh with expired token's refresh token
+            const refreshToken = loadRefreshTokenFromDisk();
+            if (refreshToken) {
+                try {
+                    const newTokens = await refreshAccessToken(refreshToken);
+                    saveTokensToDisk(newTokens);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    authenticated: true,
+                                    method: "oauth",
+                                    expiresAt: newTokens.expiresAt,
+                                }),
+                            }],
+                    };
+                }
+                catch {
+                    // Refresh failed — fall through to unauthenticated
+                }
+            }
+            // 4. Not authenticated
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            authenticated: false,
+                            message: "Not authenticated. Call the 'authenticate' tool to sign in or create a free ULink account.",
+                        }),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error checking auth status: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // authenticate
+    // -----------------------------------------------------------------------
+    server.registerTool("authenticate", {
+        title: "Authenticate",
+        description: "Authenticate with ULink by opening a browser window for sign-in or sign-up. No existing account required — new users can create a free account during this flow. This is the first tool to call if check_auth_status reports no valid credentials. After success, all other ULink tools become usable.",
+        annotations: { readOnlyHint: false },
+        inputSchema: {},
+    }, async () => {
+        try {
+            // 1. Check API key
+            const apiKey = getApiKey();
+            if (apiKey) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                authenticated: true,
+                                message: "Already authenticated via API key.",
+                            }),
+                        }],
+                };
+            }
+            // 2. Check existing tokens
+            const existing = loadTokensFromDisk();
+            if (existing) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                authenticated: true,
+                                message: "Already authenticated with ULink. All tools are ready to use.",
+                            }),
+                        }],
+                };
+            }
+            // 3. Run browser OAuth flow
+            const tokens = await browserOAuthFlow();
+            saveTokensToDisk(tokens);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            authenticated: true,
+                            message: "Successfully authenticated with ULink. You can now use all ULink tools to manage projects, links, and domains.",
+                        }),
+                    }],
+            };
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Authentication failed: ${reason}. Please try again.`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // get_onboarding_status
+    // -----------------------------------------------------------------------
+    server.registerTool("get_onboarding_status", {
+        title: "Get Onboarding Status",
+        description: "Get the onboarding progress for a ULink project, including which setup steps are complete and what to do next. Requires authentication. Use this after creating a project to guide users through setup.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            projectId: z
+                .string()
+                .describe("The project ID to check onboarding status for."),
+        },
+    }, async ({ projectId }) => {
+        try {
+            // Pre-check: verify auth exists to avoid unexpected browser popup
+            const apiKey = getApiKey();
+            const tokens = loadTokensFromDisk();
+            if (!apiKey && !tokens) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Not authenticated. Call the 'authenticate' tool first, then retry.",
+                        }],
+                    isError: true,
+                };
+            }
+            const data = await apiRequest("GET", `/projects/${encodeURIComponent(projectId)}/onboarding`);
+            // Compute next step from boolean flags
+            const steps = [
+                { key: "domain_setup_completed", step: "domain_setup", desc: "Set up a domain using the add_domain tool" },
+                { key: "platform_selection_completed", step: "platform_selection", desc: "Select target platforms using configure_project" },
+                { key: "platform_config_completed", step: "platform_config", desc: "Complete platform configuration (bundle ID, package name, etc.)" },
+                { key: "platform_implementation_viewed", step: "platform_implementation", desc: "Review platform implementation guide for your selected platforms" },
+                { key: "cli_verified", step: "cli_verification", desc: "Verify setup by running 'ulink verify' CLI command" },
+                { key: "sdk_setup_viewed", step: "sdk_setup", desc: "Review SDK setup guide for creating and receiving links" },
+            ];
+            let completedCount = 0;
+            let nextStep = "complete";
+            let nextStepDescription = "Onboarding complete! You can now create links with create_link.";
+            let foundNext = false;
+            for (const s of steps) {
+                if (data[s.key]) {
+                    completedCount++;
+                }
+                else if (!foundNext) {
+                    nextStep = s.step;
+                    nextStepDescription = s.desc;
+                    foundNext = true;
+                }
+            }
+            const completionPercentage = Math.round((completedCount / steps.length) * 100);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            ...data,
+                            nextStep,
+                            nextStepDescription,
+                            completedSteps: completedCount,
+                            totalSteps: steps.length,
+                            completionPercentage,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=auth.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulinkly/mcp-server",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "ULink MCP Server — Model Context Protocol server for the ULink REST API",
   "type": "module",
   "bin": {