quario

@quario/mcp

エージェントが JSON データを PDF、Excel、Word、HTML、CSV のレポートに変換できます。 この MCP サーバーは、Claude やその他の MCP クライアントに 2 つのツールを提供します。validate_report はレポート定義をチェックし、render_report はそれをファイルに書き出します。1 つの定義から 5 つの形式すべてを生成でき、エージェントに返されるのはパスであり、ファイルのバイト列ではありません。

• 5 つの形式。 1 つの JSON 定義から、pdf、xlsx、docx、html、csv を生成できます。
• 修正可能なエラー。 各問題には、data: expected a JSONPath string のように、発生箇所のパスが示されます。エージェントはその箇所を修正して再試行します。
• バイト列ではなくファイル。 render_report はディスクに書き込み、パスとサイズを返します。サイズにかかわらず、レポートがエージェントのコンテキストを消費するのは 1 行だけです。
• ホストが制御を維持します。 クエリの予算、リンクスキーム、データルート、出力ディレクトリは起動設定で指定します。ツールの引数でこれらを変更することはできません。
• 上書きしません。 同名のファイルがある場合は、-1、次に -2 のように番号が付加されます。
• ローカルで動作します。 stdio 経由で実行され、npx @quario/mcp で起動できます。

render_report の呼び出しとその結果：

{
  "definition": {
    "data": "$.orders[*]",
    "detail": { "columns": [{ "header": "Total", "value": "{{ @.price * @.qty }}" }] }
  },
  "target": "pdf",
  "data": { "orders": [{ "price": 250, "qty": 2 }] },
  "filename": "orders"
}

ツールは Wrote orders.pdf (1.3 kB): /tmp/quario-mcp/orders.pdf と応答します。

サーバーはオープンソースです。サーバーが実行するエンジンはオープンソースではありません。 このパッケージは Apache-2.0 です。quario と 5 つのレンダリング先をインストールします。これらのパッケージはQuario Licenseに基づく商用ソフトウェアです。評価利用は無料です。 ライセンスキーがない場合、すべてのレンダリングに未ライセンスのマークが付きます。

目次

• はじめに
• 設定
• 信頼境界
• validate_report
• render_report
• 今回のリリースに含まれないもの
• 開発
• ライセンス

---

はじめに

1. Node を確認します。 サーバーには Node 22 以降が必要です。

node --version

2. サーバーをクライアントに追加します。 パッケージにはエンジンと 5 つのレンダリング先が含まれているため、ほかにインストールするものはありません。

キーなしで評価利用する場合の Claude Code：

claude mcp add quario -- npx -y @quario/mcp

ライセンスキーを使用する場合の Claude Code：

claude mcp add quario -e QUARIO_LICENSE=quario_... -- npx -y @quario/mcp

claude_desktop_config.json で設定する Claude Desktop：

{
  "mcpServers": {
    "quario": {
      "command": "npx",
      "args": ["-y", "@quario/mcp"],
      "env": { "QUARIO_LICENSE": "quario_..." }
    }
  }
}

キーなしで評価利用する場合は、env 行を省略してください。

3. レポートを依頼します。 クライアントを再起動し、エージェントにレポートを依頼します。

次の注文の PDF を、商品列と合計列付きで作成してください：Desk、250、数量 2。

エージェントは、書き出したファイルのパスを返します。QUARIO_OUT_DIR が設定されていない場合、ファイルはシステムの一時ディレクトリ内にある quario-mcp に保存されます。

4. ファイルを読み取れるようにします（任意）。 インラインデータはどこでも利用できます。エージェントが dataPath で JSON ファイルを渡せるようにするには、そのファイルを含むディレクトリを QUARIO_DATA_ROOT に設定します。Claude Code は CLAUDE_PROJECT_DIR を設定し、QUARIO_DATA_ROOT が未設定の場合、サーバーはその値を使用します。

---

設定

サーバーは環境変数から設定を読み取ります。フラグも設定ファイルもありません。変数が空の場合は、未設定として扱われます。

変数	設定内容	未設定の場合
QUARIO_LICENSE	ライセンスキー	ライセンスなしとなり、出力にマークが付きます
QUARIO_LOCALE	デフォルトの locale	en-US
QUARIO_CURRENCY	デフォルトの currency	なし
QUARIO_TIME_ZONE	デフォルトの timeZone	UTC
QUARIO_SCHEMES	href のスキーム（カンマ区切り）	https:,mailto:
QUARIO_MAX_DEPTH	クエリ予算、または Infinity	500
QUARIO_MAX_NODES	クエリ予算、または Infinity	上限なし
QUARIO_MAX_RESULTS	クエリ予算、または Infinity	上限なし
QUARIO_DATA_ROOT	dataPath の解決先ディレクトリ	CLAUDE_PROJECT_DIR。未設定なら dataPath の解決に失敗します
QUARIO_OUT_DIR	サーバーの書き込み先ディレクトリ	システムの一時ディレクトリ内の quario-mcp

サーバーが実行できない値があると、起動時に停止します。 メッセージは stderr に出力されます。これには、解析できない予算値、エンジンが拒否するスキーム、存在しないデータルート、サーバーが作成または書き込みできない出力ディレクトリが含まれます。例外は、検証に失敗したライセンスキーです。この場合、サーバーは起動し、出力にマークが付きます。

信頼の境界

環境に設定される設定の主体はホストです。ツールを呼び出すエージェントは作成者であり、エンジンは作成者を信頼できないものとして扱います。そのため、ツールの引数からホスト設定に到達することはありません。クエリ予算、href のスキーム、登録済み関数、フォント、ライセンスキー、データルート、出力ディレクトリは、すべて環境変数からのみ設定されます。

