clarion-knowledge-base by peterparker57 - MCP Server

Clarion Knowledge Base - MCP Server

Semantic search for Clarion programming documentation via Claude AI

Instantly search across 21 Clarion documentation manuals using natural language queries in Claude Code or Claude Desktop. Powered by semantic search with 21,747 indexed documentation chunks.

Overview

Clarion Knowledge Base is a Model Context Protocol (MCP) server that brings the entire Clarion programming language documentation to your fingertips within Claude AI. Instead of manually searching through PDF manuals, simply ask Claude natural language questions about Clarion programming and get instant, relevant answers with source citations.

Why This Matters for Clarion Developers

Instant Documentation Access: Search 21 PDF manuals (Language Reference, ABC Library, Templates, IDE, etc.) in seconds
Natural Language Queries: Ask questions like "How do I create a browse?" instead of keyword searching
Works in Your Workflow: Integrates seamlessly with Claude Code and Claude Desktop
Always Available: Runs locally via Docker - no cloud dependency for documentation lookup
Semantic Understanding: Finds relevant content even if you don't know the exact terminology

Key Features

21,747 Indexed Chunks - Complete coverage of Clarion documentation
Semantic Search - Understands intent, not just keywords
MCP Protocol Integration - Native Claude Code and Claude Desktop support
Docker-Based - Simple deployment, no Python environment setup needed
Qdrant Vector Database - Fast, efficient similarity search
Source Citations - Every result includes document source and location
Filtered Search - Optionally search within specific documentation categories

Quick Install (2 Minutes)

The easiest way to install is using the Claude Code plugin system:

# Step 1: Add the marketplace
/plugin marketplace add https://github.com/peterparker57/clarion-knowledge-base.git

# Step 2: Install the plugin
/plugin install clarion-knowledge-base

# Step 3: Run the setup command (this downloads and configures everything)
/clarion-setup

Requirements: Docker Desktop must be installed and running.

The setup command will:

Download and configure Docker containers
Set up the Qdrant vector database (~76 MB)
Import 21,747 documentation chunks
Verify everything is working

After setup completes, restart Claude Code and you can use slash commands like /clarion-search or simply ask Claude questions about Clarion programming!

NEW: Standalone Web App (No Claude Required!)

Want to use the Clarion Knowledge Base without Claude? Use our standalone web application with your own LLM provider (DeepSeek, OpenAI, Claude, Gemini, Grok, or FREE local Ollama).

Quick Start (Pre-Built Docker Image):

# Create and enter a folder for Clarion KB
mkdir ~/clarion-kb
cd ~/clarion-kb

# Download deployment file
curl -O https://raw.githubusercontent.com/peterparker57/clarion-knowledge-base/main/docker-compose-public.yml

# Start the app (first time downloads ~12GB)
docker-compose -f docker-compose-public.yml up -d

# Open browser
open http://localhost:8080

That's it! No building, no Git clone - just pull and run from Docker Hub.

Important: Run all commands in the same folder (the clarion-kb folder you created).

Custom Port Configuration

Port 8080 already in use? No problem!

Option 1: Environment Variable (easiest)

CLARION_WEB_PORT=8081 docker-compose -f docker-compose-public.yml up -d
# Access at http://localhost:8081

Option 2: Edit the File Edit docker-compose-public.yml and change:

ports:
  - "8080:8080"  # Change first number: "8081:8080"

Common alternative ports: 8081, 8082, 3000, 5000, 9090

First Startup Time

⚠️ Important: On first startup, services may take 2-3 minutes to become healthy while:

Qdrant restores the 21,747 documentation chunks from snapshot (~90 seconds)
Web app loads the sentence transformer embedding model (~80MB)
Docker performs health checks to ensure services are ready

Be patient! The containers will start automatically once Qdrant is healthy.

Check startup progress:

docker-compose -f docker-compose-public.yml logs -f

Wait for: "Uvicorn running on http://0.0.0.0:8080" before accessing the web interface.

Features:

🌐 Browser-Based Interface - Access from any device
🔑 Multiple LLM Providers: DeepSeek ($0.35/1M), OpenAI, Claude, Gemini, Grok, or Ollama (FREE)
💰 Real-Time Pricing - See cost per model before you query
📊 3 Query Modes: Augmented (docs + AI), Strict (docs only), Chat (AI only - fast)
📱 Mobile Friendly - Works on phones/tablets
📚 Same Data: 21,747 documentation chunks as MCP mode
🎯 Source Citations - Every answer includes document sources

When to Use Each Mode:

Feature	MCP Mode	Web App
Best for	Claude Code/Desktop users	Everyone
LLM	Claude (Anthropic)	Any provider (your choice)
Interface	Claude chat	Web browser
Cost	Claude subscription	Pay-per-use or FREE (Ollama)
Mobile	❌ No	✅ Yes

