## About Intuz

This library is maintained by [Intuz](https://www.intuz.com), an AI-first software development company specializing in [Agentic AI Development](https://www.intuz.com/ai)
and [Custom AI Development](https://www.intuz.com/custom-ai-development).
<br><br>

INTUZ is presenting an enterprise knowledge retrieval and RAG MCP server.

---

# Enterprise Knowledge MCP Server

> An MCP server that exposes semantic search and RAG over enterprise documents as standardized tools for any MCP-compatible client.

## Use Cases

### 1. AI-Powered Knowledge Access for Non-Technical Users
- **Problem:** Business stakeholders cannot query or search internal document repositories without developer help.
- **Solution:** An MCP server that makes enterprise knowledge available as clean tools — any MCP client (Claude Desktop, etc.) can retrieve and cite information from PDFs, Word documents, and spreadsheets.
- **Outcome:** Instant, citation-backed answers from company knowledge without touching source systems directly.

### 2. Automated Document Retrieval and RAG
- **Problem:** LLMs lack access to internal, proprietary knowledge and hallucinate when asked about it.
- **Solution:** The server retrieves the most relevant document chunks and assembles a citation-tagged context block ready to drop into any LLM prompt.
- **Outcome:** Accurate, grounded responses with precise citations pointing to pages, headings, or spreadsheet sheets.

### 3. Scalable Multi-Source Knowledge Indexing
- **Problem:** Enterprise knowledge is scattered across SharePoint, Confluence, Notion, Google Drive, Slack, and local file systems.
- **Solution:** A modular connector architecture — each new data source is one class implementing two methods; nothing downstream changes.
- **Outcome:** A single unified knowledge index across all enterprise sources, searchable via natural language.

---

## Description

The Enterprise Knowledge MCP Server bridges the gap between enterprise document repositories and AI assistants. It uses FastMCP to expose ingestion, semantic search, and RAG context assembly as standardized tools, so any MCP-compatible client gets read-only, citation-backed access without touching source systems.

This application enables users to:
- Index PDF, DOCX, and XLSX files locally — no document text leaves the machine.
- Perform semantic search with metadata filters (source type, department, author).
- Retrieve citation-tagged RAG context blocks ready for any LLM prompt.
- Extend to new data sources (SharePoint, Confluence, Notion, Google Drive, Slack) by writing one connector class.

Built with FastMCP, ChromaDB, and sentence-transformers, the system is fully local, modular, and production-leaning.

---

## Features

| Feature | Description |
|---------|-------------|
| Semantic Search | Cosine-similarity vector search over all indexed chunks |
| RAG Context Assembly | Returns citation-tagged context blocks (`[1]`, `[2]`, ...) with source lists |
| Local Embeddings | sentence-transformers — no external embedding API calls, no data leaves the machine |
| Schema-Aware Extraction | PDF pages, DOCX headings and tables, XLSX sheets each become citable sections |
| Metadata Filtering | Filter by `source_type`, `department`, `author` at query time |
| Modular Connectors | One class implements `BaseConnector` to add any new data source |
| Safe Read-Only Access | MCP tools never write to source systems |
| Configurable | Full environment-variable configuration via `.env` |
| Tested | Includes basic test structure |

---

## Architecture

```
[MCP Client — Claude Desktop, etc.]
        |
    (stdio / MCP protocol)
        |
[server.py — FastMCP tools]
        |
[rag/retriever.py — KnowledgeService]
        |
   ┌────┴────┐
   |         |
[ingestion]  [storage/vector_store.py — ChromaDB]
   |
   ├── extractor.py   (PDF pages / DOCX headings+tables / XLSX sheets)
   ├── chunker.py     (sentence-packed overlapping chunks)
   └── embedder.py    (sentence-transformers, local)
        |
[connectors/]
   └── local_files.py  (PDF / DOCX / XLSX — implemented)
   └── ...             (SharePoint / Confluence / Notion / Drive / Slack — roadmap)
```

---

## Project Structure

```
enterprise-knowledge-mcp/
├── data/
│   ├── raw/                         # drop source files here
│   └── chroma/                      # Chroma persistent index (auto-created)
├── src/
│   ├── server.py                    # MCP server entry point (FastMCP tools)
│   ├── config.py                    # centralised env-var configuration
│   ├── connectors/
│   │   ├── base.py                  # BaseConnector ABC + SourceDocument dataclass
│   │   └── local_files.py           # local PDF/DOCX/XLSX connector (implemented)
│   ├── ingestion/
│   │   ├── extractor.py             # text extraction per mime type
│   │   ├── chunker.py               # sentence-boundary chunker with overlap
│   │   └── embedder.py              # sentence-transformers wrapper
│   ├── rag/
│   │   └── retriever.py             # KnowledgeService: ingest + search + RAG context
│   └── storage/
│       └── vector_store.py          # Chroma vector store wrapper
├── Screenshots/
│   └── logo.jpg
├── .env.example                     # copy to .env and configure
├── .gitignore
├── requirements.txt
└── README.md
```

---

## Getting Started

### Prerequisites
- Python 3.10+
- pip
### Quick Setup (Recommended)

```bash
git clone <repository-url>
cd enterprise-knowledge-mcp

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env if you need non-default paths or a different embedding model
```

### Manual Setup

```bash
# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env as needed (all values have sensible defaults)
```

### Running the Server

```bash
python src/server.py
```

The server runs over **stdio** — the standard transport for local MCP clients.

### Claude Desktop Configuration

Add this block to `claude_desktop_config.json`:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "enterprise-knowledge": {
      "command": "python",
      "args": ["/absolute/path/to/enterprise-knowledge-mcp/src/server.py"]
    }
  }
}
```

Replace `/absolute/path/to/` with the real path on your machine.

---

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `EKM_RAW_DIR` | No | `./data/raw` | Directory the local connector scans for source files |
| `EKM_CHROMA_DIR` | No | `./data/chroma` | Directory where the Chroma persistent index is stored |
| `EKM_COLLECTION` | No | `enterprise_knowledge` | Chroma collection name |
| `EKM_CHUNK_SIZE` | No | `800` | Max chunk size in characters |
| `EKM_CHUNK_OVERLAP` | No | `120` | Overlap in characters carried between chunks |
| `EKM_EMBEDDING_MODEL` | No | `all-MiniLM-L6-v2` | sentence-transformers model — runs locally, no API key needed |
| `EKM_TOP_K` | No | `5` | Default number of results returned by search and RAG tools |

---

## Usage

1. Drop PDF, DOCX, or XLSX files into `data/raw/`.
2. Connect an MCP client (e.g. Claude Desktop) to the server.
3. Use the `ingest_local_directory` tool to index documents.
4. Ask natural language questions — the client will call `search_knowledge` or `get_rag_context` automatically.

**Programmatic ingest example:**

```python
import sys; sys.path.insert(0, "src")

