@ontos-ai/knowhere-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knowhere Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# Knowhere MCP
+
+`@ontos-ai/knowhere-mcp` is a thin Model Context Protocol wrapper around
+`@ontos-ai/knowhere-sdk`.
+
+The SDK owns the parse, cache, outline, read, grep, and search behavior. This
+package only exposes that SDK interface as MCP tools.
+
+## Install
+
+```bash
+npm install @ontos-ai/knowhere-mcp
+```
+
+## Run
+
+```bash
+npx -y @ontos-ai/knowhere-mcp login
+npx -y @ontos-ai/knowhere-mcp
+```
+
+The server uses stdio transport and stores expanded Knowhere result files under
+the SDK local knowledge cache by default. `knowhere-mcp login` opens the
+Knowhere dashboard in your browser and stores a local MCP login at
+`~/.knowhere-node-sdk/mcp/auth.json`.
+
+During login, the dashboard asks for a Permission:
+
+- Read only: query Knowhere and read existing parsed documents. Parse and
+  delete tools are not exposed to the MCP host.
+- Full access: query, read, parse URLs/files, cache completed parse jobs, and
+  archive documents.
+
+Useful auth commands:
+
+```bash
+npx -y @ontos-ai/knowhere-mcp login
+npx -y @ontos-ai/knowhere-mcp status
+npx -y @ontos-ai/knowhere-mcp logout
+```
+
+`knowhere-mcp status` shows the stored Permission for the current login.
+
+Set `KNOWHERE_DASHBOARD_URL` when logging in through a non-default dashboard.
+Set `KNOWHERE_BASE_URL` only when using a non-default Knowhere API endpoint.
+`KNOWHERE_API_KEY` is still supported as a manual fallback and takes precedence
+over the local dashboard login. API-key authentication runs with full access.
+
+## Connect From MCP Hosts
+
+The package is a local stdio MCP server. Use `npx -y @ontos-ai/knowhere-mcp`
+as the server command in hosts that manage MCP processes for you. Run the login
+command once before connecting a host:
+
+```bash
+npx -y @ontos-ai/knowhere-mcp login
+```
+
+The host config does not need `KNOWHERE_API_KEY` when dashboard login is used.
+Do not commit real API keys to shared project config files if you choose the
+manual API-key fallback.
+
+### Codex
+
+Codex stores MCP servers in `~/.codex/config.toml` by default. Trusted projects
+can also use project-scoped `.codex/config.toml`.
+
+Add the server with the Codex CLI:
+
+```bash
+codex mcp add knowhere -- npx -y @ontos-ai/knowhere-mcp
+```
+
+Or edit `config.toml` directly:
+
+```toml
+[mcp_servers.knowhere]
+command = "npx"
+args = ["-y", "@ontos-ai/knowhere-mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
+
+For project-scoped config with a non-default API endpoint, forward only the
+endpoint variable:
+
+```toml
+[mcp_servers.knowhere]
+command = "npx"
+args = ["-y", "@ontos-ai/knowhere-mcp"]
+env_vars = ["KNOWHERE_BASE_URL"]
+```
+
+Restart Codex or run `/mcp` in the Codex TUI to inspect connected MCP servers.
+
+### Claude Code
+
+Add the server with the Claude Code CLI:
+
+```bash
+claude mcp add \
+  --transport stdio \
+  knowhere \
+  -- npx -y @ontos-ai/knowhere-mcp
+```
+
+Use `/mcp` inside Claude Code to verify the server and `claude mcp list` to see
+configured servers.
+
+For a project-shared `.mcp.json`, forward environment variables rather than
+committing secrets:
+
+```json
+{
+  "mcpServers": {
+    "knowhere": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@ontos-ai/knowhere-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Open Claude Desktop settings, go to the developer settings, and edit
+`claude_desktop_config.json`.
+
+Config file locations:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add the Knowhere server:
+
+```json
+{
+  "mcpServers": {
+    "knowhere": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@ontos-ai/knowhere-mcp"]
+    }
+  }
+}
+```
+
+Save the file and fully restart Claude Desktop. If the server does not appear,
+check Claude's MCP logs and verify that `node`, `npm`, and `npx` are available
+from the desktop app's environment.
+
+### Other Stdio MCP Hosts
+
+Use the same process configuration:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@ontos-ai/knowhere-mcp"]
+}
+```
+
+Host documentation:
+
+- [Codex MCP configuration](https://developers.openai.com/codex/mcp)
+- [Claude Code MCP configuration](https://docs.anthropic.com/en/docs/claude-code/mcp)
+- [Claude Desktop local MCP servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
+
+## Tools
+
+When logged in with Read only permission, the MCP server exposes only
+`knowhere_search`, `knowhere_list_documents`,
+`knowhere_get_document_outline`, `knowhere_read_chunks`,
+`knowhere_grep_chunks`, `knowhere_async_get_job_status`, and
+`knowhere_async_cache_job_result`.
+
+- `knowhere_parse_url`: blocking parse for a remote URL; waits for completion
+  and caches the result locally.
+- `knowhere_parse_file`: blocking parse for a file path available to the MCP
+  process; waits for completion and caches the result locally.
+- `knowhere_async_parse_url`: start parsing a remote URL and return the job
+  immediately.
+- `knowhere_async_parse_file`: start parsing a local file path, upload it if
+  needed, and return the job immediately.
+- `knowhere_async_get_job_status`: check a parse job status; completed jobs
+  started by async parse tools are cached locally automatically.
+- `knowhere_async_cache_job_result`: manually cache a completed parse job result
+  locally, mainly for recovery or jobs started outside the async parse tools.
+- `knowhere_list_documents`: list locally cached parse results.
+- `knowhere_delete_document`: archive, or soft-delete, a published Knowhere
+  document through the Knowhere API.
+- `knowhere_get_document_outline`: inspect a cached document outline.
+- `knowhere_read_chunks`: read exact chunks from a cached result.
+- `knowhere_grep_chunks`: run local literal or regex grep over cached chunks.
+- `knowhere_search`: search published documents through the Knowhere API
+  retrieval query.
+
+## Package Boundary
+
+Use `@ontos-ai/knowhere-sdk` directly when building an app. Install this MCP
+package when an agent host needs a local MCP server.

package/dist/chunk-ZITSXYWR.mjs

@@ -0,0 +1,319 @@
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  Knowhere,
+  VERSION,
+  ValidationError
+} from "@ontos-ai/knowhere-sdk";
+import * as z from "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 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 McpServer({
+    name: "knowhere-local-knowledge",
+    version: 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 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 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);
+}
+
+export {
+  createKnowhereMcpServer,
+  runKnowhereMcpServer
+};

package/dist/index.d.mts

@@ -0,0 +1,17 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Knowhere, AuthTokenProvider } from '@ontos-ai/knowhere-sdk';
+
+type Permission = 'read_only' | 'full_access';
+
+interface KnowhereMcpServerOptions {
+    client?: Knowhere;
+    authTokenProvider?: AuthTokenProvider;
+    baseURL?: string;
+    cacheDirectory?: string;
+    permission?: Permission;
+    recoverPendingJobsOnStart?: boolean;
+}
+declare function createKnowhereMcpServer(options?: KnowhereMcpServerOptions): Promise<McpServer>;
+declare function runKnowhereMcpServer(options?: KnowhereMcpServerOptions): Promise<void>;
+
+export { type KnowhereMcpServerOptions, createKnowhereMcpServer, runKnowhereMcpServer };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Knowhere, AuthTokenProvider } from '@ontos-ai/knowhere-sdk';
+
+type Permission = 'read_only' | 'full_access';
+
+interface KnowhereMcpServerOptions {
+    client?: Knowhere;
+    authTokenProvider?: AuthTokenProvider;
+    baseURL?: string;
+    cacheDirectory?: string;
+    permission?: Permission;
+    recoverPendingJobsOnStart?: boolean;
+}
+declare function createKnowhereMcpServer(options?: KnowhereMcpServerOptions): Promise<McpServer>;
+declare function runKnowhereMcpServer(options?: KnowhereMcpServerOptions): Promise<void>;
+
+export { type KnowhereMcpServerOptions, createKnowhereMcpServer, runKnowhereMcpServer };