Insights Knowledge Base

You can run and use the Insights Knowledge Base MCP Server to manage a local, private knowledge base of reports and documents. It automates document extraction, embedding, and retrieval, so you can quickly find relevant insights through a dedicated MCP client.

How to use

Set up the MCP server locally and connect with your MCP client to search and retrieve insights. You will run the MCP server as a stdio process and use it as a local endpoint for vector search, keyword retrieval, and online report viewing. The server reads private documents you add to the library_files folder and builds embeddings on demand.

How to install

Prerequisites: Python 3.12 or newer.

pip install uv

Clone the project and fetch large file data if needed.

git clone https://example.org/InsightsLibrary.git
cd InsightsLibrary
git lfs pull

Create and activate a dedicated virtual environment.

uv venv .venv

# Activate the environment
# Windows:
.\.venv\Scripts\activate
# Mac/Linux:
source .venv/bin/activate

Install core dependencies from the current directory.

uv install .

Create environment variables for future needs (optional but recommended for local setup). Enter a text editor and add the variables you will use.

# Example editing command (choose your editor)
nano .env  # Mac/Linux
notepad .env # Windows

Configure the MCP server in the project root. The following snippet shows a local stdio configuration that starts the server with uv and runs the ikb_mcp_server.py script.

{
  "mcpServers": {
    "ikb_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<Your Project Root Directory!!!>", 
        "run",
        "ikb_mcp_server.py"
      ]
    }
  }
}

Add private documents and start the server

Place your private PDF documents into the library_files folder at the project root. This is where the MCP server will extract text, build embeddings, and make content searchable.

Optional environment variables to configure local models and embedding behavior can be added in the .env file. Example keys (adjust as needed):

VLM_API_KEY=<API Key>
VLM_BASE_URL=<Base URL> # e.g. https://openrouter.ai/api/v1
VLM_MODEL_NAME=<Model Name> # e.g. qwen/qwen2.5-vl-72b-instruct:free

Run the main processing workflow to extract, recognize, and optionally embed content. This starts the extraction and prepares the knowledge base for queries.

# Navigate to the project root directory
# Activate the virtual environment if not already active
uv run main.py

Usage patterns and tips

• Add new documents regularly to keep the knowledge base up to date, and run the main pipeline to index new content.

• Use the built-in vector search to find similar content via the Qwen3-Embedding-0.6B model and rely on keyword retrieval for quick text-based queries.

Notes and security

All reports and documents are stored locally. Ensure your private data is secured according to your organization’s policies.

License

This project is licensed under the MIT License.

Available tools

get_similar_content_by_rag

Finds the most similar document content using vector similarity (RAG) to support fast, relevant retrieval of reports.