Onyx MCP Server

Search and query Onyx programming language documentation and GitHub code examples.

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.

⚡ Instant Access with NPX (No Installation Required!)

Configure Claude Desktop (or other MCP-compatible LLM):

{ "mcpServers": { "onyx": { "command": "npx", "args": ["@onyxlang/mcp-server", "bridge", "--url", "https://mcp.onyxlang.io"] } } }

🎆That's it!No installation, no setup, no data crawling needed. You get instant access to the latest Onyx documentation and examples.

Option 1: Install from npm (Recommended)

# Install globally npm install -g @onyxlang/mcp-server # Or install locally in your project npm install @onyxlang/mcp-server

git clone https://github.com/onyx-lang/onyx-mcp-server.git cd onyx-mcp-server npm install cp .env.example .env # Edit .env and add your GitHub token (optional but recommended)

# Start MCP server onyx-mcp server # Start HTTP server onyx-mcp http # Start bridge to hosted server onyx-mcp bridge --url https://mcp.onyxlang.io # Crawl data (if running locally) onyx-mcp crawl all

# Use npm scripts with arguments npm start # MCP server npm run http # HTTP server on default port (3001) npm run http -- --port 3002 # HTTP server on custom port npm run bridge # Bridge to default (localhost:3001) npm run bridge -- --url https://mcp.onyxlang.io # Bridge to hosted server npm run crawl:all # Crawl all data # Or run directly node src/index.js server node src/index.js http --port 3002 node src/index.js bridge --url https://mcp.onyxlang.io

# Start the MCP server (default) npm start # Start the HTTP server for REST API access npm run http npm run http -- --port 3002 # Custom port # Start the MCP-to-HTTP bridge (connects to local or remote HTTP server) npm run bridge npm run bridge -- --url https://mcp.onyxlang.io # Connect to hosted server # Run with development mode npm run dev # MCP server npm run http:dev # HTTP server # Run tests npm test # Crawl data to populate the MCP (CLI only, not through MCP interface) npm run crawl:all

The system provides both MCP query functionality and CLI-based crawling:

# MCP Server operations (query/search only) node src/index.js server # Start MCP server node src/index.js server --dev # Development mode node src/index.js http # Start HTTP server node src/index.js http --port 3002 # HTTP server on custom port node src/index.js bridge # Start MCP-to-HTTP bridge node src/index.js bridge --url https://mcp.onyxlang.io # Connect to hosted server # Using npm scripts (with argument passing) npm start # MCP server npm run http # HTTP server (port 3001) npm run http -- --port 3002 # HTTP server on custom port npm run bridge # Bridge to localhost:3001 npm run bridge -- --url https://mcp.onyxlang.io # Bridge to hosted server # Data crawling (CLI only - NOT accessible through MCP) node src/index.js crawl docs # Documentation only node src/index.js crawl github repo1 repo2 # Specific repositories node src/index.js crawl url https://... # Single URL node src/index.js crawl all # Everything # Utilities node src/index.js test # Run test suite node src/index.js validate # Validate setup

onyx_mcp/ ├── src/ │ ├── bridge.js # 🌉 MCP-to-HTTP bridge for remote access │ ├── index.js # 🎯 Unified entry point │ ├── mcp-server.js # 🌐 MCP server implementation │ ├── mcp-http.js # 🌐 MCP over HTTP server implementation │ ├── test.js # 🧪 Test suite │ ├── validate.js # ✅ Setup validation │ ├── crawlers/ # 📡 Data crawlers │ │ ├── docs.js # - Documentation crawler │ │ ├── github.js # - GitHub repository crawler │ │ └── urls.js # - URL content crawler │ └── core/ # 🔧 Core functionality │ └── search-engine.js # - Search and indexing ├── data/ # 📊 Crawled data (auto-generated) ├── .env.example # 🔐 Environment template └── package.json # 📦 Dependencies & scripts

The server provides theseread-onlysearch and query tools to Claude:

- search_onyx_docs- Search official documentation

- search_github_examples- Search code by topic
- get_onyx_functions- Function definitions from GitHub
- get_onyx_structs- Struct definitions from GitHub
- list_github_repos- List available repositories

- search_all_sources- Search across all data sources

