Knowledge

You run a local MCP Knowledge Server to enable AI coding assistants and agents to search your private documents. It provides fast semantic search across multiple contexts, supports many document formats, handles OCR for scanned files, processes in the background, and communicates with clients over HTTP or stdio transports. All processing stays on your machine, keeping your data private while you empower your AI tools with your own knowledge base.

How to use

You access the MCP Knowledge Server from an MCP client (such as Copilot CLI or Claude Desktop) using either an HTTP transport or a stdio transport. Start the server, then choose a transport that matches your client.

• With an HTTP transport, your MCP client talks to the server’s HTTP API. The Copilot CLI integration uses a streamable HTTP endpoint. The default HTTP URL is http://localhost:3000.

• With a stdio transport, you run the server as a local process and connect through standard input/output. You typically start it with a Python command that launches the MCP server in the current environment.

How to install

Prerequisites: you need Python 3.11+ or Python 3.12 and, optionally for scanned documents, Tesseract OCR.

Automated setup and quick demo (recommended): run the quickstart script to create a virtual environment, install dependencies, download the embedding model, and run an end-to-end demo.

Manual installation steps in sequence:

./quickstart.sh

Configuration and operation notes

Configuration is managed via a YAML file named config.yaml in the project root, with a default configuration provided. You can override settings using environment variables with the KNOWLEDGE_ prefix.

Key features you may configure include: storage paths, embedding model, OCR behavior, chunking strategy, processing limits, and logging.

To customize localization, placement, and behavior for OCR and processing, you can edit the YAML snippet shown in the configuration examples.

Usage with MCP clients (practical flow)

1. Start the MCP server via the recommended management script or the Python startup command.

2. Choose a transport based on your client: HTTP for Copilot CLI or Claude Desktop, or stdio for local tooling.

3. Manage contexts to organize your documents. Create contexts, add documents to one or more contexts, and search within a context or across all contexts.

4. Add documents to your knowledge base with optional context assignment, configure OCR per document or globally, and then run semantic searches to retrieve relevant chunks.

Example workflow highlights

Create a context, add documents to it, and perform a context-scoped search.

Search across all contexts when you need a broad view of your documents.

Common tasks and status checks

List or inspect documents, check indexing progress for async processing, and view statistics about documents and contexts.

Use management commands to monitor the server, view logs, and perform restarts as needed.

Security and privacy notes

All processing happens locally on your machine. No data leaves your system unless you explicitly configure a remote transport or export data.

Available tools

knowledge-add

Add documents to the knowledge base with optional context assignment.

knowledge-search

Perform semantic search across documents with optional context filtering.

knowledge-show

List all documents and their metadata, filterable by context.

knowledge-remove

Remove specific documents from the knowledge base.

knowledge-clear

Clear all knowledge from the server.

knowledge-status

Get statistics and health status of the knowledge base.

knowledge-task-status

Check the status of asynchronous processing tasks.

knowledge-context-create

Create a new context for organizing documents.

knowledge-context-list

List all contexts with their statistics.

knowledge-context-show

Show details for a specific context.

knowledge-context-delete

Delete a context (documents remain in other contexts).