@ontos-ai/knowhere-mcp 0.2.0

package/dist/stdio.js

@@ -0,0 +1,943 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_knowhere_sdk = require("@ontos-ai/knowhere-sdk");
+var z = __toESM(require("zod/v4"));
+var parsingParamsSchema = z.object({
+  model: z.enum(["base", "advanced"]).optional(),
+  ocrEnabled: z.boolean().optional(),
+  kbDir: z.string().optional(),
+  docType: z.enum(["auto", "pdf", "docx", "txt", "md"]).optional(),
+  smartTitleParse: z.boolean().optional(),
+  summaryImage: z.boolean().optional(),
+  summaryTable: z.boolean().optional(),
+  summaryTxt: z.boolean().optional(),
+  addFragDesc: z.string().optional()
+}).optional();
+var objectOutputSchema = {
+  result: z.record(z.string(), z.unknown())
+};
+async function createKnowhereMcpServer(options) {
+  const client = options?.client ?? new import_knowhere_sdk.Knowhere({
+    authTokenProvider: options?.authTokenProvider,
+    baseURL: options?.baseURL
+  });
+  const knowledge = options?.cacheDirectory === void 0 ? client.knowledge : client.knowledge.withCacheDirectory(options.cacheDirectory);
+  if (options?.recoverPendingJobsOnStart !== false) {
+    await knowledge.recoverPendingAsyncParseJobs();
+  }
+  const server = new import_mcp.McpServer({
+    name: "knowhere-local-knowledge",
+    version: import_knowhere_sdk.VERSION
+  });
+  const permission = options?.permission ?? "full_access";
+  const hasWritePermission = permission === "full_access";
+  if (hasWritePermission) {
+    server.registerTool(
+      "knowhere_parse_url",
+      {
+        description: "Blocking parse: submit a remote URL to Knowhere, wait for completion, then cache the parse result locally for outline/read/grep/search tools.",
+        inputSchema: {
+          url: z.string().url(),
+          namespace: z.string().optional(),
+          localDocumentId: z.string().optional(),
+          dataId: z.string().optional(),
+          parsingParams: parsingParamsSchema
+        },
+        outputSchema: objectOutputSchema
+      },
+      async (input) => createToolResult(
+        await knowledge.parse({
+          url: input.url,
+          namespace: input.namespace,
+          localDocumentId: input.localDocumentId,
+          dataId: input.dataId,
+          ...toFlatParsingParams(input.parsingParams)
+        })
+      )
+    );
+    server.registerTool(
+      "knowhere_parse_file",
+      {
+        description: "Blocking parse: submit a local file path available to this MCP process, wait for completion, then cache the parse result locally.",
+        inputSchema: {
+          file: z.string().describe("Local file path available to this MCP server process."),
+          fileName: z.string().optional(),
+          namespace: z.string().optional(),
+          localDocumentId: z.string().optional(),
+          dataId: z.string().optional(),
+          parsingParams: parsingParamsSchema
+        },
+        outputSchema: objectOutputSchema
+      },
+      async (input) => createToolResult(
+        await knowledge.parse({
+          file: input.file,
+          fileName: input.fileName,
+          namespace: input.namespace,
+          localDocumentId: input.localDocumentId,
+          dataId: input.dataId,
+          ...toFlatParsingParams(input.parsingParams)
+        })
+      )
+    );
+    server.registerTool(
+      "knowhere_async_parse_url",
+      {
+        description: "Start parsing a remote URL through Knowhere and return immediately with the parse job. Poll with knowhere_async_get_job_status; completed tracked jobs are cached locally automatically.",
+        inputSchema: {
+          url: z.string().url(),
+          namespace: z.string().optional(),
+          localDocumentId: z.string().optional(),
+          dataId: z.string().optional(),
+          parsingParams: parsingParamsSchema
+        },
+        outputSchema: objectOutputSchema
+      },
+      async (input) => createToolResult(
+        await knowledge.startParse({
+          url: input.url,
+          namespace: input.namespace,
+          localDocumentId: input.localDocumentId,
+          dataId: input.dataId,
+          ...toFlatParsingParams(input.parsingParams)
+        })
+      )
+    );
+    server.registerTool(
+      "knowhere_async_parse_file",
+      {
+        description: "Start parsing a local file path available to this MCP process, upload it if needed, and return immediately with the parse job. Poll with knowhere_async_get_job_status; completed tracked jobs are cached locally automatically.",
+        inputSchema: {
+          file: z.string().describe("Local file path available to this MCP server process."),
+          fileName: z.string().optional(),
+          namespace: z.string().optional(),
+          localDocumentId: z.string().optional(),
+          dataId: z.string().optional(),
+          parsingParams: parsingParamsSchema
+        },
+        outputSchema: objectOutputSchema
+      },
+      async (input) => createToolResult(
+        await knowledge.startParse({
+          file: input.file,
+          fileName: input.fileName,
+          namespace: input.namespace,
+          localDocumentId: input.localDocumentId,
+          dataId: input.dataId,
+          ...toFlatParsingParams(input.parsingParams)
+        })
+      )
+    );
+  }
+  server.registerTool(
+    "knowhere_async_get_job_status",
+    {
+      description: "Fetch the current status for a Knowhere parse job. If the job was started by an async parse tool and is done, this also caches the result locally for outline/read/grep/search.",
+      inputSchema: {
+        jobId: z.string()
+      },
+      outputSchema: objectOutputSchema
+    },
+    async (input) => createToolResult(await knowledge.getJobStatus(input.jobId))
+  );
+  server.registerTool(
+    "knowhere_async_cache_job_result",
+    {
+      description: "Manually load a completed Knowhere parse job result and cache it locally. Usually not needed for jobs started by async parse tools because knowhere_async_get_job_status auto-caches them when done.",
+      inputSchema: {
+        jobId: z.string(),
+        localDocumentId: z.string().optional(),
+        verifyChecksum: z.boolean().optional()
+      },
+      outputSchema: objectOutputSchema
+    },
+    async (input) => createToolResult(
+      await knowledge.cacheJobResult({
+        jobId: input.jobId,
+        localDocumentId: input.localDocumentId,
+        verifyChecksum: input.verifyChecksum
+      })
+    )
+  );
+  server.registerTool(
+    "knowhere_list_documents",
+    {
+      description: "List parse results cached locally by this SDK-backed MCP server.",
+      inputSchema: {},
+      outputSchema: objectOutputSchema
+    },
+    async () => createToolResult({ documents: await knowledge.listDocuments() })
+  );
+  if (hasWritePermission) {
+    server.registerTool(
+      "knowhere_delete_document",
+      {
+        description: "Archive, or soft-delete, a published Knowhere document through the Knowhere API. Provide documentId directly, or localDocumentId for a cached parse result that has a server documentId.",
+        inputSchema: {
+          documentId: z.string().optional(),
+          localDocumentId: z.string().optional()
+        },
+        outputSchema: objectOutputSchema
+      },
+      async (input) => createToolResult(await archiveDocument({ client, knowledge, params: input }))
+    );
+  }
+  server.registerTool(
+    "knowhere_get_document_outline",
+    {
+      description: "Return the local outline for a cached parsed document.",
+      inputSchema: {
+        localDocumentId: z.string()
+      },
+      outputSchema: objectOutputSchema
+    },
+    async (input) => createToolResult(await knowledge.getDocumentOutline(input.localDocumentId))
+  );
+  server.registerTool(
+    "knowhere_read_chunks",
+    {
+      description: "Read exact chunks from a cached local parse result.",
+      inputSchema: {
+        localDocumentId: z.string(),
+        sectionPath: z.string().optional(),
+        startChunk: z.number().int().positive().optional(),
+        endChunk: z.number().int().positive().optional(),
+        chunkId: z.string().optional(),
+        chunkType: z.enum(["text", "image", "table"]).optional(),
+        limit: z.number().int().positive().optional()
+      },
+      outputSchema: objectOutputSchema
+    },
+    async (input) => createToolResult(await knowledge.readChunks(input))
+  );
+  server.registerTool(
+    "knowhere_grep_chunks",
+    {
+      description: "Run grep-style literal or regex matching against cached local chunks.",
+      inputSchema: {
+        localDocumentId: z.string(),
+        pattern: z.string(),
+        isRegex: z.boolean().optional(),
+        isCaseSensitive: z.boolean().optional(),
+        maxResults: z.number().int().positive().optional(),
+        chunkType: z.enum(["text", "image", "table"]).optional(),
+        sectionPathPrefix: z.string().optional(),
+        contextChars: z.number().int().nonnegative().optional()
+      },
+      outputSchema: objectOutputSchema
+    },
+    async (input) => createToolResult(await knowledge.grepChunks(input))
+  );
+  server.registerTool(
+    "knowhere_search",
+    {
+      description: "Search published Knowhere documents with the Knowhere API retrieval query. localDocumentIds only map returned server document IDs back to local cache IDs when available.",
+      inputSchema: {
+        query: z.string(),
+        namespace: z.string().optional(),
+        topK: z.number().int().positive().optional(),
+        localDocumentIds: z.array(z.string()).optional(),
+        useAgentic: z.boolean().optional()
+      },
+      outputSchema: objectOutputSchema
+    },
+    async (input) => createToolResult(await knowledge.search(input))
+  );
+  return server;
+}
+async function runKnowhereMcpServer(options) {
+  const server = await createKnowhereMcpServer(options);
+  const transport = new import_stdio.StdioServerTransport();
+  await server.connect(transport);
+}
+function createToolResult(result) {
+  const structuredContent = { result };
+  return {
+    content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
+    structuredContent
+  };
+}
+function toFlatParsingParams(parsingParams) {
+  if (!parsingParams) {
+    return {};
+  }
+  return {
+    model: parsingParams.model,
+    ocr: parsingParams.ocrEnabled,
+    docType: parsingParams.docType,
+    smartTitleParse: parsingParams.smartTitleParse,
+    summaryImage: parsingParams.summaryImage,
+    summaryTable: parsingParams.summaryTable,
+    summaryTxt: parsingParams.summaryTxt,
+    addFragDesc: parsingParams.addFragDesc,
+    kbDir: parsingParams.kbDir
+  };
+}
+async function archiveDocument(params) {
+  const archiveTarget = await resolveArchiveTarget(params.knowledge, params.params);
+  const document = await params.client.documents.archive(archiveTarget.documentId);
+  return {
+    document,
+    localDocumentId: archiveTarget.localDocumentId
+  };
+}
+async function resolveArchiveTarget(knowledge, params) {
+  if (params.documentId) {
+    return {
+      documentId: params.documentId,
+      localDocumentId: params.localDocumentId
+    };
+  }
+  if (!params.localDocumentId) {
+    throw new import_knowhere_sdk.ValidationError("documentId or localDocumentId is required");
+  }
+  const document = await findLocalDocument(knowledge, params.localDocumentId);
+  if (!document) {
+    throw new Error(`Local Knowhere document not found: ${params.localDocumentId}`);
+  }
+  if (!document.documentId) {
+    throw new Error(`Local Knowhere document has no server documentId: ${params.localDocumentId}`);
+  }
+  return {
+    documentId: document.documentId,
+    localDocumentId: document.localDocumentId
+  };
+}
+async function findLocalDocument(knowledge, localDocumentId) {
+  const documents = await knowledge.listDocuments();
+  return documents.find((document) => document.localDocumentId === localDocumentId);
+}
+
+// src/auth.ts
+var import_child_process = require("child_process");
+var import_crypto = __toESM(require("crypto"));
+var import_http = require("http");
+var import_os = __toESM(require("os"));
+var import_path = __toESM(require("path"));
+var import_promises = require("fs/promises");
+var import_knowhere_sdk2 = require("@ontos-ai/knowhere-sdk");
+var DEFAULT_DASHBOARD_URL = "https://knowhereto.ai";
+var AUTH_FILE_ENV = "KNOWHERE_MCP_AUTH_FILE";
+var DASHBOARD_URL_ENV = "KNOWHERE_DASHBOARD_URL";
+var API_BASE_URL_ENV = "KNOWHERE_BASE_URL";
+var API_KEY_ENV = "KNOWHERE_API_KEY";
+var TOKEN_REFRESH_SKEW_MS = 5 * 60 * 1e3;
+var LOGIN_TIMEOUT_MS = 5 * 60 * 1e3;
+var RANDOM_BYTE_LENGTH = 32;
+var DEFAULT_CLIENT_NAME = "knowhere-cli";
+var DEFAULT_PERMISSION = "full_access";
+var PERMISSION_VALUES = /* @__PURE__ */ new Set(["read_only", "full_access"]);
+var McpCredentialManager = class {
+  authFilePath;
+  refreshPromise;
+  constructor(authFilePath = getDefaultAuthFilePath()) {
+    this.authFilePath = authFilePath;
+  }
+  getAuthFilePath() {
+    return this.authFilePath;
+  }
+  async getStatus() {
+    if (process.env[API_KEY_ENV]) {
+      return {
+        source: "api_key",
+        authFilePath: this.authFilePath,
+        apiBaseUrl: process.env[API_BASE_URL_ENV],
+        permission: DEFAULT_PERMISSION
+      };
+    }
+    const storedAuth = await this.readAuth();
+    if (!storedAuth) {
+      return { source: "none", authFilePath: this.authFilePath };
+    }
+    return {
+      source: "stored_login",
+      authFilePath: this.authFilePath,
+      dashboardUrl: storedAuth.dashboardUrl,
+      apiBaseUrl: process.env[API_BASE_URL_ENV] ?? storedAuth.apiBaseUrl,
+      permission: storedAuth.permission,
+      refreshTokenExpiresAt: storedAuth.refreshTokenExpiresAt,
+      accessTokenExpiresAt: storedAuth.accessTokenExpiresAt
+    };
+  }
+  async hasStoredLogin() {
+    return await this.readAuth() !== void 0;
+  }
+  async getAccessToken() {
+    const storedAuth = await this.readAuth();
+    if (!storedAuth) {
+      throw new import_knowhere_sdk2.ValidationError(
+        'Knowhere MCP is not logged in. Run "npx -y @ontos-ai/knowhere-mcp login" or set KNOWHERE_API_KEY.'
+      );
+    }
+    if (isUsableAccessToken(storedAuth)) {
+      return storedAuth.accessToken;
+    }
+    if (!this.refreshPromise) {
+      this.refreshPromise = this.refreshAccessToken(storedAuth).finally(() => {
+        this.refreshPromise = void 0;
+      });
+    }
+    return this.refreshPromise;
+  }
+  async login(options = {}) {
+    const dashboardUrl = normalizeDashboardUrl(
+      options.dashboardUrl ?? process.env[DASHBOARD_URL_ENV] ?? DEFAULT_DASHBOARD_URL
+    );
+    const apiBaseUrl = options.baseURL ?? process.env[API_BASE_URL_ENV];
+    const codeVerifier = createRandomToken();
+    const state = createRandomToken();
+    const codeChallenge = createPkceChallenge(codeVerifier);
+    const callback = await createLoopbackCallback(state);
+    try {
+      const loginUrl = buildLoginUrl({
+        dashboardUrl,
+        redirectUri: callback.redirectUri,
+        state,
+        codeChallenge,
+        clientName: options.clientName ?? DEFAULT_CLIENT_NAME
+      });
+      options.onLoginUrl?.(loginUrl);
+      if (options.openBrowser !== false) {
+        openBrowser(loginUrl);
+      }
+      const code = await callback.waitForCode();
+      const tokenResponse = await requestToken(dashboardUrl, {
+        grant_type: "authorization_code",
+        code,
+        code_verifier: codeVerifier,
+        client_name: options.clientName ?? DEFAULT_CLIENT_NAME
+      });
+      const storedAuth = buildStoredAuth({
+        dashboardUrl,
+        apiBaseUrl,
+        tokenResponse,
+        previous: await this.readAuth()
+      });
+      await this.writeAuth(storedAuth);
+      return {
+        authFilePath: this.authFilePath,
+        dashboardUrl,
+        apiBaseUrl,
+        permission: tokenResponse.permission,
+        refreshTokenExpiresAt: tokenResponse.refreshTokenExpiresAt
+      };
+    } finally {
+      await callback.close();
+    }
+  }
+  async logout() {
+    const storedAuth = await this.readAuth();
+    let revokeError;
+    if (storedAuth) {
+      try {
+        await requestRevoke(storedAuth.dashboardUrl, storedAuth.refreshToken);
+      } catch (error) {
+        revokeError = error instanceof Error ? error.message : "Failed to revoke MCP login";
+      }
+    }
+    await (0, import_promises.rm)(this.authFilePath, { force: true });
+    return {
+      authFilePath: this.authFilePath,
+      hadStoredLogin: storedAuth !== void 0,
+      revokeError
+    };
+  }
+  async resolveBaseURL() {
+    return process.env[API_BASE_URL_ENV] ?? (await this.readAuth())?.apiBaseUrl;
+  }
+  async refreshAccessToken(storedAuth) {
+    const tokenResponse = await requestToken(storedAuth.dashboardUrl, {
+      grant_type: "refresh_token",
+      refresh_token: storedAuth.refreshToken
+    });
+    const refreshedAuth = buildStoredAuth({
+      dashboardUrl: storedAuth.dashboardUrl,
+      apiBaseUrl: storedAuth.apiBaseUrl,
+      tokenResponse,
+      previous: storedAuth
+    });
+    await this.writeAuth(refreshedAuth);
+    return refreshedAuth.accessToken ?? "";
+  }
+  async readAuth() {
+    try {
+      const rawAuth = await (0, import_promises.readFile)(this.authFilePath, "utf8");
+      return parseStoredAuth(JSON.parse(rawAuth));
+    } catch (error) {
+      if (isFileMissingError(error)) {
+        return void 0;
+      }
+      throw error;
+    }
+  }
+  async writeAuth(storedAuth) {
+    await (0, import_promises.mkdir)(import_path.default.dirname(this.authFilePath), { recursive: true, mode: 448 });
+    await (0, import_promises.writeFile)(this.authFilePath, `${JSON.stringify(storedAuth, null, 2)}
+`, {
+      mode: 384
+    });
+    await (0, import_promises.chmod)(this.authFilePath, 384);
+  }
+};
+function getDefaultAuthFilePath() {
+  return process.env[AUTH_FILE_ENV] ?? import_path.default.join(import_os.default.homedir(), ".knowhere-node-sdk", "mcp", "auth.json");
+}
+function isUsableAccessToken(storedAuth) {
+  if (!storedAuth.accessToken || !storedAuth.accessTokenExpiresAt) {
+    return false;
+  }
+  const expiresAt = Date.parse(storedAuth.accessTokenExpiresAt);
+  return Number.isFinite(expiresAt) && expiresAt - Date.now() > TOKEN_REFRESH_SKEW_MS;
+}
+function buildStoredAuth({
+  dashboardUrl,
+  apiBaseUrl,
+  tokenResponse,
+  previous
+}) {
+  const now = /* @__PURE__ */ new Date();
+  const accessTokenExpiresAt = new Date(
+    now.getTime() + tokenResponse.expiresInSeconds * 1e3
+  ).toISOString();
+  const refreshToken = tokenResponse.refreshToken ?? previous?.refreshToken;
+  if (!refreshToken) {
+    throw new Error("Knowhere MCP token response did not include a refresh token");
+  }
+  return {
+    dashboardUrl,
+    apiBaseUrl,
+    permission: tokenResponse.permission,
+    refreshToken,
+    refreshTokenExpiresAt: tokenResponse.refreshTokenExpiresAt ?? previous?.refreshTokenExpiresAt,
+    accessToken: tokenResponse.accessToken,
+    accessTokenExpiresAt,
+    createdAt: previous?.createdAt ?? now.toISOString(),
+    updatedAt: now.toISOString()
+  };
+}
+function parseStoredAuth(value) {
+  if (!isRecord(value)) {
+    throw new Error("Invalid Knowhere MCP auth file");
+  }
+  const dashboardUrl = readRequiredString(value, "dashboardUrl");
+  const refreshToken = readRequiredString(value, "refreshToken");
+  const createdAt = readRequiredString(value, "createdAt");
+  const updatedAt = readRequiredString(value, "updatedAt");
+  return {
+    dashboardUrl,
+    apiBaseUrl: readOptionalString(value, "apiBaseUrl"),
+    permission: normalizePermission(readOptionalString(value, "permission")),
+    refreshToken,
+    refreshTokenExpiresAt: readOptionalString(value, "refreshTokenExpiresAt"),
+    accessToken: readOptionalString(value, "accessToken"),
+    accessTokenExpiresAt: readOptionalString(value, "accessTokenExpiresAt"),
+    createdAt,
+    updatedAt
+  };
+}
+function readRequiredString(value, key) {
+  const field = value[key];
+  if (typeof field !== "string" || field.length === 0) {
+    throw new Error(`Invalid Knowhere MCP auth file: ${key} is required`);
+  }
+  return field;
+}
+function readOptionalString(value, key) {
+  const field = value[key];
+  return typeof field === "string" && field.length > 0 ? field : void 0;
+}
+function readRequiredPermission(value, key) {
+  const field = value[key];
+  if (typeof field !== "string" || field.length === 0) {
+    throw new Error(`Invalid Knowhere MCP token response: ${key} is required`);
+  }
+  if (!PERMISSION_VALUES.has(field)) {
+    throw new Error(`Invalid Knowhere MCP token response: ${key} is invalid`);
+  }
+  return field;
+}
+function createPkceChallenge(codeVerifier) {
+  return import_crypto.default.createHash("sha256").update(codeVerifier).digest("base64url");
+}
+function buildLoginUrl({
+  dashboardUrl,
+  redirectUri,
+  state,
+  codeChallenge,
+  clientName
+}) {
+  const url = new URL("/mcp/login", dashboardUrl);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("client_name", clientName);
+  return url.toString();
+}
+async function createLoopbackCallback(expectedState) {
+  let resolveCode;
+  let rejectCode;
+  let isSettled = false;
+  const codePromise = new Promise((resolve, reject) => {
+    resolveCode = resolve;
+    rejectCode = reject;
+  });
+  const timeout = setTimeout(() => {
+    if (!isSettled) {
+      isSettled = true;
+      rejectCode?.(new Error("Timed out waiting for Dashboard login callback"));
+    }
+  }, LOGIN_TIMEOUT_MS);
+  const server = (0, import_http.createServer)((request, response) => {
+    handleCallbackRequest({
+      request,
+      response,
+      expectedState,
+      resolveCode: (code) => {
+        if (!isSettled) {
+          isSettled = true;
+          clearTimeout(timeout);
+          resolveCode?.(code);
+        }
+      },
+      rejectCode: (error) => {
+        if (!isSettled) {
+          isSettled = true;
+          clearTimeout(timeout);
+          rejectCode?.(error);
+        }
+      }
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new Error("Failed to start loopback login callback server");
+  }
+  return {
+    redirectUri: `http://127.0.0.1:${address.port}/callback`,
+    waitForCode: () => codePromise,
+    close: () => new Promise((resolve, reject) => {
+      clearTimeout(timeout);
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    })
+  };
+}
+function handleCallbackRequest({
+  request,
+  response,
+  expectedState,
+  resolveCode,
+  rejectCode
+}) {
+  const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+  if (requestUrl.pathname !== "/callback") {
+    response.writeHead(404);
+    response.end("Not found");
+    return;
+  }
+  const code = requestUrl.searchParams.get("code");
+  const callbackError = requestUrl.searchParams.get("error");
+  const state = requestUrl.searchParams.get("state");
+  if (callbackError) {
+    response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+    response.end("Knowhere MCP login was denied. You can close this window.");
+    rejectCode(new Error(`Dashboard login failed: ${callbackError}`));
+    return;
+  }
+  if (!code || state !== expectedState) {
+    response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+    response.end("Knowhere MCP login failed. You can close this window.");
+    rejectCode(new Error("Dashboard login callback did not include a valid code and state"));
+    return;
+  }
+  response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+  response.end(
+    "<!doctype html><title>Knowhere MCP</title><p>Knowhere MCP login complete. You can close this window.</p>"
+  );
+  resolveCode(code);
+}
+async function requestToken(dashboardUrl, body) {
+  const response = await fetch(new URL("/api/mcp/token", dashboardUrl), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const responseBody = await readJsonResponse(response);
+  if (!response.ok) {
+    throw new Error(getResponseMessage(responseBody, "Knowhere MCP token request failed"));
+  }
+  return parseTokenResponse(responseBody);
+}
+async function requestRevoke(dashboardUrl, refreshToken) {
+  const response = await fetch(new URL("/api/mcp/revoke", dashboardUrl), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ refresh_token: refreshToken })
+  });
+  const responseBody = await readJsonResponse(response);
+  if (!response.ok) {
+    throw new Error(getResponseMessage(responseBody, "Knowhere MCP revoke request failed"));
+  }
+}
+async function readJsonResponse(response) {
+  try {
+    return await response.json();
+  } catch {
+    return void 0;
+  }
+}
+function parseTokenResponse(value) {
+  if (!isRecord(value)) {
+    throw new Error("Invalid Knowhere MCP token response");
+  }
+  const accessToken = readRequiredString(value, "accessToken");
+  const tokenType = readRequiredString(value, "tokenType");
+  const expiresInSeconds = value.expiresInSeconds;
+  const permission = readRequiredPermission(value, "permission");
+  if (tokenType !== "Bearer") {
+    throw new Error("Invalid Knowhere MCP token type");
+  }
+  if (typeof expiresInSeconds !== "number" || !Number.isFinite(expiresInSeconds)) {
+    throw new Error("Invalid Knowhere MCP token expiry");
+  }
+  return {
+    accessToken,
+    expiresInSeconds,
+    permission,
+    refreshToken: readOptionalString(value, "refreshToken"),
+    refreshTokenExpiresAt: readOptionalString(value, "refreshTokenExpiresAt"),
+    tokenType
+  };
+}
+function getResponseMessage(responseBody, fallback) {
+  if (isRecord(responseBody) && typeof responseBody.message === "string") {
+    return responseBody.message;
+  }
+  return fallback;
+}
+function normalizeDashboardUrl(value) {
+  const url = new URL(value);
+  url.pathname = "/";
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+function normalizePermission(value) {
+  if (value && PERMISSION_VALUES.has(value)) {
+    return value;
+  }
+  return DEFAULT_PERMISSION;
+}
+function openBrowser(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  const child = (0, import_child_process.spawn)(command, args, {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+}
+function createRandomToken() {
+  return import_crypto.default.randomBytes(RANDOM_BYTE_LENGTH).toString("base64url");
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFileMissingError(error) {
+  return error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
+}
+
+// src/stdio.ts
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  switch (command) {
+    case void 0:
+    case "serve":
+      await runKnowhereMcpServerWithAuth();
+      return;
+    case "login":
+      await runLogin(args);
+      return;
+    case "logout":
+      await runLogout();
+      return;
+    case "status":
+      await runStatus();
+      return;
+    case "--help":
+    case "-h":
+    case "help":
+      printHelp();
+      return;
+    default:
+      throw new Error(`Unknown knowhere-mcp command: ${command}`);
+  }
+}
+async function runKnowhereMcpServerWithAuth() {
+  const credentialManager = new McpCredentialManager();
+  const status = await credentialManager.getStatus();
+  if (process.env.KNOWHERE_API_KEY) {
+    await runKnowhereMcpServer({ permission: status.permission });
+    return;
+  }
+  await runKnowhereMcpServer({
+    authTokenProvider: () => credentialManager.getAccessToken(),
+    baseURL: await credentialManager.resolveBaseURL(),
+    permission: status.permission,
+    recoverPendingJobsOnStart: status.source === "stored_login"
+  });
+}
+async function runLogin(args) {
+  const options = parseLoginArgs(args);
+  const credentialManager = new McpCredentialManager(options.authFilePath);
+  const result = await credentialManager.login({
+    dashboardUrl: options.dashboardUrl,
+    baseURL: options.baseURL,
+    openBrowser: options.openBrowser,
+    clientName: options.clientName,
+    onLoginUrl: (url) => {
+      console.log(`Open this URL to log in to Knowhere:
+${url}`);
+    }
+  });
+  console.log(`Knowhere MCP login saved to ${result.authFilePath}`);
+  console.log(`Permission: ${result.permission}`);
+  if (result.refreshTokenExpiresAt) {
+    console.log(`Refresh token expires at ${result.refreshTokenExpiresAt}`);
+  }
+}
+async function runLogout() {
+  const credentialManager = new McpCredentialManager();
+  const result = await credentialManager.logout();
+  if (result.revokeError) {
+    console.error(
+      `Knowhere MCP login was removed locally, but revoke failed: ${result.revokeError}`
+    );
+  }
+  console.log(
+    result.hadStoredLogin ? `Knowhere MCP login removed from ${result.authFilePath}` : `No Knowhere MCP login found at ${result.authFilePath}`
+  );
+}
+async function runStatus() {
+  const credentialManager = new McpCredentialManager();
+  const status = await credentialManager.getStatus();
+  console.log(formatStatus(status));
+}
+function parseLoginArgs(args) {
+  const options = {
+    openBrowser: true
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    switch (arg) {
+      case "--dashboard-url":
+        options.dashboardUrl = readFlagValue(args, index, arg);
+        index += 1;
+        break;
+      case "--base-url":
+        options.baseURL = readFlagValue(args, index, arg);
+        index += 1;
+        break;
+      case "--auth-file":
+        options.authFilePath = readFlagValue(args, index, arg);
+        index += 1;
+        break;
+      case "--client-name":
+        options.clientName = readFlagValue(args, index, arg);
+        index += 1;
+        break;
+      case "--no-open":
+        options.openBrowser = false;
+        break;
+      default:
+        throw new Error(`Unknown login option: ${arg}`);
+    }
+  }
+  return options;
+}
+function readFlagValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+function formatStatus(status) {
+  switch (status.source) {
+    case "api_key":
+      return [
+        "Knowhere MCP is authenticated with KNOWHERE_API_KEY",
+        `Auth file: ${status.authFilePath}`,
+        `Permission: ${status.permission ?? "full_access"}`
+      ].join("\n");
+    case "stored_login":
+      return [
+        "Knowhere MCP is authenticated with dashboard login",
+        `Auth file: ${status.authFilePath}`,
+        `Dashboard: ${status.dashboardUrl ?? "unknown"}`,
+        `API base URL: ${status.apiBaseUrl ?? "default"}`,
+        `Permission: ${status.permission ?? "full_access"}`,
+        `Refresh token expires: ${status.refreshTokenExpiresAt ?? "unknown"}`,
+        `Access token expires: ${status.accessTokenExpiresAt ?? "not cached"}`
+      ].join("\n");
+    case "none":
+      return `Knowhere MCP is not logged in
+Run: npx -y @ontos-ai/knowhere-mcp login
+Auth file: ${status.authFilePath}`;
+  }
+}
+function printHelp() {
+  console.log(`Usage:
+  knowhere-mcp                 Run the stdio MCP server
+  knowhere-mcp serve           Run the stdio MCP server
+  knowhere-mcp login           Log in through the Knowhere dashboard
+  knowhere-mcp status          Show local MCP auth status
+  knowhere-mcp logout          Remove and revoke local MCP login
+
+Login options:
+  --dashboard-url <url>        Dashboard URL, defaults to KNOWHERE_DASHBOARD_URL or https://knowhereto.ai
+  --base-url <url>             Knowhere API URL, defaults to KNOWHERE_BASE_URL or SDK default
+  --auth-file <path>           Override local auth file path
+  --client-name <name>         Label shown in dashboard token records
+  --no-open                    Print login URL without opening a browser`);
+}
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});