📖 Full Documentation: See for complete instructions, LLM provider setup, and troubleshooting.

🐳 Docker Hub: clarionlive/clarion-knowledge-base-webapp

Alternative: Manual Installation (MCP Mode)

If you prefer manual installation or need more control, you can install via the installer scripts:

# Step 1: Clone the repository
git clone https://github.com/peterparker57/clarion-knowledge-base
cd clarion-knowledge-base

# Step 2: Run the installer
./install.sh      # Mac/Linux
# or
install.bat       # Windows

# Step 3: Restart Claude Code or Claude Desktop
# The Clarion Knowledge Base will now be available as an MCP server

What happens during installation:

Checks Docker is installed and running
Downloads pre-built vector database (~76 MB compressed)
Starts Docker containers (Qdrant + MCP server)
Configures Claude Code/Desktop automatically
Verifies the MCP server is working

Note: The installer will prompt you to choose Claude Code, Claude Desktop, or both.

See for detailed plugin documentation or for manual installation details.

Prerequisites

Before installation, ensure you have:

Docker Desktop - Download here
- Must be installed and running
- At least 2GB available disk space
Claude Code or Claude Desktop - Get Claude
- Either or both clients supported
Internet Connection - Required for initial database download (~76 MB)
System Requirements:
- Windows 10/11, macOS 10.15+, or Linux
- 4GB RAM minimum (8GB recommended)

Installation Details

Recommended: Use the plugin installation method described above (/plugin add peterparker57/clarion-knowledge-base).

The following sections are for manual configuration or troubleshooting.

For Claude Code

The installer (or plugin) automatically configures Claude Code, but if you need to configure manually:

Configuration File Locations:

Windows: %USERPROFILE%\.claude\claude_code_config.json
macOS: ~/.claude/claude_code_config.json
Linux: ~/.config/claude-code/config.json

Example Configuration:

{
  "mcpServers": {
    "clarion-knowledge-base": {
      "command": "docker",
      "args": ["exec", "-i", "clarion-mcp-server", "python", "/app/src/mcp_server.py"]
    }
  }
}

Verify Installation:

Restart Claude Code completely
Open a new chat or project
Type /mcp to see available servers
Look for "clarion-knowledge-base" in the list
Try a test query: "How do I define a QUEUE in Clarion?"

For Claude Desktop

The installer automatically configures Claude Desktop, but for manual configuration:

Configuration File Locations:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Example Configuration:

{
  "mcpServers": {
    "clarion-knowledge-base": {
      "command": "docker",
      "args": ["exec", "-i", "clarion-mcp-server", "python", "/app/src/mcp_server.py"]
    }
  }
}

Verify Installation:

Completely quit and restart Claude Desktop
Look for the tools icon (🔧) in the chat interface
Click to see available tools
"search_docs" from clarion-knowledge-base should appear
Try asking: "Explain the FILE driver in Clarion"

Usage Examples

Once installed, you can query Clarion documentation naturally within Claude:

Example Queries

Basic Language Questions:

"How do I create a browse in Clarion?"
"What's the syntax for a LOOP statement?"
"Explain the difference between GROUP and QUEUE"

Library and Component Questions:

"How do I use the ABC library for file handling?"
"What are the methods available in the BrowseClass?"
"Show me examples of the Internet Builder classes"

Template and IDE Questions:

"What are embed points in Clarion templates?"
"How do I create a custom template?"
"Explain the Application Generator options"

Database and Advanced Topics:

"How do I connect to a SQL database in Clarion?"
"What's the FILE driver architecture?"
"How do I implement XML processing?"

Example Output

When you ask a question, you'll receive:

# Search Results for: "How do I define a QUEUE in Clarion?"

**Found 5 relevant chunks**

## Result 1: Language Reference
**Score:** 0.8542 | **Type:** core_language | **Chunk:** 42/156

**Content:**

QUEUE Structure

A QUEUE is a memory-resident table with automatic memory management... [Full documentation excerpt with proper formatting]


## Result 2: Programming Guide
**Score:** 0.7891 | **Type:** core_language | **Chunk:** 89/201

**Content:**

[Additional relevant content...]


---
*Retrieved from Clarion Knowledge Base (Vector Store: 5 chunks)*

Tips for Effective Queries

