Used for dependency management and running scripts to install, crawl documentation, and start the MCP server.
Onyx MCP Server
A Model Context Protocol (MCP) server providing search and query access to Onyx programming language documentation and GitHub code examples. The server includes comprehensive crawling capabilities to populate data, but crawling is NOT accessible through the MCP interface - ensuring clean separation between data collection and query functionality.
🚀 Quick Start
⚡ Instant Access with NPX (No Installation Required!)
Configure Claude Desktop (or other MCP-compatible LLM):
🎆 That's it! No installation, no setup, no data crawling needed. You get instant access to the latest Onyx documentation and examples.
Installation
Option 1: Install from npm (Recommended)
Option 2: Install from source
Usage
If installed globally:
If installed locally or from source:
Basic Usage
🎯 Server Interface
The system provides both MCP query functionality and CLI-based crawling:
📁 Project Structure
🛠️ MCP Tools Available
The server provides these read-only search and query tools to Claude:
📚 Documentation
search_onyx_docs
- Search official documentation
🐙 GitHub Integration
search_github_examples
- Search code by topicget_onyx_functions
- Function definitions from GitHubget_onyx_structs
- Struct definitions from GitHublist_github_repos
- List available repositories
🔍 Unified Search
search_all_sources
- Search across all data sources
🚀 Code Execution
run_onyx_code
- Execute Onyx code and return output/errors for testing and debuggingrun_wasm
- Execute WebAssembly code and return output/errors for testing and debuggingbuild_onyx_code
- Build Onyx code file using "onyx build" in a specified directoryonyx_pkg_build
- Build an Onyx package using "onyx pkg build" in a specified directory
⚠️ Important Note
Crawling tools are available through the CLI but intentionally NOT accessible through the MCP interface. This ensures clean separation between data collection and query functionality.
🔧 Configuration
Environment Variables (.env)
🌐 Claude Desktop Integration
You can connect to the Onyx MCP in multiple ways:
⚡ Option 1: NPX Bridge (Zero Installation)
For hosted server (always up-to-date):
Option 2: Local MCP Server (For Development)
Option 3: Connect to Custom Hosted Server via Bridge
Option 4: Local HTTP Server + Bridge
For testing the bridge locally:
Start the HTTP server:
npm run http --port 3002Configure Claude Desktop to use the bridge:
{ "mcpServers": { "onyx": { "command": "node", "args": ["/path/to/onyx_mcp/src/index.js", "bridge", "--url", "http://localhost:3002"] } } }
For Development (Local Setup)
Clone and setup:
git clone <repository> cd onyx_mcp npm install cp .env.example .envPopulate data:
npm run crawl:allStart MCP server:
npm startConfigure Claude Desktop with local server (see integration section above)
For Production (Hosted Server)
Clone and setup:
git clone <repository> cd onyx_mcp npm installStart HTTP server:
npm run httpConfigure Claude Desktop with bridge (see integration section above)
Bridge Architecture
The bridge allows you to connect the MCP protocol to HTTP servers:
Benefits:
✅ Connect to hosted Onyx MCP at
mcp.onyxlang.io
✅ No need to run local server or populate data
✅ Always up-to-date with latest Onyx information
✅ Same MCP interface, different backend
✅ Easy switching between local and remote servers
🔄 Code Testing & Feedback Loop
The code execution tools enable Claude to test, build, and refine Onyx code through iterative feedback:
Available Tools:
run_onyx_code
- Execute code in sandbox for quick testingbuild_onyx_code
- Build code files in user's specified directoryonyx_pkg_build
- Build complete Onyx packages in user's project directory
How it Works:
Claude writes Onyx code based on your requirements
Tests with for quick validation (sandbox)
Builds with in your project directory
Reads build/compilation errors from the output
Analyzes and fixes issues - syntax, imports, dependencies
Builds packages with in your project directory
Repeats until success - working, compiled code in your directory!
Example Workflows:
Quick Testing:
Project Building:
Package Development:
Benefits:
✅ Self-correcting code - Claude can fix its own mistakes
✅ Real validation - Actually runs the code, not just syntax checking
✅ Learning from errors - Improves suggestions based on Onyx compiler feedback
✅ Iterative refinement - Keeps improving until code works perfectly
✅ Confidence in results - You know the code actually compiles and runs
Requirements:
Onyx compiler must be installed and available in PATH
Install from: https://onyxlang.io/
The tool executes code in a sandboxed temporary directory
Default timeout of 10 seconds (configurable) prevents infinite loops
📊 Data Sources & Crawling
The system includes comprehensive crawling capabilities to populate data:
📚 Documentation Sources
Official Onyx documentation
Tutorial and guide files
API documentation
Language reference materials
🐙 GitHub Sources
Onyx language repositories
Code examples and tutorials
Package and library documentation
Configuration files and project setups
📁 Supported File Types
.onyx
source files.kdl
configuration filesREADME, documentation, and guide files
HTML documentation pages
Package configurations (
onyx.pkg
, etc.)
🔄 Data Population Process
Use CLI crawling commands to populate the
data/
directoryMCP server searches the pre-crawled data
No crawling triggers are available through the MCP interface
📡 Enhanced GitHub Crawling
The GitHub crawler extracts comprehensive content:
📚 Documentation:
README.md, LICENSE, CHANGELOG.md
All documentation in
docs/
foldersHTML documentation and web pages
Tutorial and guide files
🔧 Configuration:
.kdl
files (Onyx project management)onyx.pkg
and package configurationsTOML, YAML, JSON configs
💻 Source Code:
All
.onyx
source filesExample and tutorial files
HTML examples and web interfaces
🌐 Web Content:
HTML documentation pages
Interactive examples and demos
Web-based tutorials and guides
API documentation in HTML format
Repository Management
🧪 Testing & Validation
Tests validate:
✅ File structure integrity
✅ Module import functionality
✅ Data directory operations
✅ Crawler configurations
✅ Search engine error handling
💡 Usage Examples
Once connected to Claude Desktop:
🔧 Configurable Context System
Global Context Message
All MCP tool responses include a configurable context message that can be easily modified at the top of src/mcp-server.js
:
This allows you to:
Customize the assistant's context for Onyx queries
Provide consistent guidance across all tool responses
Easily update instructions without modifying individual tools
Maintain context coherence throughout conversations
🚀 Key Design Principles
Security & Separation of Concerns
MCP interface is read-only - cannot trigger crawling or data modification
Crawling available through CLI - full control over data collection
Clean architecture - data collection separate from query functionality
No external API calls through MCP tools
Enhanced User Experience
Consistent context across all responses
Tool-specific messaging for clarity
Comprehensive error handling with context
Legacy compatibility for existing workflows
🔍 Data Flow
CLI Crawling Commands populate data sources in
data/
directorySearch Engine indexes and provides unified search capabilities
MCP Server exposes read-only search tools to Claude
Claude receives contextual responses with configurable messaging
Context System ensures consistent, helpful guidance in all responses
No crawling triggers available through MCP interface
📈 Performance
Efficient caching prevents unnecessary re-crawling
Rate limiting respects API limits
Parallel processing for multiple repositories
Comprehensive error handling for reliability
This MCP server provides Claude with secure, read-only access to Onyx programming language knowledge through a configurable context system. Comprehensive crawling capabilities are available through CLI commands but intentionally not accessible through the MCP interface, ensuring clean separation between data collection and query functionality.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Provides AI systems with access to Onyx programming language documentation through web crawling and intelligent search capabilities.
Related MCP Servers
- -securityAlicense-qualityProvides tools for retrieving and processing documentation through vector search, enabling AI assistants to augment their responses with relevant documentation context.Last updated -14MIT License
- -securityFlicense-qualityEnables AI assistants to search for documentation of packages and services, providing implementation details, examples, and specifications through a specialized API.Last updated -32
- -securityAlicense-qualityA comprehensive server that enables AI assistants to generate, configure, and manage Doxygen documentation for various programming languages through a clean interface.Last updated -2GPL 3.0
- -securityAlicense-qualityA sophisticated server that enables AI assistants to automatically analyze codebases and generate comprehensive, professional documentation.Last updated -1MIT License