Web Algebra

Web-Algebra

自然言語による指示を、RDF Linked Data の読み込み、クエリ、書き込みのための JSON 形式のドメイン固有言語オペレーションに変換する、組み合わせ可能な RDF オペレーションシステムです。

概要

このシステムは、RDF Linked Data と SPARQL を管理するための汎用オペレーションに加え、一部の LinkedDataHub 固有のオペレーションを実装しています。オペレーションは次の 2 つの方法で利用できます。

1. 実行可能な JSON 形式：オペレーションを JSON 構造に組み合わせ、付属の実行エンジンで実行します
2. Model Context Protocol（MCP）：AI エージェントが対話的に使用できるツールとしてオペレーションを公開します

エージェントが個々の MCP ツール呼び出しを通じてセマンティックなワークフローを段階的に実行する代わりに、Web-Algebra ではワークフロー全体を最適化された JSON「バイトコード」にコンパイルし、アトミックに実行できます。これにより、複数のオペレーションを組み合わせた複雑な処理が可能になります。

デモ

WebAlgebra の動作をご覧ください。自然言語を RDF オペレーションに変換します。

アーキテクチャ

このシステムは、次の機能を提供する抽象基底クラス Operation を中心に構築されています。

• レジストリーシステム：src/web_algebra/operations/ からオペレーションを自動検出します
• JSON DSL：オペレーションではパラメーターに args を指定した @op キーを使用し、ネストされたオペレーション呼び出しをサポートします
• RDFLib 型システム：適切な RDF 処理のため、内部で URIRef、Literal、Graph、Result 型を使用します
• 実行エンジン：スタンドアロン実行と MCP サーバー統合の両方に対応します
• コンテキストシステム：ForEach オペレーションは行コンテキストを設定し、内部オペレーションは Value を通じてそれにアクセスできます
• URI 解決：ResolveURI オペレーションによって、セマンティクスに沿った URI を適切に構築します

主なコンポーネント

• システムプロンプト：オペレーションの定義と JSON 形式の仕様をすべて記載しています
• 形式意味論：型システムとオペレーションカタログをすべて記載しています
• オペレーションインターフェース：基底クラスと JSON インタープリター
• オペレーションの実装：利用可能なすべてのオペレーションを含むディレクトリ
• 例：実際の Linked Data 上で実行するプラン。それぞれに結果と検証項目が含まれています

オペレーション

オペレーションは、Linked Data の読み書き、SPARQL クエリ、URI 操作、LinkedDataHub 固有のリソース作成に対応しています。以下は一部の一覧です。

• Linked Data
  • GET
  • PATCH
  • POST
  • PUT
• SPARQL
  • CONSTRUCT
  • DESCRIBE
  • SELECT
  • Substitute
  • Values
  • SPARQLString
• スキーマ
  • ExtractClasses
  • ExtractDatatypeProperties
  • ExtractObjectProperties
  • ExtractOntology
• URI と文字列の操作
  • ResolveURI
  • EncodeForURI
  • Concat
  • Replace
  • Str
  • StrUUID
  • URI
• 日時
  • Now
• 制御フローと変数
  • Value
  • Variable
  • ForEach
  • Iterate
  • Filter
  • Bindings
  • Current
  • Position
  • Last
  • Merge
• LinkedDataHub 固有
  • ldh-CreateContainer
  • ldh-CreateItem
  • ldh-List
  • ldh-AddFile
  • ldh-AddGenericService
  • ldh-AddResultSetChart
  • ldh-AddSelect
  • ldh-AddConstruct
  • ldh-AddView
  • ldh-AddObjectBlock
  • ldh-AddXHTMLBlock
  • ldh-RemoveBlock
  • ldh-GeneratePortal
  • ldh-GenerateClassContainers
  • ldh-GenerateOntologyViews

使い方

前提条件

1. uv をインストール

2. uv venv
   uv sync
   

Standalone

Natural language instruction

uv run python src/web_algebra/main.py

次に、指示を入力します。たとえば：

DBpedia からランダムに英国の都市を 10 件選択してください

examples の説明を参照してください。

