Source Code to Knowledge Base Generator with MCP Server

Convert any source code repository into a searchable knowledge base with automatic chunking, embedding generation, and intelligent search capabilities. Now with MCP (Model Context Protocol) support for Claude Code and Cursor integration!
๐ฆ Now available on npm! Install with: npm install -g @vezlo/src-to-kb
Available Commands
After installation, you'll have access to these commands:
src-to-kb - Generate knowledge base from source code
src-to-kb-search - Search the knowledge base
src-to-kb-upload - Upload local knowledge base to external server
src-to-kb-api - Start REST API server with Swagger docs
src-to-kb-mcp - Start MCP server for IDE integration
src-to-kb-mcp-install - Auto-configure Claude Code/Cursor
Features
- ๐ Multi-language Support: JavaScript, TypeScript, Python, Java, C++, Go, Rust, and more
- ๐ Notion Integration: Import pages and databases directly from Notion (NEW!)
- ๐ฏ Answer Modes: Three modes for different users - End User (simple), Developer (technical), Copilot (code-focused)
- ๐ REST API: Full-featured API with Swagger documentation for integration with external services
- ๐ Smart Chunking: Intelligent code splitting with configurable overlap
- ๐งน Code Cleaning: Optional comment removal and whitespace normalization
- ๐ข Embeddings: Optional OpenAI embeddings for semantic search
- ๐ Statistics: Comprehensive analysis of your codebase
- ๐ Fast Processing: Efficient file scanning and processing
- ๐พ Structured Storage: Organized JSON output for easy integration
- ๐ค MCP Server: Direct integration with Claude Code, Cursor, and other MCP-compatible tools
- ๐ก AI-Powered Search: Uses OpenAI GPT-5 (latest reasoning model) for intelligent query understanding and helpful answers
- ๐ API Authentication: Optional API key authentication for secure access
- ๐ External Server Integration: Send code to external servers for processing and search via REST API
Quick Start
๐ For Existing Projects (Next.js, React, etc.)
# Install globally
npm install -g @vezlo/src-to-kb
# Generate KB from your project
src-to-kb ./my-nextjs-app --output ./my-kb
# Start API server
src-to-kb-api
# Search your codebase
src-to-kb-search search "How does routing work?" --mode developer
That's it! Your codebase is now searchable with AI assistance.
Processing Modes & Flags
The following table shows how flags work across different sources and modes:
| Source | Mode | Default (no flags) | --chunks-only | --with-embeddings |
|---|
| Codebase | Local | Creates chunks | Same (redundant) | Creates chunks + embeddings |
| Codebase | Server | Sends raw content | Creates chunks โ sends | Creates chunks + embeddings โ sends |
| Notion | Local | Creates chunks | Same (redundant) | Creates chunks + embeddings |
| Notion | Server | Sends raw content | Creates chunks โ sends | Creates chunks + embeddings โ sends |
Note: Server mode is enabled when EXTERNAL_KB_URL environment variable is set.
External Server Integration ๐
๐ Try It Now with Public Demo Server
Experience external server integration immediately with our production-ready assistant-server:
# Default: Send raw content (server creates chunks)
EXTERNAL_KB_URL=https://your-assistant-server.com/api/knowledge/items src-to-kb ./your-repo
# Create chunks locally, then send to server
EXTERNAL_KB_URL=https://your-assistant-server.com/api/knowledge/items src-to-kb ./your-repo --chunks-only
# Create chunks + embeddings locally, then send to server
EXTERNAL_KB_URL=https://your-assistant-server.com/api/knowledge/items OPENAI_API_KEY=sk-... src-to-kb ./your-repo --with-embeddings
# With API key authentication
EXTERNAL_KB_URL=https://your-assistant-server.com/api/knowledge/items EXTERNAL_KB_API_KEY=your-api-key src-to-kb ./your-repo
# Search using assistant-server
EXTERNAL_KB_URL=https://your-assistant-server.com/api/knowledge/items \
EXTERNAL_KB_SEARCH_URL=https://your-assistant-server.com/api/search \
src-to-kb-search search "how does authentication work?"
Assistant Server: vezlo/assistant-server - Production-ready Node.js/TypeScript API server with vector search and Docker deployment
๐ค Upload Local Knowledge Base
Upload an existing local knowledge base to an external server:
# Default: Upload raw content (reconstructs from chunks)
EXTERNAL_KB_URL=https://your-assistant-server.com/api/knowledge/items \
src-to-kb-upload --kb ./knowledge-base
# Upload chunks only (server generates embeddings)
EXTERNAL_KB_URL=https://your-assistant-server.com/api/knowledge/items \
src-to-kb-upload --kb ./knowledge-base --chunks-only
# Upload chunks with embeddings
EXTERNAL_KB_URL=https://your-assistant-server.com/api/knowledge/items \
src-to-kb-upload --kb ./knowledge-base --with-embeddings
Requirements:
EXTERNAL_KB_URL environment variable must be set
- Knowledge base must have
documents/ and chunks/ directories
- For
--with-embeddings: embeddings/ directory must exist
๐ข Enterprise Setup
For production deployments or custom servers:
๐ Complete Guide: External Server Setup Guide
Notion Integration ๐
NEW! Import your Notion pages and databases directly into your knowledge base! Perfect for combining documentation, project plans, and code knowledge in one searchable system.
Quick Start with Notion
# 1. Get your Notion API key (see full guide below)
export NOTION_API_KEY=secret_xxx
# 2. Generate KB from a Notion page
src-to-kb --source=notion --notion-url=https://notion.so/Your-Page-abc123
# 3. Or fetch all pages from a Notion database
src-to-kb --source=notion --notion-url=https://notion.so/Database-xyz789
# 4. Search your Notion content
src-to-kb-search search "your query" --kb ./knowledge-base/notion
With External Server
Send Notion content directly to your assistant-server:
# Set external server URL
export EXTERNAL_KB_URL=http://localhost:3002/api/knowledge/items
export EXTERNAL_KB_API_KEY=your-api-key
# Send raw content from Notion to server (default)
src-to-kb --source=notion --notion-url=https://notion.so/Your-Page-abc123
# Send chunks from Notion to server
src-to-kb --source=notion --notion-url=https://notion.so/Your-Page-abc123 --chunks-only
# Send chunks + embeddings from Notion to server
OPENAI_API_KEY=sk-... src-to-kb --source=notion --notion-url=https://notion.so/Your-Page-abc123 --with-embeddings
# Search via external server
export EXTERNAL_KB_URL=http://localhost:3002/api/knowledge/items
export EXTERNAL_KB_SEARCH_URL=http://localhost:3002/api/search
src-to-kb-search search "your query"
Features
- โ
Auto-detection: Automatically detects if URL is a page or database
- โ
Single Page: Fetch individual Notion pages
- โ
Database Support: Fetch all pages from a Notion database
- โ
Rich Content: Preserves formatting, headings, lists, code blocks, and more
- โ
Separate KB: Notion content saved to
./knowledge-base/notion by default
- โ
External Server: Send directly to assistant-server for production use
Examples
# Single page (local KB)
src-to-kb --source=notion --notion-url=https://notion.so/Project-Docs-abc123
# Database with all pages (local KB)
src-to-kb --source=notion --notion-url=https://notion.so/Team-Wiki-xyz789
# With API key as parameter
src-to-kb --source=notion --notion-key=secret_xxx --notion-url=https://notion.so/Page-abc123
# Send to external server (raw content by default)
EXTERNAL_KB_URL=http://localhost:3002/api/knowledge/items \
EXTERNAL_KB_API_KEY=your-key \
src-to-kb --source=notion --notion-url=https://notion.so/Page-abc123
# Search local Notion KB
src-to-kb-search search "project timeline" --kb ./knowledge-base/notion
# Search via external server
EXTERNAL_KB_URL=http://localhost:3002/api/knowledge/items \
EXTERNAL_KB_SEARCH_URL=http://localhost:3002/api/search \
src-to-kb-search search "project timeline"
๐ Complete Notion Guide: Notion Integration Documentation - Includes setup instructions, API key creation, sharing pages/databases, and troubleshooting
1. Basic Usage
Process your repository with default settings:
# If installed globally via npm
src-to-kb /path/to/your/repo
# Or using the script directly
node kb-generator.js /path/to/your/repo
2. With Custom Output Directory
src-to-kb /path/to/your/repo --output ./my-knowledge-base
3. With OpenAI Embeddings
# Set your OpenAI API key
export OPENAI_API_KEY=your-api-key-here
# Generate with embeddings
src-to-kb /path/to/your/repo --with-embeddings
4. Search with Answer Modes
Choose the right answer mode for your needs:
# First generate a knowledge base
src-to-kb ./your-project --output ./project-kb
# Search with different modes:
# End User Mode - Simple, non-technical answers
src-to-kb-search search "how do I reset password?" --kb ./project-kb --mode enduser
# Developer Mode - Technical details and architecture (default)
src-to-kb-search search "authentication flow" --kb ./project-kb --mode developer
# Copilot Mode - Code examples and implementation patterns
src-to-kb-search search "implement user login" --kb ./project-kb --mode copilot
# View available modes
src-to-kb-search modes
Answer Modes ๐ฏ