@ontos-ai/knowhere-mcp 0.2.0

package/dist/index.js

@@ -0,0 +1,350 @@
+"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 __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createKnowhereMcpServer: () => createKnowhereMcpServer,
+  runKnowhereMcpServer: () => runKnowhereMcpServer
+});
+module.exports = __toCommonJS(index_exports);
+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);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createKnowhereMcpServer,
+  runKnowhereMcpServer
+});

package/dist/index.mjs

@@ -0,0 +1,8 @@
+import {
+  createKnowhereMcpServer,
+  runKnowhereMcpServer
+} from "./chunk-ZITSXYWR.mjs";
+export {
+  createKnowhereMcpServer,
+  runKnowhereMcpServer
+};

package/dist/stdio.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/stdio.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node