knowdrift

knowdrift connects an MCP client to a web crawl that is organised by topic. Instead of searching the open web blindly, you first ask which topics the crawler has already covered, then pull the documents it filed under the topics that match your question. Answers come back as ranked documents drawn from pages that were actually crawled and indexed.

This package is a thin forwarding client. It speaks MCP over stdio on one side and relays each tool call to the public remote service over streamable HTTP on the other, returning whatever the remote sends back.

Tools

list-topics

Takes no arguments. Returns the names of the topics for which crawled content is currently available, so you can discover the subject areas the index covers before searching it.

search

Retrieves the documents that best match a question inside chosen topics.

CLI usage

npx @reneturcios/knowdrift list-topics
npx @reneturcios/knowdrift search '{"topics":["technology"],"query":"How do vector databases work?","topK":5}'
npx @reneturcios/knowdrift --version

The tool subcommands accept the tool's arguments as a single JSON object string and print the first text block of the result. Exit codes are 0 on success, 1 when the call returns an error result, and 2 for usage errors.

MCP usage

Start the stdio server with the mcp subcommand:

npx -y @reneturcios/knowdrift mcp

MCP client configuration:

{
  "mcpServers": {
    "knowdrift": {
      "command": "npx",
      "args": ["-y", "@reneturcios/knowdrift", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/knowdrift
docker run --rm ghcr.io/cloudcorprecords/knowdrift search '{"topics":["technology"],"query":"What is new in quantum computing?"}'

With no arguments the container runs the stdio MCP server; any other arguments are passed to the CLI.

Configuration

No account or API key is needed: the upstream service is public. When the upstream cannot be reached or answers with an error, the tool returns an error result whose text begins with knowdrift error: rather than fabricating documents.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs fully offline. It drives the forwarding logic against a stubbed JSON-RPC upstream and checks the served tool list against the documented tool surface.

License

MIT — see LICENSE.