@ontos-ai/knowhere-mcp 0.2.0

package/dist/stdio.mjs

@@ -0,0 +1,612 @@
+#!/usr/bin/env node
+import {
+  runKnowhereMcpServer
+} from "./chunk-ZITSXYWR.mjs";
+
+// src/auth.ts
+import { spawn } from "child_process";
+import crypto from "crypto";
+import { createServer } from "http";
+import os from "os";
+import path from "path";
+import { mkdir, readFile, rm, writeFile, chmod } from "fs/promises";
+import { ValidationError } from "@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 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 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 readFile(this.authFilePath, "utf8");
+      return parseStoredAuth(JSON.parse(rawAuth));
+    } catch (error) {
+      if (isFileMissingError(error)) {
+        return void 0;
+      }
+      throw error;
+    }
+  }
+  async writeAuth(storedAuth) {
+    await mkdir(path.dirname(this.authFilePath), { recursive: true, mode: 448 });
+    await writeFile(this.authFilePath, `${JSON.stringify(storedAuth, null, 2)}
+`, {
+      mode: 384
+    });
+    await chmod(this.authFilePath, 384);
+  }
+};
+function getDefaultAuthFilePath() {
+  return process.env[AUTH_FILE_ENV] ?? path.join(os.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 crypto.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 = 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 = spawn(command, args, {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+}
+function createRandomToken() {
+  return crypto.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);
+});

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@ontos-ai/knowhere-mcp",
+  "version": "0.2.0",
+  "description": "MCP wrapper for the Knowhere Node.js SDK local knowledge tools",
+  "keywords": [
+    "knowhere",
+    "mcp",
+    "model-context-protocol",
+    "document-parsing"
+  ],
+  "author": "Knowhere Team <team@knowhereto.ai>",
+  "license": "MIT",
+  "homepage": "https://knowhereto.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ontos-AI/knowhere-node-sdk.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Ontos-AI/knowhere-node-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "knowhere-mcp": "./dist/stdio.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19.0",
+    "npm": ">=10.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76",
+    "@ontos-ai/knowhere-sdk": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/stdio.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts src/stdio.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "vitest",
+    "test:ci": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}