I’ll never forget the moment I realized my AI assistant was completely useless without an internet connection. I was on a flight, trying to work on a project that needed some quick Wikipedia lookups, and suddenly my supposedly “intelligent” assistant became as helpful as a brick. That’s when I started thinking: what if AI assistants could access knowledge offline?
The Offline Problem
We’ve become so accustomed to always-on internet that we forget how fragile that assumption is. Whether you’re:
- Flying across oceans with spotty or expensive wifi
- Working in remote locations with unreliable connectivity
- Developing in security-conscious environments where internet access is restricted
- Building applications for emerging markets where data costs matter
- Simply wanting independence from internet infrastructure
The reality is that some of our most valuable knowledge—Wikipedia, educational content, reference materials—could be available offline if we just had the right tools.
Enter OpenZIM: Knowledge in a Box
The OpenZIM format is like having a compressed, searchable library in a single file. Originally developed for the Kiwix project to bring Wikipedia to areas with limited internet access, ZIM files contain entire websites optimized for offline browsing.
Think about it: the entire English Wikipedia, with all its articles, images, and cross-references, compressed into a file you can carry on a USB stick. That’s the power of the ZIM format.
What Makes ZIM Special
- Massive compression: Entire Wikipedia in under 100GB (text-only versions much smaller)
- Fast random access: No need to decompress everything to find one article
- Rich metadata: Full-text search indices, category information, cross-references
- Standardized format: Works across different platforms and applications
What is the Model Context Protocol?
Before diving into the technical details, let me explain MCP in the context of offline knowledge access. The Model Context Protocol provides a standardized way for AI models to access external resources safely and efficiently. Instead of each AI tool implementing its own knowledge access methods, MCP creates a consistent interface.
For offline knowledge, this means your AI assistant can search through Wikipedia, access educational content, or browse reference materials—all without touching the internet.
Building the OpenZIM MCP Server
The Performance Challenge
Here’s the challenge that kept me up late: ZIM files contain compressed Wikipedia content, and you need to search through millions of articles without decompressing everything. It’s like trying to find a specific book in a library where all the books are in sealed boxes.
The solution? Build a smart indexing system that knows what’s in each “box” without opening them all.
use zim::Zim;
use tantivy::{Index, schema::*, collector::TopDocs};
pub struct ZimResourceProvider {
zim: Zim,
search_index: Index,
title_field: Field,
content_field: Field,
url_field: Field,
}
impl ZimResourceProvider {
pub async fn search(&self, query: &str, limit: usize) -> Result<Vec<SearchResult>, Error> {
let reader = self.search_index.reader()?;
let searcher = reader.searcher();
let query_parser = QueryParser::for_index(&self.search_index, vec![
self.title_field,
self.content_field
]);
let query = query_parser.parse_query(query)?;
let top_docs = searcher.search(&query, &TopDocs::with_limit(limit))?;
let mut results = Vec::new();
for (_score, doc_address) in top_docs {
let retrieved_doc = searcher.doc(doc_address)?;
results.push(self.doc_to_search_result(retrieved_doc)?);
}
Ok(results)
}
}
Performance Optimizations That Actually Matter
Building openzim-mcp taught me several crucial performance lessons:
1. Lazy Loading Everything
Don’t load what you don’t need. ZIM entries are loaded on demand:
pub struct LazyZimEntry {
zim: Arc<Zim>,
entry_index: u32,
cached_content: Option<Vec<u8>>,
}
impl LazyZimEntry {
pub async fn content(&mut self) -> Result<&[u8], Error> {
if self.cached_content.is_none() {
let entry = self.zim.get_entry_by_index(self.entry_index)?;
self.cached_content = Some(entry.get_content()?);
}
Ok(self.cached_content.as_ref().unwrap())
}
}
2. Full-Text Search with Tantivy
Tantivy turned out to be perfect for this use case—fast indexing and lightning-quick searches:
use tantivy::*;
pub fn build_search_index(zim: &Zim) -> Result<Index, Error> {
let mut schema_builder = Schema::builder();
let title_field = schema_builder.add_text_field("title", TEXT | STORED);
let content_field = schema_builder.add_text_field("content", TEXT);
let url_field = schema_builder.add_text_field("url", STORED);
let schema = schema_builder.build();
let index = Index::create_in_ram(schema);
let mut index_writer = index.writer(50_000_000)?; // 50MB buffer
for entry in zim.iter_entries() {
if entry.is_article() {
let mut doc = Document::new();
doc.add_text(title_field, &entry.get_title());
doc.add_text(content_field, &entry.get_text_content()?);
doc.add_text(url_field, &entry.get_url());
index_writer.add_document(doc)?;
}
}
index_writer.commit()?;
Ok(index)
}
3. Memory Mapping for the Win
Let the OS handle caching with memory-mapped files. Sometimes the OS really is smarter than you:
use memmap2::Mmap;
pub struct MmapZimFile {
mmap: Mmap,
zim: Zim,
}
impl MmapZimFile {
pub fn open(path: &Path) -> Result<Self, Error> {
let file = File::open(path)?;
let mmap = unsafe { Mmap::map(&file)? };
let zim = Zim::from_bytes(&mmap)?;
Ok(Self { mmap, zim })
}
}
Practical Offline Workflows
Research and Development
Here’s how I use the OpenZIM MCP server in my daily workflow:
# AI assistant searching offline Wikipedia
> Search the local Wikipedia for "distributed systems consensus algorithms"
# AI assistant accessing educational content
> Find articles about "rust programming language memory safety" in the offline knowledge base
# AI assistant browsing without internet
> Look up "HTTP/3 protocol specifications" in the local technical documentation
The AI gets comprehensive, reliable information without needing internet access.
Educational Scenarios
The offline capabilities shine in educational contexts:
- Classroom environments where internet is restricted or unreliable
- Field research where connectivity isn’t available
- Developing regions where data costs are prohibitive
- Security-sensitive environments where external connections aren’t allowed
Development in Low-Connectivity Environments
When building applications in environments with poor connectivity, having offline access to documentation and reference materials is invaluable:
// Example: AI assistant helping with offline development
pub async fn get_documentation(&self, topic: &str) -> Result<String, Error> {
let search_results = self.zim_provider.search(topic, 5).await?;
let mut documentation = String::new();
for result in search_results {
let content = self.zim_provider.get_article_content(&result.url).await?;
documentation.push_str(&format!("## {}\n\n{}\n\n", result.title, content));
}
Ok(documentation)
}
Architecture Patterns for Offline Data Access
Resource-Centric Design
The key insight for offline MCP servers is separating data access from data processing:
#[derive(Debug, Clone)]
pub struct OfflineResource {
pub uri: String,
pub title: String,
pub description: Option<String>,
pub content_type: String,
pub size: Option<u64>,
}
pub trait OfflineResourceProvider {
async fn search_resources(&self, query: &str) -> Result<Vec<OfflineResource>, Error>;
async fn get_resource_content(&self, uri: &str) -> Result<Vec<u8>, Error>;
async fn get_resource_metadata(&self, uri: &str) -> Result<ResourceMetadata, Error>;
}
This pattern lets you swap out different offline data sources—ZIM files, local databases, cached web content—without changing the MCP interface.
Caching Strategy
For offline systems, intelligent caching is crucial:
use lru::LruCache;
use tokio::sync::Mutex;
pub struct SmartCache {
content_cache: Mutex<LruCache<String, Vec<u8>>>,
metadata_cache: Mutex<LruCache<String, ResourceMetadata>>,
search_cache: Mutex<LruCache<String, Vec<SearchResult>>>,
}
impl SmartCache {
pub async fn get_or_fetch<F, Fut>(&self, key: &str, fetcher: F) -> Result<Vec<u8>, Error>
where
F: FnOnce() -> Fut,
Fut: Future<Output = Result<Vec<u8>, Error>>,
{
// Check cache first
{
let mut cache = self.content_cache.lock().await;
if let Some(content) = cache.get(key) {
return Ok(content.clone());
}
}
// Fetch and cache
let content = fetcher().await?;
let mut cache = self.content_cache.lock().await;
cache.put(key.to_string(), content.clone());
Ok(content)
}
}
Best Practices for Offline MCP Servers
Error Handling for Offline Scenarios
Offline systems have unique error conditions:
use thiserror::Error;
#[derive(Error, Debug)]
pub enum OfflineError {
#[error("ZIM file not found: {path}")]
ZimFileNotFound { path: String },
#[error("Search index corrupted or missing")]
SearchIndexCorrupted,
#[error("Article not found: {url}")]
ArticleNotFound { url: String },
#[error("ZIM file format error: {message}")]
FormatError { message: String },
#[error("Insufficient disk space for cache")]
InsufficientSpace,
}
Configuration for Offline Systems
Offline systems need different configuration considerations:
use serde::{Deserialize, Serialize};
#[derive(Debug, Deserialize, Serialize)]
pub struct OfflineConfig {
pub zim_file_path: String,
pub cache_size_mb: usize,
pub search_index_path: Option<String>,
pub max_search_results: usize,
pub enable_full_text_search: bool,
}
impl Default for OfflineConfig {
fn default() -> Self {
Self {
zim_file_path: "./wikipedia.zim".to_string(),
cache_size_mb: 512, // 512MB cache
search_index_path: None, // Auto-generate
max_search_results: 50,
enable_full_text_search: true,
}
}
}
Testing Offline Systems
Testing offline systems requires different strategies:
#[cfg(test)]
mod tests {
use super::*;
use tempfile::TempDir;
#[tokio::test]
async fn test_offline_search() {
let temp_dir = TempDir::new().unwrap();
let provider = create_test_zim_provider(temp_dir.path()).await;
let results = provider.search("rust programming", 10).await.unwrap();
assert!(!results.is_empty());
assert!(results.len() <= 10);
}
#[tokio::test]
async fn test_cache_behavior() {
let provider = create_cached_provider().await;
// First access - should hit ZIM file
let start = std::time::Instant::now();
let content1 = provider.get_content("A/Rust").await.unwrap();
let first_duration = start.elapsed();
// Second access - should hit cache
let start = std::time::Instant::now();
let content2 = provider.get_content("A/Rust").await.unwrap();
let second_duration = start.elapsed();
assert_eq!(content1, content2);
assert!(second_duration < first_duration);
}
}
The Future of Offline AI
Building openzim-mcp opened my eyes to the potential of offline AI systems. We’re moving toward a world where AI assistants can be truly independent—not just smart when connected, but genuinely useful even when the internet isn’t available.
Some exciting directions I’m exploring:
- Hybrid online/offline systems: Seamlessly switching between online and offline knowledge sources
- Incremental updates: Efficiently updating offline knowledge bases with new information
- Specialized knowledge domains: Creating ZIM files for specific technical domains or industries
- Collaborative offline networks: Sharing knowledge bases across local networks without internet
Getting Started with Offline Knowledge
Want to try the OpenZIM MCP server yourself? Here’s how to get started:
# Install the server
cargo install openzim-mcp
# Download a ZIM file (example: Simple English Wikipedia)
wget https://download.kiwix.org/zim/wikipedia/wikipedia_en_simple_all.zim
# Configure your AI assistant to use the offline knowledge base
# (specific steps depend on your MCP client)
# Start exploring offline knowledge
# Try searching for topics you're interested in
The offline knowledge ecosystem is rich and growing. You’ll find ZIM files for Wikipedia in dozens of languages, educational content, technical documentation, and specialized knowledge bases.
What I Learned
Building openzim-mcp taught me that offline doesn’t mean limited. In fact, having a curated, high-quality knowledge base can be more valuable than access to the entire chaotic internet. The speed, reliability, and focus of offline knowledge access often leads to better AI assistant interactions.
The technical challenges—efficient search, smart caching, memory management—pushed me to think differently about data access patterns. Sometimes constraints force you to build better systems.
Ready to explore offline AI? Check out the openzim-mcp repository for complete implementation details and examples.