Hyperon Wiki MCP客户端和工具

用于Hyperon Wiki API的Ruby客户端库和CLI(wiki.hyperon.dev).通过基于角色的安全性、批处理操作和CQL查询和扰流板扫描等高级功能，提供对Decko知识图的编程访问。

![Ruby](https://www.ruby-lang.org/) ![License](LICENSE) ![Tests](spec/) ![RuboCop](https://rubocop.org/) ![Phase](<>)

概述

这 Hyperon Wiki MCP客户端 是一个Ruby库和命令行工具，用于与Hyperon Wiki Decko知识图进行交互。它为人类用户和人工智能代理提供了安全的角色软件API访问。

组件：

Ruby客户端库 (lib/magi/archive/mcp/)-具有JWT身份验证、重试逻辑和基于角色的访问控制的HTTP客户端
CLI工具 (bin/hyperon-wiki-mcp)-用于交互式使用和脚本编写的命令行界面
工具模块 (lib/magi/archive/mcp/tools.rb)-卡片操作、搜索、标签、关系、验证和管理功能的高级方法

客户端连接到 Hyperon Wiki API服务器 （独立存储库位于 hyperon-wiki)，它提供在其上运行的实际后端服务 wiki.hyperon.dev.

实施状态：第3阶段完成 ✅

所有核心功能、批处理操作和高级功能都已实施，并准备投入生产。

特性

核心卡运营（第一阶段）

基于角色的安全性：具有RS256 JWT身份验证的三层访问控制（用户、GM、管理员）
卡片CRUD：完全创建/读取/更新/删除，并强制执行角色
批处理：具有部分故障处理的批量操作（按项目或事务模式）
格式转换：HTML↔ Markdown渲染
儿童管理：使用复合命名列出并创建子卡(Parent+Child)
CLI工具：具有JSON/漂亮输出格式的命令行界面

高级功能（第2-3阶段）

管理员数据库备份：创建、下载、列出和删除数据库备份（仅限管理员）
卡片关系：探索连接（引用者、嵌套、链接、linked_by、nested_in）
标签操作：通过带有AND/OR逻辑、模式匹配和AI辅助建议的标签进行搜索
卡片验证：根据卡片类型验证标签和结构，并提供基于内容的建议
每周摘要生成：结合wiki更改和git存储库活动的自动摘要
安全CQL查询：执行具有强制安全限制的卡查询语言查询
扰流板扫描：异步作业，扫描玩家/AI内容，寻找仅限GM的破坏者
类型发现：列出并探索可用的卡类型

看 MCP-SPEC.md API完整规范和 MCP_SERVER.md 使用指南。

快速安装（选择您的客户端）

先决条件：Ruby 3.2+(ruby --version 检查）

# Clone and install dependencies
git clone https://github.com/Magi-AGI/hyperon-wiki-mcp.git
cd hyperon-wiki-mcp
bundle install

# Then run the installer for your AI client:
ruby bin/install-claude-desktop   # Claude Desktop (macOS/Windows/Linux)
ruby bin/install-cursor           # Cursor IDE
ruby bin/install-gemini           # Gemini CLI
ruby bin/install-codex            # Codex CLI
ruby bin/install-claude-cli       # Claude Code CLI

每个安装程序都会提示您输入Decko wiki凭据（建议使用用户名/密码）。

安装后：重新启动AI客户端并尝试“从Hyperon Wiki获取主页卡”

看 MCP_SERVER.md 有关详细的安装说明和故障排除。

______________________________________________________________________

快速入门（库使用）

基本用法

require "magi/archive/mcp"

# Initialize tools (reads config from environment)
tools = Magi::Archive::Mcp::Tools.new

# Get a card
card = tools.get_card("Main Page")

# Search for cards
results = tools.search_cards(q: "quantum", type: "Article", limit: 10)

# Create a card (requires appropriate role)
new_card = tools.create_card("My New Card", content: "Content here", type: "Article")

MCP协议集成

对于Claude Desktop、Claude Code或Codex CLI等人工智能助手，请参阅 MCP_SERVER.md 有关安装和配置说明。

安装

如宝石（推荐）

gem install hyperon-wiki-mcp

来源

需要Ruby 3.2+ （检查 ruby --version)

# Using rbenv
brew install rbenv ruby-build
rbenv install 3.2.2
rbenv global 3.2.2

然后安装：

git clone https://github.com/Magi-AGI/hyperon-wiki-mcp.git
cd hyperon-wiki-mcp
bundle install
bundle exec rake install

开发设置

