Noorle — AI Agent Runtime & MCP Gateways

Noorle プラグインのサンプル

WebAssembly Component Model と WASI 0.2 を使用して、Noorle プラットフォーム用のプラグインを構築する際の、実際のパターンを示す包括的な WebAssembly プラグインのサンプル集です。エクスポートした関数は自動的に MCP ツールになります。設定は不要です。

• 🧩 プラグイン開発ドキュメント
• 🔌 MCP ゲートウェイの仕組み
• 🚀 5 分で始めるクイックスタート
• ⌨️ Noorle CLI

🎯 このリポジトリで紹介する内容

このリポジトリでは、次の内容を紹介する Noorle プラグインの実用的なサンプルを提供しています。

• HTTP API との連携 - OpenWeatherMap、NewsAPI、arXiv、Exchange Rate API を使用した実例
• 複数言語のサポート - Rust、Go、Python、JavaScript、TypeScript による実装
• WASI 0.2 のパターン - セキュアなサンドボックス実行のための最新の WebAssembly System Interface の使用方法
• Component Model - WIT を使用した、型安全で言語に依存しないプラグインインターフェース
• 本番環境向けのパターン - エラー処理、環境設定、テスト戦略

🛠️ 紹介するテクノロジー

• WebAssembly Component Model - 次世代の WASM モジュール構成
• WASI Preview 2 - ネットワーク、ファイルシステム、環境へのアクセスを可能にするセキュアなシステムインターフェース
• WIT (WebAssembly Interface Types) - 言語に依存しないインターフェース定義
• クロス言語コンパイル - TinyGo、ComponentizeJS、componentize-py、cargo-component

📚 こんな方に最適

• Noorle プラットフォーム用のプラグインを構築する開発者
• WebAssembly Component Model のベストプラクティスを学びたい方
• WASI 0.2 の HTTP クライアントパターンを理解したい方
• 複数の言語を使った WASM 開発を試したい方
• セキュアなサンドボックス内で API 連携を構築したい方

各サンプルには、詳細なドキュメント、ローカルでのテスト手順、本番環境でも使えるコードパターンが含まれています。

利用可能なサンプル

🌦️ 天気プラグイン

OpenWeatherMap API からリアルタイムの気象情報を取得します。

5 つの言語に対応：

• Rust - waki HTTP クライアントを使用した高パフォーマンスな実装。プリミティブ型ではない複雑なレコード型を返す方法を紹介します
• Go - WASI HTTP バインディングを使用した TinyGo によるコンパイル
• Python - componentize-py による WASI バインディングの直接使用
• JavaScript - ComponentizeJS を使用したネイティブの fetch() API
• TypeScript - IDE の完全なサポートによる型安全な開発

機能：

• 任意の都市の現在の気象データを取得
• メートル法とヤード・ポンド法の単位系に対応
• 環境変数を使用した安全な API キー管理
• ネットワーク障害に対する堅牢なエラー処理
• ネストされたフィールド（気温、風、天候）を含む複雑な気象レスポンスを返す

📰 ニュースプラグイン

NewsAPI.org を使用して、世界中のニュース記事や最新のヘッドラインを検索します。

対応言語：

• Rust - 構造化レコード型を使用した NewsAPI.org との連携

機能：

• キーワードやトピックでニュース記事を検索
• 構造化された記事データ（タイトル、説明、URL、ソース）を返す
• ネストされた構造を持つ複雑なレコード型を紹介
• レート制限および認証エラーの処理
• 環境変数を使用した安全な API キー管理

💱 為替レートプラグイン

リアルタイムの通貨換算と為替レート情報を提供します。

対応言語：

• Rust - フォールバックに対応した複数の API エンドポイント

機能：

• 任意の基準通貨の現在の為替レートを取得
• 異なる通貨間で金額を換算
• 対応しているすべての通貨を一覧表示
• プライマリ API が失敗した場合、セカンダリ API に自動でフォールバック
• API キーは不要です。無料の通貨データソースを使用します

✈️ Amadeus フライトプラグイン

Amadeus API を使用して、フライトのオファーや旅行情報を検索します。

利用可能な実装：

• Go - 複雑な非プリミティブレコード型の入力を実演する TinyGo 実装

機能：

• 都市間のフライトオファーを検索
• 複雑な検索パラメーター（出発地、目的地、日付、乗客）に対応
• WASI コンポーネントでのネストされた入力構造の処理を実演
• 環境変数を使用した安全な API 認証情報の管理
• 料金や区間を含む詳細なフライト情報を返却

📚 ArXiv プラグイン

arXiv リポジトリから学術論文を検索してダウンロードします。

利用可能な実装：

• Rust - Atom/RSS フィードの解析と PDF のダウンロード

機能：

• arXiv で学術論文を検索
• 論文の PDF を直接ダウンロード
• 著者、要約、カテゴリを含む構造化メタデータ
• feed-rs による効率的なフィード解析

技術スタック

WebAssembly コンポーネントモデル

すべてのプラグインは WASI 0.2 を使用した WebAssembly コンポーネントモデルを採用し、以下を提供します。