from connectors.local_files import LocalFileConnector
from rag.retriever import KnowledgeService

svc = KnowledgeService()
result = svc.ingest_connector(LocalFileConnector(root_dir="data/raw"))
print(result)
# {"documents_indexed": N, "chunks_indexed": M, "errors": [...]}
```

### MCP Tools

| Tool | Arguments | Description |
|------|-----------|-------------|
| `ingest_local_directory` | `directory?` (str) | Scan and index all PDF/DOCX/XLSX files from a directory. Defaults to `EKM_RAW_DIR`. Re-ingesting a document replaces its previous chunks. |
| `search_knowledge` | `query` (str), `top_k?` (int), `source_type?` (str), `department?` (str), `author?` (str) | Semantic search with optional metadata filters. Returns ranked chunks with score, title, section, and path. |
| `get_rag_context` | `query` (str), `top_k?` (int), `source_type?` (str), `department?` (str) | Retrieved chunks with inline citation markers `[1]`, `[2]`, ... and a matching source list — ready to paste into an LLM prompt. |
| `list_indexed_documents` | — | All documents currently in the index with their chunk counts. |
| `index_stats` | — | Total indexed chunk count. |

---

## Dependencies

| Package | Purpose |
|---------|---------|
| `mcp>=1.28,<2` | FastMCP server framework (v1 decorator API) |
| `chromadb` | Persistent vector store with cosine similarity search |
| `sentence-transformers` | Local embedding model — no external API calls |
| `pypdf` | PDF text extraction (page-by-page) |
| `python-docx` | DOCX text and table extraction |
| `openpyxl` | XLSX sheet extraction |
| `pydantic` | Data validation and settings |

---

## Testing

```bash
# From the repo root with venv activated
pytest -v
```

---

## Connector Roadmap

| Priority | Source | Notes |
|----------|--------|-------|
| Done | **Local files** (PDF, DOCX, XLSX) | `connectors/local_files.py` |
| 2 | **SharePoint** | Microsoft Graph API, delta queries, app-only client credentials auth |
| 3 | **Confluence** | REST API v2, CQL incremental sync, API token auth |
| 4 | **Notion** | `/v1/search` + block children pagination, integration token auth |
| 5 | **Google Drive** | Drive API v3, service account or OAuth, export Docs/Sheets as text |
| 6 | **Slack** | `conversations.history` + file downloads, bot token, channel-level ACLs |

---

<h1>License</h1>

Copyright (c) 2026 Intuz Solutions Pvt Ltd.
<br><br>
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:
<br><br>
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.

<h1></h1>
<a href="https://www.intuz.com">
<img src="./Screenshots/logo.jpg" alt="Intuz Logo">
</a>