git clone https://github.com/your-org/hyperon-wiki-mcp.git
cd hyperon-wiki-mcp
bundle install

配置

两种身份验证方法

方法1：用户名/密码（推荐给人类用户）

使用您现有的Decko维基凭据-不需要API密钥！

# .env file
MCP_USERNAME=your-decko-username
MCP_PASSWORD=your-decko-password
DECKO_API_BASE_URL=https://wiki.hyperon.dev/api/mcp

# Optional: Override role (auto-detected from your permissions if not specified)
# MCP_ROLE=user

优点：

✅ 无需管理员干预
✅ 根据您的帐户权限自动检测角色
✅ 与您的wiki登录凭据相同
✅ 更好的审计跟踪（与您的用户帐户相关的操作）

方法2:neneneba API密钥（用于服务帐户/自动化）

对于机器人、脚本和自动化流程：

# .env file
MCP_API_KEY=your-64-char-api-key
MCP_ROLE=user              # Required with API key
DECKO_API_BASE_URL=https://wiki.hyperon.dev/api/mcp

获取API密钥： 联系您的Decko管理员为服务帐户生成API密钥。

用法

作为图书馆

基本卡操作

require "magi/archive/mcp"

# Initialize tools (uses environment variables for config)
tools = Magi::Archive::Mcp::Tools.new

# Get a card
card = tools.get_card("Main Page")
puts card["name"]
puts card["content"]

# Search for cards
results = tools.search_cards(q: "quantum", type: "Article", limit: 10)
results["cards"].each do |card|
  puts "#{card['name']} (#{card['type']})"
end

# Create a card (requires appropriate role)
new_card = tools.create_card(
  "My New Card",
  content: "This is the content.",
  type: "Article"
)

# Update a card
updated = tools.update_card("My New Card", content: "Updated content.")

# Delete a card (admin only)
tools.delete_card("My New Card", force: false)

分页

# Iterate through all matching cards
tools.each_card_page(q: "research", limit: 50) do |page|
  page["cards"].each do |card|
    puts card["name"]
  end
  puts "Offset: #{page['offset']}, Total: #{page['total']}"
end

批量操作

# Per-item mode: each operation independent
operations = [
  { action: "create", name: "Card 1", content: "Content 1" },
  { action: "create", name: "Card 2", content: "Content 2" },
  { action: "update", name: "Existing Card", content: "New content" }
]

result = tools.batch_operations(operations, mode: "per_item")
result["results"].each do |op_result|
  puts "#{op_result['action']} #{op_result['name']}: #{op_result['status']}"
end

# Transactional mode: all or nothing
result = tools.batch_operations(operations, mode: "transactional")

# Create child cards using helper
ops = [
  tools.build_child_op("Business Plan", "Overview", content: "Executive summary"),
  tools.build_child_op("Business Plan", "Goals", content: "Key objectives"),
  tools.build_child_op("Business Plan", "Timeline", content: "Project schedule")
]
result = tools.batch_operations(ops)

格式转换

# Markdown to HTML
html = tools.render_snippet("# Hello\n\nThis is **bold**.", from: :markdown, to: :html)