例外は locale、currency、timeZone、およびターゲットオプションです。これらはレポートの見た目を変えるだけで、サーバーが読み取り、実行、書き込みできる内容には影響しないため、呼び出し時に設定できます。

---

validate_report

定義をレンダリングせずに読み取り、問題がないか確認します。

フィールド	型	備考
definition	object	必須
targets	array of "html" | "pdf" | "xlsx" | "docx" | "csv"	任意。各ターゲットに対して required を確認します

definition フィールドには、説明も含め、レポートドキュメントの完全な JSON Schema が含まれます。そのため、エージェントはツール自体からドキュメントの意味を読み取れます。サーバーはこのスキーマに照らしてエンベロープを読み取り、定義を検証せずにエンジンへ渡します。エンジンは問題のある箇所のパスに、問題を 1 件報告します。失敗したすべてのサブスキーマを列挙するスキーマの報告よりも、こちらのほうがエージェントにとって有用です。

問題は成功した結果であり、エラーではありません。結果には { problems, warnings } を含む structuredContent と、同じオブジェクトを JSON として格納した 1 つのテキストブロックが含まれます。一方のクライアントは構造化されたコピーをモデルに渡し、別のクライアントはテキストを渡すため、どちらのコピーにも完全な内容が含まれます。

• 問題は { path, source?, message, code?, start?, end? } です。エンジンに位置情報付きの診断がある場合、code、start、end がそこから取得されます。
• 警告は { path, message } です。

render_report

定義を 1 つのターゲットにレンダリングし、出力をファイルに書き込みます。

フィールド	型	備考
definition	オブジェクト	必須
target	"html" | "pdf" | "xlsx" | "docx" | "csv"	必須
data	任意の JSON 値	data と dataPath のいずれか一方だけを指定してください
dataPath	文字列	データルート内の JSON ファイル
params	オブジェクト	任意。定義の params に渡す値
locale	文字列	任意。この呼び出しでは QUARIO_LOCALE を上書きします
currency	文字列	任意。この呼び出しでは QUARIO_CURRENCY を上書きします
timeZone	文字列	任意。この呼び出しでは QUARIO_TIME_ZONE を上書きします
filename	文字列	任意。ベース名。詳細は以下を参照してください
options	オブジェクト	任意。xlsx の page、meta、filter

このツールは定義をターゲットに合わせてプランニングするため、そのターゲットで失われる required 宣言があると問題になります。問題のある定義は、validate_report と同じ { problems, warnings } を isError として返します。

options はターゲットファクトリーに渡されます。サーバーは fonts と paths を拒否します。不明なキーがあると、ファクトリー独自のメッセージをエラーとして返します。csv ターゲットはオプションを受け取りません。

レンダリングデータ

• data と dataPath のいずれか一方だけを指定してください。両方を指定した場合、またはどちらも指定しなかった場合はエラーです。
• dataPath はデータルート内に解決されます。サーバーはシンボリックリンクの解決後にパスを検査するため、リンクを使ってルート外に出ることはできません。データルートがない場合、サーバーは dataPath を拒否します。
• ファイルには JSON が格納されている必要があります。解析できないファイルの場合、サーバー独自のメッセージが返され、ファイルのテキストが返されることはありません。
• 画像は次の 2 つの形式のいずれかで渡します。{ "$image": "assets/logo.png" } はデータルート内のファイルを指定します。{ "$base64": "<base64>" } はバイトデータをインラインで渡します。base64 の画像は呼び出しのたびにエージェントのコンテキストを消費するため、$image を推奨します。
• キーが $image または $base64 だけのオブジェクトは、レンダリング前にバイトデータにデコードされます。これは、インラインデータでもファイル内でも、あらゆる階層で行われます。定義では通常どおり、バイトデータを =$.input.logo として読み取ります。
• $image のパスは、dataPath ファイル内の場合も含め、データルートを基準に解決されます。サーバーはシンボリックリンクの解決後にパスを検査します。ファイルは PNG または JPEG である必要があります。サーバーはそれ以外のファイルを読み取りません。そのため、データファイルの参照を使って任意のファイルをドキュメントにコピーすることはできません。データルートがない場合、サーバーは $image を拒否します。
• データから同じファイルが何度参照されても、サーバーは各ファイルを 1 回だけ読み取ります。
• 拒否された場合は、$.input.logo のようにデータ内のパスを示すエラーが返されます。これは、base64 ではない文字列や、存在しない、ルート外にある、または画像ではない $image に適用されます。

出力ファイル

すべてのターゲットはファイルを書き込み、その内容ではなく場所を返します。

• ファイルは QUARIO_OUT_DIR に出力されます。
• filename はベース名です。区切り文字を含まず、.. でもない必要があります。サーバーはターゲットの拡張子を強制します。filename を指定しない場合、名前は report-<timestamp>.<ext> になります。
• サーバーは既存のファイルを上書きしません。名前がすでに存在する場合は、末尾に -1、次に -2 のように連番を付けます。
• 結果には { path, target, bytes } を含む structuredContent と、Wrote <name> (<size>): <absolute path> というテキストが含まれます。

---

今回のリリースには含まれません

登録済みの関数、ホストフォント、リモートトランスポート。

---

開発

npm run check はローカルでの必須チェックです。フォーマット、リント、デッドコードチェック、サイズ上限、ユニットテストと型チェックの各スイート、複雑度チェックを実行します。CI でも同じチェックを実行します。ローカルで check が成功すれば、プルリクエストでも成功します。

このリポジトリの規約は AGENTS.md に記載されています。読者が最も元に戻してしまいそうな決定事項は docs/adr に記載されています。

---

ライセンス

Copyright 2026 Robin van der Vleuten

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

このサーバーがインストールする quario および @quario/* パッケージには、それぞれ独自のライセンスがあります。各パッケージの LICENSE ファイルを参照してください。