- run_onyx_code- Execute Onyx code and return output/errors for testing and debugging
- run_wasm- Execute WebAssembly code and return output/errors for testing and debugging
- build_onyx_code- Build Onyx code file using "onyx build" in a specified directory
- onyx_pkg_build- Build an Onyx package using "onyx pkg build" in a specified directory

Crawling tools are available through the CLI butintentionally NOT accessiblethrough the MCP interface. This ensures clean separation between data collection and query functionality.

# GitHub token (recommended for higher rate limits) GITHUB_TOKEN=your_github_token_here # Optional settings DEBUG=false MAX_CRAWL_LIMIT=50

You can connect to the Onyx MCP in multiple ways:

⚡ Option 1: NPX Bridge (Zero Installation)

{ "mcpServers": { "onyx": { "command": "npx", "args": ["@onyxlang/mcp-server", "bridge", "--url", "https://mcp.onyxlang.io"] } } }

Option 2: Local MCP Server (For Development)

{ "mcpServers": { "onyx": { "command": "node", "args": ["/path/to/onyx_mcp/src/index.js", "server"] } } }

Option 3: Connect to Custom Hosted Server via Bridge

{ "mcpServers": { "onyx": { "command": "node", "args": ["/path/to/onyx_mcp/src/index.js", "bridge", "--url", "https://mcp.onyxlang.io"], } } }

- Start the HTTP server:

npm run http --port 3002

{ "mcpServers": { "onyx": { "command": "node", "args": ["/path/to/onyx_mcp/src/index.js", "bridge", "--url", "http://localhost:3002"] } } }

git clone <repository> cd onyx_mcp npm install cp .env.example .env

Configure Claude Desktopwith local server (see integration section above)

git clone <repository> cd onyx_mcp npm install

Configure Claude Desktopwith bridge (see integration section above)

The bridge allows you to connect the MCP protocol to HTTP servers:

Claude Desktop → MCP Bridge → HTTP Server (Local or Remote)

- ✅ Connect to hosted Onyx MCP atmcp.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

The code execution tools enable Claude to test, build, and refine Onyx code through iterative feedback:

- run_onyx_code- Execute code in sandbox for quick testing
- build_onyx_code- Build code files in user's specified directory
- onyx_pkg_build- Build complete Onyx packages in user's project directory
- Claude writes Onyx codebased on your requirements
- Tests withrun_onyx_codefor quick validation (sandbox)
- Builds withbuild_onyx_codein your project directory
- Reads build/compilation errorsfrom the output
- Analyzes and fixes issues- syntax, imports, dependencies
- Builds packages withonyx_pkg_buildin your project directory
- Repeats until success- working, compiled code in your directory!

User: "Write a function to calculate fibonacci numbers" 1. Claude writes initial code 2. Tests with run_onyx_code (sandbox) 3. Sees errors and fixes them 4. Code runs successfully

User: "Build this code in my project at /home/user/myproject" 1. Claude uses build_onyx_code with directory: "/home/user/myproject" 2. Sees build errors and fixes imports 3. Creates working executable in user's directory 4. User can run the built program directly

User: "Build my Onyx package in /home/user/onyx-lib" 1. Claude uses onyx_pkg_build with directory: "/home/user/onyx-lib" 2. Fixes package configuration issues 3. Creates complete built package in user's directory 4. User can distribute/use the package

- ✅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

- Onyx compilermust 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

# Crawl specific repositories node src/index.js crawl github onyx-lang/onyx user/project # With various URL formats node src/index.js crawl github \ https://github.com/onyx-lang/onyx \ github.com/user/repo \ owner/project

# Quick validation npm run validate # Full test suite npm test # Expected results: 100% pass rate

"Show me examples of HTTP requests in Onyx" "How do I define a struct with KDL configuration?" "What are the available string manipulation functions?" "Find PostgreSQL ORM examples in Onyx repositories"

// ============================================================================= // CONFIGURABLE CONTEXT MESSAGE // ============================================================================= // This message will be prepended to all MCP tool responses. // Modify this section to customize the context provided to the assistant. const GLOBAL_CONTEXT_MESSAGE = You are assisting with Onyx programming language queries...;

An MCP server providing searchable access to multiple AI/ML SDK documentation and source code.