# HTML to Markdown
markdown = tools.render_snippet("
Hello

This is bold.
", from: :html, to: :markdown)

每周摘要生成

# Create a weekly summary card
card = tools.create_weekly_summary

# With custom options
card = tools.create_weekly_summary(
  base_path: "/path/to/repos",
  days: 7,
  date: "2025 12 09",
  executive_summary: "Custom summary..."
)

看 MCP_SERVER.md 以获取完整的文档。

使用CLI

这 hyperon-wiki-mcp CLI提供对所有MCP工具的命令行访问。

办张卡

hyperon-wiki-mcp get "Main Page"
hyperon-wiki-mcp get --name "Main Page" --with-children
hyperon-wiki-mcp get "Card Name" --format json

搜索卡片

hyperon-wiki-mcp search --query "quantum physics"
hyperon-wiki-mcp search --type Article --limit 20
hyperon-wiki-mcp search -q "research" -t Article -l 10 -o 20

创建卡片

hyperon-wiki-mcp create --name "New Article" --content "Content here" --type Article

更新卡片

hyperon-wiki-mcp update "Card Name" --content "Updated content"
hyperon-wiki-mcp update --name "Card Name" --type "Article"

删除卡（仅限管理员）

hyperon-wiki-mcp delete "Card Name"
hyperon-wiki-mcp delete "Card With Children" --force

列出卡片类型

hyperon-wiki-mcp types
hyperon-wiki-mcp types --limit 100

渲染内容

hyperon-wiki-mcp render --from markdown --to html --content "# Hello"
hyperon-wiki-mcp render --from html --to markdown --content "
Hello
"

列出孩子

hyperon-wiki-mcp children "Parent Card"
hyperon-wiki-mcp children --name "Parent Card" --limit 50

CLI选项

Usage: hyperon-wiki-mcp COMMAND [options]

Commands:
  get NAME              Get a card by name
  search                Search for cards
  create                Create a new card
  update NAME           Update an existing card
  delete NAME           Delete a card (admin only)
  types                 List card types
  render                Convert HTML/Markdown
  children PARENT       List child cards

Options:
  -n, --name NAME              Card name
  -q, --query QUERY            Search query
  -t, --type TYPE              Card type
  -c, --content CONTENT        Card content
  -l, --limit NUM              Result limit (default: 50)
  -o, --offset NUM             Result offset (default: 0)
  -f, --format FORMAT          Output format (json|pretty)
      --from FORMAT            Source format for rendering
      --to FORMAT              Target format for rendering
      --with-children          Include children in get
      --force                  Force delete even with children
      --debug                  Show debug information
  -h, --help                   Show this help
  -v, --version                Show version

建筑

三角色安全模型

用户角色(mcp-user):

- 阅读公共卡片 - 创建/更新自己的卡片 - 没有GM内容可见性 - 无破坏性操作

总经理角色(mcp-gm):

- 所有用户权限 - 仅阅读通用汽车内容 - 无破坏性操作

管理员角色(mcp-admin):

- 完全访问所有卡 - 删除和移动操作 - 系统管理

身份验证流程

客户端库从环境中读取凭据（API密钥或用户名/密码）
客户端库调用 POST /api/mcp/auth 在Hyperon Wiki API服务器上
API服务器发出短暂的RS256 JWT（15-60分钟到期）
JWT包括以下声明： sub, role, iss, iat, exp, jti, kid
客户端库通过API服务器的JWKS端点验证JWT签名
客户端库在到期前自动刷新令牌

Hyperon Wiki API服务器端点

客户端库连接到Hyperon Wiki API服务器上的这些端点（单独的存储库）。所有请求都需要 Authorization: Bearer :

核心运营（第1-2阶段）：

POST /api/mcp/auth -获取角色范围的JWT
GET /api/mcp/cards/:name -取卡片
GET /api/mcp/cards/:name/children -列出儿童卡片
GET /api/mcp/cards -搜索/列出卡片
POST /api/mcp/cards -创建卡片
PATCH /api/mcp/cards/:name -更新卡片
DELETE /api/mcp/cards/:name -删除卡（仅限管理员）
POST /api/mcp/cards/batch -批量操作
POST /api/mcp/render -HTML→Markdown转换
POST /api/mcp/render/markdown -Markdown→HTML转换

高级功能（第3阶段）：

POST /api/mcp/run_query -具有强制限制的安全CQL查询
POST /api/mcp/jobs/spoiler-scan -开始扰流板扫描作业
GET /api/mcp/jobs/:id -获取工作状态（即将推出）
GET /api/mcp/jobs/:id/result -获取工作结果（即将发布）
GET /api/mcp/cards/:name/relationships -获取卡片关系
GET /api/mcp/types -列出卡片类型
POST /api/mcp/admin/database/backup -创建数据库备份（管理员）
GET /api/mcp/admin/database/backups -列出备份（管理员）
DELETE /api/mcp/admin/database/backups/:filename -删除备份（管理员）

发展

运行测试

# Run all tests
bundle exec rspec

# Run with documentation format
bundle exec rspec --format documentation

# Run specific file
bundle exec rspec spec/magi/archive/mcp/tools_spec.rb

# Run specific test
bundle exec rspec spec/magi/archive/mcp/tools_spec.rb:42

测试覆盖范围： 180个示例，156个通过，14个待定（第3阶段实施）

单元测试 （约165例）：

- 配置：17个示例（环境变量、身份验证方法） - 认证：18个示例（JWT验证、令牌刷新） - 客户端：18个示例（HTTP客户端、重试逻辑、错误处理） - 工具：108多个示例（所有第1-3阶段功能，包括每周总结、验证、关系） - 主：1例

集成测试 （7例）：

- 记录响应形状的合同测试 - 验证API响应格式和错误处理 - 捕获客户端和服务器之间的模式漂移

待定测试 （14例）：

- 高级git存储库扫描场景 - 每周摘要生成中的边缘案例

注：集成测试使用带有记录响应形状的WebLock。对于完整的端到端测试，请使用测试数据在实时Decko实例上运行。

代码质量

# Run RuboCop
bundle exec rubocop

# Auto-fix style issues
bundle exec rubocop -a

在本地构建和安装

# Build gem
bundle exec rake build

# Install locally
bundle exec rake install

# Interactive console
bundle exec rake console

项目结构

lib/magi/archive/
├── mcp/
│   ├── tools.rb           # High-level tools for card operations (all phases)
│   ├── client.rb          # HTTP client for Hyperon Wiki API
│   ├── auth.rb            # JWT verification and token management
│   ├── config.rb          # Configuration management (env vars, defaults)
│   └── version.rb         # Version constant
└── mcp.rb                 # Main module

bin/
└── hyperon-wiki-mcp       # CLI executable

spec/
├── magi/archive/mcp/      # Unit tests (config, auth, client, tools)
├── integration/           # Contract tests with recorded responses
│   └── contract_spec.rb   # API response shape validation
└── support/               # Test helpers and fixtures

错误处理

客户端针对不同的错误情况提出特定的异常：

begin
  card = tools.get_card("Nonexistent Card")
rescue Magi::Archive::Mcp::Client::NotFoundError => e
  puts "Card not found: #{e.message}"
rescue Magi::Archive::Mcp::Client::AuthorizationError => e
  puts "Permission denied: #{e.message}"
rescue Magi::Archive::Mcp::Client::ValidationError => e
  puts "Validation error: #{e.message}"
  puts "Details: #{e.details.inspect}"
rescue Magi::Archive::Mcp::Client::APIError => e
  puts "API error: #{e.message}"
end

异常类型：

NotFoundError -未找到资源（404）
AuthorizationError -拒绝许可（401403）
ValidationError -无效输入（422）
RateLimitError -超出速率限制（429）
APIError -API一般错误（400、500系列）

安全最佳实践

从不提交凭据：使用 .env 敏感数据的文件（gitignored）
使用最小角色：仅请求您的运营所需的角色
令牌管理：库自动处理刷新
仅限HTTPS：始终使用与Decko的安全连接
输入验证：在API调用之前对用户输入进行消毒
速率限制：遵守API速率限制（强制服务器端）

看 MCP_SERVER.md 获取全面的安全指南。

贡献

分叉存储库
创建要素分支(git checkout -b feature/new-feature)
进行更改并添加测试
运行测试和RuboCop(bundle exec rspec && bundle exec rubocop)
以明确的信息提交
推叉并提交拉叉请求

文档

MCP服务器指南 -完整指南：安装、身份验证、工具参考、安全、部署、故障排除
MCP规范 -API规范和协议详细信息
ChatGPT使用指南 -正确的使用模式、常见错误和最佳实践
已知问题 -当前问题、调查和解决方法
开发指南 -Ruby开发指南和项目结构
Claude 代码指南 -人工智能辅助编码开发指南
API文档 -YARD文件

许可证

MIT许可证-请参阅许可证详细信息文件

支持

问题:
讨论:
电子邮件: support@magi-agi.org

版本历史

v0.3.0-第3阶段完成（2024年12月）

第三阶段：高级功能

具有强制限制的安全CQL（卡查询语言）查询
剧透扫描异步作业（GM/admin触发的内容扫描）
通过git存储库集成生成每周摘要
卡片验证和结构建议
全面的关系探索

测试与质量

180次RSpec测试（156次通过，14次待定）
修复了类结构问题（现在已正确包含每周摘要方法）
API响应验证的合同测试
全面的错误处理和重试逻辑

v0.2.0-第二阶段完成（2024年11月）

第二阶段：扩展操作

标签操作（搜索、验证、人工智能辅助建议）
卡片关系探索（引用者、嵌套、链接、linked_by、nested_in）
数据库备份管理（仅限管理员）
内容呈现（HTML↔ Markdown）
类型发现和探索

身份验证改进

用户名/密码验证（除了API密钥）
根据帐户权限自动检测角色
通过用户帐户跟踪实现更好的审计跟踪

v0.1.0-第一阶段完成（2024年10月）

第一阶段：核心基础设施

带RS256验证的JWT身份验证
基于角色的访问控制（用户、总经理、管理员）
具有自动重试和令牌刷新功能的HTTP客户端
卡片的完整CRUD操作
批处理（按项目和事务模式）
全面的错误处理
用于交互式使用的CLI工具

Hyperon Wiki MCP

快速接入

详细介绍