Be Specific: "How do I sort a QUEUE?" vs. "QUEUE sorting"
Use Natural Language: Write questions as you would ask a colleague
Include Context: "In templates, how do I..." helps filter results
Try Multiple Phrasings: If results aren't great, rephrase your question
Use Filters: Specify doc_type for focused searches (see Advanced Usage)

Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    Claude AI (Code/Desktop)                  │
│                                                              │
│  User asks: "How do I create a browse in Clarion?"          │
└────────────────────────┬─────────────────────────────────────┘
                         │ MCP Protocol
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              Docker Container: clarion-mcp-server            │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  MCP Server (Python)                                 │  │
│  │  - Receives query                                    │  │
│  │  - Generates embedding (768-dim vector)              │  │
│  │  - Searches vector database                          │  │
│  │  - Formats results with citations                    │  │
│  └────────────────────┬─────────────────────────────────┘  │
└─────────────────────────┼─────────────────────────────────────┘
                         │ gRPC/HTTP
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              Docker Container: clarion-qdrant                │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Qdrant Vector Database                              │  │
│  │  - 21,747 documentation chunks                       │  │
│  │  - 768-dimensional embeddings                        │  │
│  │  - < 100ms search latency                            │  │
│  │  - Persistent storage (Docker volume)                │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Components

1. Qdrant Vector Database

Stores 21,747 document chunks as 768-dimensional embeddings
Uses all-MiniLM-L6-v2 sentence transformer model
Persistent storage via Docker volume (655 MB)
Ports: 6333 (REST API), 6334 (gRPC)

2. MCP Server (Python)

Implements Model Context Protocol for Claude integration
Handles query embedding generation
Performs vector similarity search
Formats results with metadata and citations
Runs on-demand via docker exec (no persistent process)

3. Docker Compose Orchestration

Manages both services as a unit
Handles networking between containers
Provides health checks and automatic restarts
Isolates dependencies (no Python environment conflicts)

Communication Flow

User Query → Claude Code/Desktop receives natural language question
MCP Call → Claude invokes search_docs tool via MCP protocol
Embedding → MCP server generates query embedding using sentence transformers
Vector Search → Qdrant finds similar document chunks via cosine similarity
Results → MCP server formats results with scores, sources, and content
Response → Claude receives structured results and presents to user

Troubleshooting

Common Issues

Docker Not Running

Symptom: Installation fails with "Cannot connect to Docker daemon"

Solution:

# Start Docker Desktop application
# Wait for it to fully start (whale icon in system tray)
# Retry installation

Port Conflicts (6333, 6334)

Symptom: "Port already in use" error

Solution:

# Check what's using the ports
# Windows:
netstat -ano | findstr :6333
# Mac/Linux:
lsof -i :6333

# Stop conflicting service or change ports in docker-compose.yml

MCP Server Not Responding

Symptom: Claude shows "MCP server timeout" or no response

Solution:

# Check if containers are running
docker ps

# Should see both:
# - clarion-qdrant
# - clarion-mcp-server

# If not running:
cd /path/to/clarion-knowledge-base
docker-compose up -d

# Check logs
docker logs clarion-mcp-server
docker logs clarion-qdrant

Configuration File Not Found

Symptom: "Could not find Claude config file"

Solution:

Verify Claude Code/Desktop is installed
Run Claude at least once to create config directory
Manually create config file using examples above
Ensure JSON syntax is valid (use a JSON validator)

Search Returns No Results

Symptom: All queries return "No results found"

Solution:

# Check if vector database is populated
docker exec -it clarion-qdrant curl http://localhost:6333/collections/clarion_docs

# Should show points_count: 21747
# If not, database may need re-import

Checking Logs

View MCP Server logs:

docker logs clarion-mcp-server
# Add -f to follow logs in real-time
docker logs -f clarion-mcp-server

View Qdrant logs:

docker logs clarion-qdrant

View all logs:

docker-compose logs

Restarting Services

Restart both services:

cd /path/to/clarion-knowledge-base
docker-compose restart

Restart individual service:

docker restart clarion-mcp-server
# or
docker restart clarion-qdrant

Full restart (stops and starts):

docker-compose down
docker-compose up -d

Advanced Usage

Updating the Vector Database

If you want to rebuild the vector database from scratch (for developers):

# 1. Ensure you have source PDFs in Documents/
# 2. Activate Python virtual environment
python -m venv .venv
source .venv/bin/activate  # Mac/Linux
# or
.venv\Scripts\activate  # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Run processing pipeline
python src/pipeline_v3.py --recreate

# 5. Restart Docker services
docker-compose restart

Rebuilding Containers

Force rebuild of Docker images:

# Rebuild without cache
docker-compose build --no-cache

# Restart with new images
docker-compose up -d --force-recreate

Environment Variables

Customize behavior via environment variables in docker-compose.yml:

environment:
  - QDRANT_HOST=qdrant        # Qdrant container hostname
  - QDRANT_PORT=6333          # Qdrant REST API port
  - COLLECTION_NAME=clarion_docs  # Vector collection name

