Onyx MCP服务器
一个模型上下文协议（MCP）服务器，提供对Onyx编程语言文档和GitHub代码示例的搜索和查询访问。服务器包括全面的爬行功能来填充数据，但爬行无法通过MCP接口访问，从而确保数据收集和查询功能之间的清晰分离。
🚀 快速开始
⚡ 使用NPX即时访问（无需安装！）
配置克劳德桌面（或其他兼容MCP的LLM）：
{
"mcpServers": {
"onyx": {
"command": "npx",
"args": ["@onyxlang/mcp-server", "bridge", "--url", "https://mcp.onyxlang.io"]
}
}
}🎆 就是这样！ 无需安装、设置或数据爬行。您可以立即访问最新的Onyx文档和示例。
安装
选项1：从npm安装（推荐）
# Install globally
npm install -g @onyxlang/mcp-server
# Or install locally in your project
npm install @onyxlang/mcp-server选项2：从源代码安装
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🎯 服务器接口
该系统提供MCP查询功能和基于CLI的爬网：
# 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🛠️ MCP工具可用
服务器提供这些 只读的 Claude的搜索和查询工具：
📚 文档
search_onyx_docs-搜索官方文件
🐙 GitHub集成
search_github_examples-按主题搜索代码get_onyx_functions-GitHub中的函数定义get_onyx_structs-GitHub中的结构定义list_github_repos-列出可用存储库
🔍 统一搜索
search_all_sources-搜索所有数据源
🚀 代码执行
run_onyx_code-执行Onyx代码并返回用于测试和调试的输出/错误run_wasm-执行WebAssembly代码并返回用于测试和调试的输出/错误build_onyx_code-在指定目录中使用“Onyx-Build”构建Onyx代码文件onyx_pkg_build-在指定目录中使用“Onyx-pkg-Build”构建Onyx包
⚠️ 重要提示
爬行工具可以通过CLI获得，但 故意不可访问 通过MCP接口。这确保了数据收集和查询功能之间的清晰分离。
🔧 配置
环境变量（.env）
# GitHub token (recommended for higher rate limits)
GITHUB_TOKEN=your_github_token_here
# Optional settings
DEBUG=false
MAX_CRAWL_LIMIT=50🌐 Claude桌面集成
您可以通过多种方式连接到Onyx MCP：
⚡ 选项1:NPX桥（零安装）
对于托管服务器（始终是最新的）：
{
"mcpServers": {
"onyx": {
"command": "npx",
"args": ["@onyxlang/mcp-server", "bridge", "--url", "https://mcp.onyxlang.io"]
}
}
}选项2：本地MCP服务器（用于开发）
{
"mcpServers": {
"onyx": {
"command": "node",
"args": ["/path/to/onyx_mcp/src/index.js", "server"]
}
}
}选项3：通过网桥连接到自定义托管服务器
{
"mcpServers": {
"onyx": {
"command": "node",
"args": ["/path/to/onyx_mcp/src/index.js", "bridge", "--url", "https://mcp.onyxlang.io"],
}
}
}选项4：本地HTTP服务器+网桥
为了在本地测试桥梁：
- 启动HTTP服务器：
npm run http --port 3002- 配置Claude桌面 使用桥：
{
"mcpServers": {
"onyx": {
"command": "node",
"args": ["/path/to/onyx_mcp/src/index.js", "bridge", "--url", "http://localhost:3002"]
}
}
}用于开发（本地设置）
- 克隆和设置：
git clone
cd onyx_mcp
npm install
cp .env.example .env- 填充数据：
npm run crawl:all- 启动MCP服务器：
npm start- 配置Claude桌面 使用本地服务器（请参阅上面的集成部分）
用于生产（托管服务器）
- 克隆和设置：
git clone
cd onyx_mcp
npm install- 启动HTTP服务器：
npm run http - 配置Claude桌面 带桥接器（见上文集成部分）
桥梁建筑
该网桥允许您将MCP协议连接到HTTP服务器：
Claude Desktop → MCP Bridge → HTTP Server (Local or Remote)优点：
- ✅ 连接到托管的Onyx MCP
mcp.onyxlang.io - ✅ 无需运行本地服务器或填充数据
- ✅ 始终了解最新的Onyx信息
- ✅ 相同的MCP接口，不同的后端
- ✅ 在本地和远程服务器之间轻松切换
🔄 代码测试和反馈循环
代码执行工具使Claude能够通过迭代反馈测试、构建和改进Onyx代码：
可用工具：
run_onyx_code-在沙盒中执行代码以进行快速测试build_onyx_code-在用户指定的目录中构建代码文件onyx_pkg_build-在用户的项目目录中构建完整的Onyx包
它是如何工作的：
- Claude编写Onyx代码 根据您的要求
- 测试与
run_onyx_code用于快速验证（沙盒） - 构建与
build_onyx_code在您的项目目录中 - 读取构建/编译错误 从输出
- 分析并修复问题 -语法、导入、依赖关系
- 使用以下内容构建包
onyx_pkg_build在您的项目目录中 - 重复直到成功 -在您的目录中运行已编译的代码！
示例工作流：
快速测试：
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优点：
- ✅ 自纠错码 -克劳德可以纠正自己的错误
- ✅ 真实验证 -实际运行代码，而不仅仅是语法检查
- ✅ 从错误中学习 -改进基于Onyx编译器反馈的建议
- ✅ 迭代精化 -不断改进，直到代码完美运行
- ✅ 对结果的信心 -你知道代码实际上是编译和运行的
要求：
- Onyx编译器 必须在PATH中安装并可用
- 从以下位置安装：https://onyxlang.io/
- 该工具在沙盒临时目录中执行代码
- 默认超时10秒（可配置）可防止无限循环
📊 数据源和爬网
该系统包括全面的爬行功能来填充数据：
📚 文档来源
- 奥尼克斯官方文件
- 教程和指南文件
- API文档
- 语言参考资料
🐙 GitHub资源
- Onyx语言存储库
- 代码示例和教程
- 包和库文档
- 配置文件和项目设置
📁 支持的文件类型
.onyx源文件.kdl配置文件- README、文档和指南文件
- HTML文档页面
- 软件包配置(
onyx.pkg等等）
🔄 数据填充过程
- 使用CLI爬网命令 填充
data/目录 - MCP服务器搜索 预先抓取的数据
- 无爬行触发器 可通过MCP接口访问
📡 增强的GitHub爬行
GitHub爬虫提取全面的内容：
📚 文档：
- README.md，许可证，变更日志.md
- 所有文件
docs/文件夹 - HTML文档和网页
- 教程和指南文件
🔧 配置：
.kdl文件（Onyx项目管理）onyx.pkg和包配置- TOML、YAML、JSON配置
💻 源代码：
- 全部
.onyx源文件 - 示例和教程文件
- HTML示例和web界面
🌐 Web内容：
- HTML文档页面
- 交互式示例和演示
- 基于网络的教程和指南
- HTML格式的API文档
库管理
# 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测试验证：
- ✅ 文件结构完整性
- ✅ 模块导入功能
- ✅ 数据目录操作
- ✅ 爬行器配置
- ✅ 搜索引擎错误处理
💡 使用示例
连接到Claude Desktop后：
"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"🔧 可配置上下文系统
全局上下文消息
所有MCP工具响应都包含一个可配置的上下文消息，可以在顶部轻松修改 src/mcp-server.js:
// =============================================================================
// 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...`;这使您能够：
- 自定义助手的上下文 对于Onyx查询
- 提供一致的指导 在所有工具响应中
- 轻松更新说明 无需修改单个工具
- 保持上下文连贯性 在整个对话中
🚀 关键设计原则
安全与关注点分离
- MCP接口为只读 -无法触发爬网或数据修改
- 可通过CLI进行爬网 -对数据收集的完全控制
- 干净的建筑 -数据收集与查询功能分开
- 没有外部API调用 通过MCP工具
增强的用户体验
- 一致的上下文 在所有回复中
- 特定于工具的消息传递 为清晰起见
- 全面的错误处理 根据上下文
- 传统兼容性 对于现有工作流
🔍 数据流
- CLI爬网命令 在中填充数据源
data/目录 - 搜索引擎 索引并提供统一的搜索功能
- MCP服务器 向Claude公开只读搜索工具
- 克劳德 通过可配置的消息接收上下文响应
- 上下文系统 确保在所有回复中提供一致、有益的指导
- 无爬行触发器 可通过MCP接口访问
📈 演出
- 高效缓存 防止不必要的重新爬行
- 速率限制 遵守API限制
- 并行处理 用于多个存储库
- 全面的错误处理 可靠性
______________________________________________________________________
*此MCP服务器通过可配置的上下文系统为Claude提供对Onyx编程语言知识的安全、只读访问。通过CLI命令可以获得全面的爬行功能，但故意不通过MCP接口访问，从而确保数据收集和查询功能之间的清晰分离。*