現在、OpenAI API へのアクセスが必要です。環境変数 OPENAI_API_KEY を設定してください。

JSON を実行する

uv run web-algebra --from-json ./examples/city-profiles/plan.json

examples を参照してください。それぞれに、回答する指示、計画、実行結果、チェックが含まれています。

LinkedDataHub を使用する場合

1. LinkedDataHub v6 を実行します
2. CERT_PEM_PATH および CERT_PASSWORD 環境変数（またはそれらを上書きする --cert_pem_path および --cert_password オプション）に、LDH のオーナー証明書とそのパスワードを web-algebra に指定します。例：

export CERT_PEM_PATH=../LinkedDataHub/ssl/owner/cert.pem
export CERT_PASSWORD="$(cat ../LinkedDataHub/secrets/owner_cert_password.txt)"
uv run web-algebra --from-json ./examples/northwind-category-catalogue/plan.json

ここおよびこのガイド全体を通して、クライアント証明書とそのパスワードが必要なのは、LinkedDataHub で認証する場合のみです。Web Algebra で LinkedDataHub を使用しない場合は必要ありません。

MCP サーバーとして

インストール

uv が必要です。以下を MCP クライアントの設定（例：claude_desktop_config.json）に追加します。

{
    "mcpServers": {
        "web-algebra": {
            "command": "uvx",
            "args": ["--from", "web-algebra", "web-algebra-mcp"],
            "env": {
                "CERT_PEM_PATH": "/path/to/LinkedDataHub/ssl/owner/cert.pem",
                "CERT_PASSWORD": "********"
            }
        }
    }
}

または Claude Code の場合：

claude mcp add web-algebra -e CERT_PEM_PATH=/path/to/LinkedDataHub/ssl/owner/cert.pem -e CERT_PASSWORD=******** -- uvx --from web-algebra web-algebra-mcp

uvx web-algebra mcp でも同じサーバーを実行できます。

環境変数：

名前	必須	説明
CERT_PEM_PATH	いいえ	LinkedDataHub のオーナー証明書（PEM）へのパスです。LinkedDataHub の操作にのみ必要です。
CERT_PASSWORD	いいえ	上記の証明書のパスワードです。
OPENAI_API_KEY	いいえ	OpenAI API キーです。クエリをモデルに記述させる SPARQLString ツールにのみ必要です。

stdio トランスポート

uv run web-algebra-mcp

Streamable HTTP トランスポート

uv run uvicorn web_algebra.server:app --reload

LinkedDataHub を使用する場合は、上記のように CERT_PEM_PATH と CERT_PASSWORD を設定してください。

MCP Inspector の設定

Inspector は次のように起動できます：

npx @modelcontextprotocol/inspector

次に、コンソール出力に表示された URL を開きます。例：

http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=b31e4b3d852b5a2445f45032c484e54e319bf16359585858cf88fe9a90816744

MCP_PROXY_AUTH_TOKEN は必須です。リンクが表示されない場合は、コンソールからセッショントークンをコピーし、Inspector の Proxy Session Token 設定に貼り付けてください。

Web Algebra の設定：

トランスポートの種類

Streamable HTTP

URL

http://127.0.0.1:8000/mcp

ローカルチェックアウトからの Claude Desktop ツール設定

公開済みパッケージの代わりにローカルチェックアウトから MCP サーバーを実行するには、claude_desktop_config.json ファイルの mcpServer 設定に、stdio トランスポートを使用する Web Algebra の項目を追加します。

{
    "mcpServers": {
        "Web Algebra": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/Web-Algebra",
                "run",
                "web-algebra-mcp"
            ],
            "env": {
                "CERT_PEM_PATH": "/path/to/LinkedDataHub/ssl/owner/cert.pem",
                "CERT_PASSWORD": "********"
            }
        }
    }
}

コマンドは変更しないでください。uv run --with の引数は重要です。そうしないと、サードパーティ製パッケージが見つかりません。

私の Mac では、Claude Desktop で動作させるには uv のパスを絶対パスにする必要があります 🤷‍♂️。

CERT_PEM_PATH と CERT_PASSWORD の環境変数は任意です。