Development Setup

For local development outside Docker:

# 1. Clone repository
git clone https://github.com/peterparker57/clarion-knowledge-base
cd clarion-knowledge-base

# 2. Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Mac/Linux
.venv\Scripts\activate     # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Start Qdrant only
docker-compose up -d qdrant

# 5. Run MCP server locally (for testing)
python src/mcp_server.py

# 6. Configure Claude to use local Python instead of Docker
# Update config to point to your local Python interpreter

Technical Details

Technology Stack

Language: Python 3.13+
Vector Database: Qdrant (latest)
Embedding Model: sentence-transformers/all-MiniLM-L6-v2
- Dimension: 768
- Model size: ~80 MB
- Inference: CPU-based, ~50ms per query
MCP Protocol: Version 1.17.0
PDF Processing: PyMuPDF4LLM (for developers rebuilding DB)
Containerization: Docker & Docker Compose

Database Statistics

Total Chunks: 21,747
Source Documents: 21 Clarion PDF manuals
Average Chunk Size: 574 characters
Storage Size:
- Compressed (download): 76 MB
- Uncompressed (Docker volume): 655 MB
Search Performance: < 100ms typical query time

Documentation Categories

The vector database includes these document types:

core_language - Language Reference, Programming Guide, Learning Clarion
libraries - ABC Library Reference, Internet Builder, Business Math Library
ide_development - IDE Reference, User Guide, Getting Started
templates - Template Guide, Template Language Reference
specialized - File Drivers, XML, Report Writer, Application Broker

Filtered Search Example

Use the doc_type parameter to search specific categories:

# In Claude, you can specify:
search_docs(
    query="How do I handle file errors?",
    doc_type="core_language",
    max_results=3,
    min_score=0.5
)

Documentation

Full Documentation

Complete HTML documentation is available in the repository:

Local: Open documentation/index.html in your browser
Includes: Detailed architecture, API reference, development guides

External Resources

MCP Protocol: Model Context Protocol Docs
Qdrant Documentation: qdrant.tech/documentation
Docker Documentation: docs.docker.com
Claude AI: claude.ai

Contributing

This project is designed for Clarion developers who want instant access to documentation within Claude AI.

Future Improvements

Potential enhancements we're considering:

Support for custom Clarion documentation (your company's docs)
Integration with Clarion community forums and knowledge bases
Enhanced metadata (code examples, version-specific docs)
Multi-language support
GraphRAG for relationship mapping between concepts

Feedback Welcome

Found a bug? Have a suggestion? Please:

Check existing GitHub Issues
Open a new issue with details
Include logs and reproduction steps
Tag appropriately (bug, enhancement, documentation)

Note: This is a community tool. Response times may vary.

License & Acknowledgements

License

This project is licensed under the MIT License - see LICENSE file for details.

Important: This tool processes Clarion documentation which is copyrighted by SoftVelocity Inc. The vector database is derived from official Clarion documentation PDFs. This tool is intended for personal and educational use by licensed Clarion developers. The original PDF documentation is not redistributed with this project.

Clarion Documentation

All documentation content is copyright SoftVelocity Inc. and used under fair use for personal reference purposes. This tool does not replace official documentation but provides enhanced search capabilities.

Acknowledgements

This project stands on the shoulders of incredible open-source tools:

Claude AI & MCP Protocol - Anthropic for the Model Context Protocol
Qdrant - qdrant.tech for the vector database engine
Sentence Transformers - sbert.net for the embedding model
PyMuPDF4LLM - pymupdf.io for PDF parsing
Docker - docker.com for containerization
Python Community - For all the amazing libraries that make this possible

Special Thanks:

SoftVelocity for creating Clarion and maintaining excellent documentation
The Clarion developer community for feedback and support

Project Status

Version: 1.0.0 Status: Production Ready ✓ Last Updated: 2025-10-12

Tested Environments

✓ Windows 10/11 with Docker Desktop
✓ macOS 12+ with Docker Desktop
✓ Linux (Ubuntu 22.04+) with Docker Engine
✓ Claude Code (latest)
✓ Claude Desktop (latest)

Known Limitations

Code Indentation: Some code examples may have lost indentation during PDF conversion. Clarion code should be manually formatted before use.
PDF Quality: Search quality depends on source PDF quality. Some older manuals may have OCR artifacts.
No Incremental Updates: To update documentation, full rebuild currently required.
English Only: Only English language documentation is supported.

Contact & Support

GitHub Repository: github.com/peterparker57/clarion-knowledge-base
Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ for the Clarion Developer Community

Bringing 20+ years of Clarion documentation to your AI assistant

⭐ Star on GitHub | | 🐛 Report Bug