• セキュリティ：きめ細かな権限を備えたケイパビリティベースのサンドボックス化
• 移植性：任意の WASI 0.2 ランタイム（wasmtime、wasmer、ブラウザー）で実行可能
• コンポジション：プラグインはコンポーネント間でインターフェースをインポート／エクスポート可能
• 言語非依存：WIT インターフェースによりシームレスな相互運用が可能

言語固有のツールチェーン

Rust

• 最適な WASM 出力のための wasm32-wasip2 ターゲット
• コンポーネントモデルとの統合に使用する wit-bindgen
• WASI ネイティブの HTTP クライアント waki
• バイナリサイズを最小限に抑えた、ゼロコスト抽象化

Go

• 効率的な WASM バイナリを生成する TinyGo コンパイラー
• 型安全なバインディングに使用する wit-bindgen-go
• WASI HTTP インターフェースへの直接アクセス
• WASM 向けに適応した Go らしいパターン

Python

• Python から WASM へのコンパイルに使用する componentize-py
• 外部ライブラリを使用しない WASI HTTP バインディングへの直接アクセス
• 組み込みライブラリを使用したネイティブな JSON 処理
• 型安全性のためのデータクラスと列挙型

JavaScript

• StarlingMonkey ランタイムを使用する ComponentizeJS
• SpiderMonkey（Firefox の JS エンジン）をベースに構築
• ネイティブの fetch() API に対応
• ES モジュールと最新の JavaScript 機能

TypeScript

• コンパイル時チェックによる完全な型安全性
• 2 段階コンパイル：TypeScript → JavaScript → WASM
• IntelliSense と自動補完による IDE サポート
• 型安全な JSON シリアライズ

はじめに

前提条件

Noorle CLI のインストール

プラグインをビルドしてデプロイするには、Noorle CLI をインストールします。

オプション 1：クイックインストール（推奨）

curl -L cli.noorle.dev | sh

オプション 2：プラットフォーム固有のバイナリをダウンロード GitHub Releases から、お使いのプラットフォーム向けの最新リリースをダウンロードしてください。

詳しいドキュメントについては、CLI リファレンスを参照してください。

WebAssembly ツールセット

開発を効率化するため、Noorle プラグインでは標準の WASM ツールセットを使用します。これらは noorle plugin prepare を実行すると自動的にインストールされます。

• wasmtime - ローカルテスト用の WebAssembly ランタイム
• wkg - 依存関係管理用の WIT パッケージマネージャー
• wasm-tools - WebAssembly コンポーネントユーティリティ
• Rust ツールチェーン - 上記のツールに必要です（これらは Rust でビルドされています）

これらのツールは、すべての言語テンプレートのビルドスクリプトで使用され、一貫した WASM コンポーネントの生成を実現します。

クイックスタート

1. リポジトリをクローンします：

git clone https://github.com/noorle/plugin-examples
cd plugin-examples

2. 例と使用する言語を選びます：

cd rust/weather

3. 開発環境を準備します：

# Install required WASM tools (one-time setup)
noorle plugin prepare

# Or check if tools are already installed
noorle plugin prepare --check

prepare コマンドはテンプレートの prepare.sh スクリプトを実行し、次の処理を行います：

• 必要な開発ツールがあるか確認します
• 不足している依存関係をインストールします（許可を求めます）
• WASM 開発用に環境を設定します
• すべてのテンプレートで一貫したツールを利用できるようにします

4. 必要に応じて環境変数を設定します：

cp .env.example .env
# Add your API key to .env

5. プラグインをビルドします：

noorle plugin build

このコマンドはテンプレートの build.sh スクリプトを実行し、次の処理を行います：

• コードを WebAssembly にコンパイルします
• Component Model のバインディングを生成します
• dist/plugin.wasm を生成します
• デプロイ用の .npack アーカイブを作成します

6. ローカルでテストします：

# Example for rust weather plugin (Rust version)
wasmtime run --wasi http --env OPENWEATHER_API_KEY=your_key \
  --invoke 'check-weather("Austin", metric)' dist/plugin.wasm

7. Noorle にデプロイします：

# Authenticate first
noorle login

# Deploy the plugin
noorle plugin deploy

# Or build and deploy in one step
noorle plugin publish

Noorle CLI ワークフロー

Noorle CLI は、プラグイン開発のワークフローを効率化します：

新しいプラグインの作成

# List available templates
noorle plugin list-templates

# Create from template
noorle plugin init my-plugin --template rust

# Interactive template selection
noorle plugin init my-plugin

開発コマンド

# Check/install dependencies
noorle plugin prepare         # Interactive installation
noorle plugin prepare --check  # Check only
noorle plugin prepare --ci     # Non-interactive for CI/CD

# Build plugin
noorle plugin build           # Runs build.sh, creates WASM

# Validate configuration
noorle plugin validate noorle.yaml

# Create deployment package
noorle plugin pack            # Creates .npack archive

デプロイコマンド

# Authentication
noorle login                  # OAuth device flow
noorle logout                 # Clear tokens

# Deploy to platform
noorle plugin deploy          # Deploy existing .npack
noorle plugin publish         # Build + deploy

