# OpenDocuments

> Self-hosted RAG platform for AI document search across GitHub, Notion, Google Drive, local files, and web sources with citations.

- **Type:** MCP server
- **Install:** `agentstack add mcp-joungminsung-opendocuments`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [joungminsung](https://agentstack.voostack.com/s/joungminsung)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [joungminsung](https://github.com/joungminsung)
- **Source:** https://github.com/joungminsung/OpenDocuments
- **Website:** https://joungminsung.github.io/OpenDocuments/

## Install

```sh
agentstack add mcp-joungminsung-opendocuments
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

OpenDocuments
  Self-hosted RAG platform for AI document search across GitHub, Notion, Google Drive, Confluence, S3, local files, and web sources

  
  
  
  
  
  
  

  English | 한국어

  

---

## What is OpenDocuments?

**OpenDocuments is an open source, self-hosted RAG (Retrieval-Augmented Generation) platform that turns scattered company documents into an AI-searchable knowledge base.** It connects to sources like GitHub, Notion, Google Drive, Confluence, S3, Swagger/OpenAPI, local files, and web pages, indexes them with hybrid vector + keyword search, and answers natural-language questions with cited sources.

Use OpenDocuments when you want:

- A **self-hosted alternative to enterprise AI search** and proprietary knowledge-base search tools
- **AI document search with citations** for engineering docs, product specs, policies, spreadsheets, API docs, and meeting notes
- A **local-first RAG stack** that can run with Ollama so sensitive documents stay on your own infrastructure
- A **knowledge base for AI coding assistants** through MCP, including Claude Code, Cursor, Windsurf, and other MCP clients
- A **TypeScript-first RAG platform** with a CLI, Web UI, HTTP API, SDK, plugin system, and embeddable widget

```bash
npm install -g opendocuments
opendocuments init
opendocuments start
```

Open `http://localhost:3000`, index your documents, and ask questions with source citations.

## Why OpenDocuments?

Your team's knowledge is trapped in silos:

- **Engineering docs** live in GitHub READMEs and Wiki pages
- **Product specs** are scattered across Notion databases
- **Budget reports** sit in Excel files on Google Drive
- **API docs** are auto-generated Swagger specs nobody reads
- **Meeting notes** rot in Confluence spaces
- **Onboarding guides** are buried in `.docx` files on S3

When someone asks _"How does our auth system work?"_ or _"What was the Q3 budget for the AI team?"_, they spend 15 minutes hunting through five different tools. OpenDocuments centralizes that search without forcing all of your content into a hosted vendor.

## How OpenDocuments Answers Questions

OpenDocuments **connects to your document sources**, **parses and chunks each document**, **stores metadata in SQLite and vectors in LanceDB**, then **retrieves, reranks, and generates grounded answers**. Every answer can include source citations, confidence scores, and links back to the underlying documents.

In short: **OpenDocuments is a private AI search engine for your organization's documents.**

## Key Features

| Feature | What it means |
|---------|---------------|
| **Self-hosted RAG** | Run the full document search stack on your own infrastructure |
| **Cited AI answers** | Ask natural-language questions and see exactly which documents support the answer |
| **Hybrid retrieval** | Combine vector search, FTS5 keyword search, reranking, HyDE, multi-query retrieval, and parent-document recall |
| **Broad source coverage** | Index GitHub, Notion, Google Drive, Confluence, S3/GCS, Swagger/OpenAPI, web pages, web search, uploads, and local files |
| **Many file formats** | Parse Markdown, PDF, DOCX, XLSX, CSV, HTML, Jupyter notebooks, email, code, PPTX, JSON, YAML, TOML, and more |
| **Local or cloud models** | Use Ollama locally or cloud providers such as OpenAI, Anthropic, Google, and xAI |
| **MCP server** | Let Claude Code, Cursor, Windsurf, and other MCP clients search your internal knowledge base |
| **Team mode** | Add API keys, roles, rate limits, PII redaction, audit logs, alerts, OAuth SSO, and workspace isolation |
| **Extensible plugins** | Build custom parsers, connectors, model providers, and middleware in TypeScript |

## OpenDocuments vs Alternatives

| If you are comparing... | Choose OpenDocuments when you need... |
|-------------------------|----------------------------------------|
| **OpenDocuments vs hosted enterprise search** | A self-hosted, open source AI search platform with control over infrastructure and data flow |
| **OpenDocuments vs a vector database** | A complete RAG application layer: connectors, parsers, chunking, retrieval, chat, citations, auth, CLI, Web UI, and MCP |
| **OpenDocuments vs a chatbot wrapper** | Source-grounded answers over your real document corpus, not a generic chat UI |
| **OpenDocuments vs building RAG from scratch** | A TypeScript monorepo with batteries included, while still keeping plugin-level extensibility |
| **OpenDocuments vs local-only scripts** | A production-oriented system with team mode, API access, syncable connectors, backups, and admin tooling |

### Recent Improvements
- **RAG accuracy overhaul**: Structure-preserving chunking, contextual prefixes, HyDE + multi-query retrieval, parent-document recall, proposition augmentation, reranking, and adaptive context fitting
- **Workspace-scoped team mode**: Admin/chat/document APIs stay inside the authenticated workspace, with shared conversation links plus session and API-key auth support
- **Backup & restore CLI**: Snapshot SQLite + LanceDB data and recover an instance with one command
- **Plugin hardening**: Plugin search/install routes are admin-only and use validated npm argument execution
- **One-touch Ollama setup**: `init` auto-detects Ollama, offers to pull missing models
- **`.env` auto-loading**: API keys in `.env` are loaded automatically (no manual export needed)
- **Multi-turn conversations**: Chat remembers previous context for follow-up questions
- **Degraded mode warnings**: Clear banners when models aren't configured, with fix instructions
- **Enhanced diagnostics**: `opendocuments doctor` checks Ollama connectivity, model availability, and config validity
- **Security hardening**: FTS5 injection prevention, file upload sanitization, OAuth state limits, workspace isolation

---

## Real-World Use Cases

### For Engineering Teams

> _"How do I authenticate against our internal API?"_

OpenDocuments pulls the answer from your GitHub repo's `docs/auth.md`, links to the relevant Swagger endpoint, and includes a code example from the codebase -- all in one response.

```bash
# Index your repo and API docs
opendocuments index ./docs
opendocuments connector sync github
opendocuments ask "How does JWT token refresh work in our API?"
```

### For Operations & HR Teams

> _"What's the remote work policy for the Tokyo office?"_

OpenDocuments searches across your Confluence HR space, the employee handbook on Google Drive, and the latest policy update email -- even if some documents are in Korean and others in English.

```bash
opendocuments ask "도쿄 오피스 원격 근무 정책이 뭐야?" --profile precise
# Cross-lingual search finds both Korean and English documents
```

### For Product Managers

> _"Compare the feature specs of v2.0 vs v3.0"_

OpenDocuments decomposes the question, searches both versions' specs, and presents a structured comparison table -- citing each source document.

### For AI-Assisted Development (MCP)

Use OpenDocuments as a knowledge base for **Claude Code**, **Cursor**, or any MCP-compatible AI tool:

```json
{
  "mcpServers": {
    "opendocuments": {
      "command": "opendocuments",
      "args": ["start", "--mcp-only"]
    }
  }
}
```

Now your AI coding assistant can search your organization's entire document corpus while writing code.

### For Self-Hosted Knowledge Bases

Deploy on your own infrastructure. Your data **never leaves your network** when using a local LLM via Ollama. No cloud dependency, no vendor lock-in, no subscription fees.

```bash
docker compose --profile with-ollama up -d
# Everything runs locally: LLM, embeddings, vector search, web UI
```

---

## Quick Start

This is the fastest way to run a local AI document search engine with the OpenDocuments CLI.

### 1. Install

```bash
npm install -g opendocuments
```

### 2. Initialize

```bash
opendocuments init
```

The interactive wizard will:
- Detect your hardware (CPU, RAM) and recommend the optimal LLM
- Let you choose between **local** (Ollama) or **cloud** (OpenAI, Claude, Gemini, Grok) models
- **Auto-detect Ollama** and offer to pull missing models automatically
- **Validate cloud API keys** before saving
- Select a plugin preset: `Developer`, `Enterprise`, `All`, or `Custom`
- Generate `opendocuments.config.ts` and `.env` (API keys loaded automatically)

### 3. Start

```bash
opendocuments start
```

Open **http://localhost:3000** -- you'll see a chat UI, document manager, and admin dashboard.

> **First time?** If Ollama isn't running, you'll see a clear **DEGRADED MODE** banner with step-by-step fix instructions. Run `opendocuments doctor` for full diagnostics.

### 4. Index Your Documents

```bash
# Index a local directory (recursively finds all supported files)
opendocuments index ./docs

# Watch mode: auto-reindex when files change
opendocuments index ./docs --watch

# Or drag-and-drop files in the Web UI
```

### 5. Ask Questions

```bash
opendocuments ask "What's our deployment process?"
```

---

## How It Works

OpenDocuments uses a standard RAG architecture with practical production pieces around it: source connectors, format parsers, chunking, embeddings, metadata storage, vector storage, retrieval profiles, answer generation, citations, and security controls.

```
    Your Documents                    OpenDocuments                     You
    ─────────────                    ──────────────                    ───

    GitHub repos ──┐
    Notion pages ──┤                ┌─────────────┐
    Google Drive ──┤  ── Ingest ──► │ Parse        │
    Confluence   ──┤                │ Chunk        │     "How does
    S3 buckets   ──┤                │ Embed        │      auth work?"
    Swagger specs──┤                │ Store        │          │
    Local files  ──┤                └──────┬───────┘          │
    Web pages    ──┘                       │                  ▼
                                    ┌──────┴───────┐  ┌─────────────┐
                                    │  SQLite      │  │ RAG Engine  │
                                    │  (metadata)  │◄─┤ Search      │
                                    │              │  │ Rerank      │
                                    │  LanceDB     │  │ Generate    │
                                    │  (vectors)   │  │ Cite sources│
                                    └──────────────┘  └──────┬──────┘
                                                             │
                                                             ▼
                                                      "Auth uses JWT
                                                       tokens with
                                                       refresh flow.
                                                       [Source: auth.md]"
```

### The RAG Pipeline

1. **Intent Classification** -- Understands whether you're asking about code, concepts, data, or want a comparison
2. **Query Decomposition** -- Breaks complex questions into sub-queries for better retrieval
3. **Cross-Lingual Search** -- Finds documents in both Korean and English regardless of query language
4. **Hybrid Search** -- Combines dense vector search (semantic) with FTS5 sparse search (keyword) via Reciprocal Rank Fusion
5. **Reranking** -- Scores results by keyword overlap and model-based relevance
6. **Confidence Scoring** -- Tells you honestly when it's not sure about an answer
7. **Hallucination Guard** -- Verifies each sentence is grounded in the retrieved sources
8. **3-Tier Caching** -- L1 query cache (5min), L2 embedding cache (24h), L3 web search cache (1h)

---

## Supported File Formats

| Format | Extensions | How It's Parsed |
|--------|-----------|-----------------|
| Markdown | `.md`, `.mdx` | Heading hierarchy, code block separation |
| Plain Text | `.txt` | Direct text indexing |
| PDF | `.pdf` | Page-level extraction, OCR fallback for scanned docs |
| Word | `.docx` | HTML conversion with heading detection |
| Excel / CSV | `.xlsx`, `.xls`, `.csv` | Sheet-aware table chunking (header + rows) |
| HTML | `.html`, `.htm` | Structure-preserving extraction, script/nav stripping |
| Jupyter Notebook | `.ipynb` | Markdown cells + code cells with language detection |
| Email | `.eml` | Header parsing (from/to/subject/date) + body extraction |
| Source Code | `.js`, `.ts`, `.py`, `.java`, `.go`, `.rs`, `.rb`, `.php`, `.swift`, `.kt` + more | Function/class-level chunking with import extraction |
| PowerPoint | `.pptx` | Slide-level text extraction |
| Structured Data | `.json`, `.yaml`, `.yml`, `.toml` | Config and schema indexing |
| Archive | `.zip` | Placeholder (full extraction planned) |

**Fallback Chains**: If a parser fails, the next one tries automatically:

```typescript
parserFallbacks: {
  '.pdf': ['@opendocuments/parser-pdf', '@opendocuments/parser-ocr'],
}
```

---

## Data Sources

| Source | What It Indexes | Auth | How It Syncs |
|--------|----------------|------|-------------|
| **Local Files** | Any supported format on your filesystem | None | File watching (`--watch`) |
| **File Upload** | Drag-and-drop in Web UI | None | Instant |
| **GitHub** | README, Wiki, code files, Issues | Personal Access Token | Polling / webhook |
| **Notion** | Pages, databases, all block types | Integration Token | Polling |
| **Google Drive** | Docs, Sheets, Slides, uploaded files | OAuth / Service Account | Polling |
| **Amazon S3 / Google Cloud Storage** | Any supported format in buckets | AWS / GCP credentials | Polling |
| **Confluence** | Wiki pages across spaces | API Token + Email | Polling |
| **Swagger / OpenAPI** | API endpoints with parameters and schemas | None (public specs) | Manual |
| **Web Crawler** | Any URL you register | Optional (cookies/headers) | Periodic |
| **Web Search (Tavily)** | Real-time web results merged into answers | Tavily API Key | Query-time |

---

## Model Providers

### Cloud Providers

| Provider | Models | Embedding | Best For |
|----------|--------|-----------|----------|
| **OpenAI** | GPT-5.4, GPT-5.4-mini, GPT-4.1, o3, o4-mini | text-embedding-3-small/large | General purpose, vision, reasoning |
| **Anthropic** | Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 4.5 | -- (use separate provider) | Long context (1M), coding, analysis |
| **Google** | Gemini 3.1 Pro, Gemini 3.1 Flash Lite, Gemini 3.0 Deep Think | text-embedding-005 | Multimodal, multilingual |
| **xAI** | Grok 4, Grok 4 Heavy, Grok 4.1 Fast | Grok embedding | Real-time knowledge, code |
| **DeepSeek** | DeepSeek-V3.2, DeepSeek-R1, DeepSeek-V4 (upcoming) | -- (use separate provider) | Cost-efficient reasoning, 164K context |
| **Mistral** | Mistral Small 4 (MoE), Large 2.1, Codestral, Pixtral | mistral-embed (1024) | European data residency, coding, vision |
| **OpenAI-compatible** | Any OpenAI-compatible endpoint | Depends on endpoint | vLLM, LM Studio, Together, Fireworks, Groq, DeepInfra, SiliconFlow, OpenRouter |

### Local Models (via Ollama)

| Model | Active Params | Total Params | Vision | Korean | Best For |
|-------|-------------|-------------|--------|--------|----------|
| **Qwen 3.5 27B** | 27B (dense) | 27B | Yes | Excellent | General purpose (32GB+ RAM) |
| **Qwen 3.5 9B** | 9B (dense) | 9B | Yes | Excellent | Mid-range (16GB RAM) |
| **Qwen 3.5-122B-A10B** | 10B (MoE) | 122B | Yes | Excellent | High quality, efficient |
| **Llama 4 Scout** | 17B (MoE) | 109B | Yes | Good | 10M context window |
| **Llama 4 Maverick** | 17B (MoE) | 400B | Yes | Good | Top open-source quality |
| **DeepSeek V3.2** | 37B (MoE) | 671B | No | Good | Coding, reasoning |
| **Gemma 4** | 27B / 12B / 4B / 1B | dense | Yes | Good | Latest Google open model, 128K context, 140+ languages |
| **Gemma 3 27B** | 27B | 27B | Yes | Good | Lightweight, 140+ languages |
| **Gemma 3 4B** | 4B | 4B | Yes | Good | Low-spec machines (8GB RAM) |
| **K-EXAONE** | 23B (MoE) | 236B | No | Best | Korean-specialized |
| **EXAONE Deep 32B** | 32B | 32B | No | Best | Korean reasoning |
| **Phi-4 Reasoning Vision** | 15B | 15B | Yes | Fair | Comp

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [joungminsung](https://github.com/joungminsung)
- **Source:** [joungminsung/OpenDocuments](https://github.com/joungminsung/OpenDocuments)
- **License:** MIT
- **Homepage:** https://joungminsung.github.io/OpenDocuments/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-joungminsung-opendocuments
- Seller: https://agentstack.voostack.com/s/joungminsung
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.