プロジェクト構成

各プラグインは、一貫した構成に従います：

language/plugin-name/
├── src/ or app.*        # Main implementation
├── wit/
│   └── world.wit        # Component interface definition
├── noorle.yaml          # Plugin permissions and config
├── prepare.sh           # Dependency setup script
├── build.sh             # Build script
├── .env.example         # Environment template
├── README.md            # Detailed documentation
└── dist/
    ├── plugin.wasm      # Compiled WASM component
    └── *.npack          # Deployment archive

主要ファイルの説明

• prepare.sh：開発ツール（wasmtime、wkg、wasm-tools）を確認してインストールします
• build.sh：言語固有のビルドスクリプトで、WASM 出力を生成します
• world.wit：プラグインの API を定義する WebAssembly Interface Types ファイルです
• noorle.yaml：権限、環境変数、メタデータを指定します

実演する主要な概念

HTTP クライアントの統合

• サンドボックス化された WASM コンポーネントから外部 API を呼び出す
• 言語固有の HTTP クライアントのパターン
• タイムアウト処理と接続管理
• リクエストとレスポンスのストリーミング

環境設定

• API キーの安全な管理
• 環境変数による設定
• noorle.yaml での機能ベースの権限設定

エラー処理

• ネットワーク障害に対する堅牢なパターン
• API エラー処理
• Result 型とエラーの伝播
• フォールバックによる適切な縮退動作

JSON 処理

• 外部 API データの解析とシリアライズ
• 型安全なデータ構造
• オプションフィールドと null 値の処理

コンポーネントインターフェースの設計

• 明確な WIT インターフェース定義
• 言語と Component Model 間の型マッピング
• パラメーターを文書化したエクスポート関数
• エラー処理用の Result 型

学習パス

1. Weather Plugin から始める：複雑なレコード型を使って、HTTP 統合と基本的なパターンを学びます
2. News Plugin を試す：NewsAPI の統合、レート制限、構造化データの処理を理解します
3. Exchange Rate を調べる：フォールバック戦略とデータキャッシュを理解します
4. ArXiv Plugin を学ぶ：フィードの解析とバイナリファイルの処理を習得します
5. 言語を比較する：異なる言語で同じ問題に取り組む方法を確認します

ベストプラクティス

セキュリティ

• API キーやシークレットをコードに直接記述しないでください
• 設定には環境変数を使用してください
• noorle.yaml では最小限の権限を指定してください
• 外部データをすべて検証してください

パフォーマンス

• 用途に適した言語を選んでください
• バイナリサイズを最適化してください（特に TinyGo/Rust）
• 適切な場合はキャッシュを実装してください
• 大きなレスポンスにはストリーミングを使用してください

エラー処理

• 常に Result 型を返してください
• 意味のあるエラーメッセージを提示してください
• 一時的な障害に対してリトライロジックを実装してください
• 重要なサービスにはフォールバック機構を追加してください

開発

• 包括的なテストを作成してください
• エクスポートするすべての関数を文書化してください
• 言語固有の慣用的な書き方に従ってください
• 利用できる場合は型安全性を活用してください

貢献

皆さまからの貢献を歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。

新しい例の追加

1. 実用的なユースケースを選びます
2. 少なくとも 1 つの言語で実装します
3. 充実した README を含めます
4. テストとドキュメントを追加します
5. 既存のパターンと構成に従います

リソース

• Noorle CLI リファレンス
• WebAssembly コンポーネントモデル
• WASI 0.2 仕様
• WIT インターフェース型

ライセンス

MIT ライセンス（Noorle プラットフォームに関する追加条項付き）

Copyright (c) 2024 Noorle

本ソフトウェアおよび関連するドキュメントファイル（以下「本ソフトウェア」）の複製を入手したすべての人に対し、使用、複製、変更、結合、公開、配布、サブライセンス、および／または販売する権利を含む、本ソフトウェアを無制限に取り扱う権利を無償で許可します。また、本ソフトウェアを提供された人に同様の権利を許可することを認めます。ただし、以下の条件に従うものとします。

上記の著作権表示および本許可表示は、本ソフトウェアのすべての複製または実質的な部分に含めるものとします。

Noorle プラットフォーム統合に関する追加条項：

• これらのサンプルは Noorle プラットフォーム向けに最適化されており、同プラットフォームで公式にサポートされています
• Noorle にデプロイする場合、プラグインは Noorle の利用規約に準拠する必要があります
• Noorle チームは、プラットフォームのドキュメントやプロモーションにこれらのサンプルを使用する場合があります

本ソフトウェアは「現状有姿」で提供され、明示的か黙示的かを問わず、商品性、特定目的への適合性、および権利非侵害の保証を含むがこれらに限定されない、いかなる種類の保証もありません。契約、不法行為、またはその他の行為に基づくかを問わず、本ソフトウェア、その使用、またはその他の取り扱いに起因または関連して発生したいかなる請求、損害、その他の責任についても、著作者または著作権者は一切責任を負わないものとします。

サポート

• GitHub の課題
• Noorle ドキュメント