PROCESIO

PROCESIO CLI + エージェント

PROCESIO 自動化プラットフォーム向けのコマンドラインツールと AI エージェントです。ターミナルや AI コーディングアシスタントから、プロセス、フォーム、ドキュメント、カスタムアクションを操作できます。

このツールはすべて、公開 API を介して PROCESIO のインストール環境に接続します。ワークスペースを指定し、認証情報をオペレーティングシステム標準のシークレットストアに保存して、ターミナル、スクリプト、AI コーディングアシスタントからプロセス、フォーム、ドキュメント、カスタムアクションを操作します。

• 接続先のプラットフォーム。ワークスペースはここにあります：https://procesio.app
• API とプラットフォームのドキュメント：https://docs.procesio.com
• PROCESIO について：https://procesio.com

インストール

Python 3.11 が必要です。uv が最も手軽ですが、 通常の仮想環境でも同じように動作します。

git clone https://github.com/Procesio-Externals/procesio-cli.git
cd procesio-cli
uv sync

基本インストールは 6 個のパッケージで構成されます。それ以外の重い依存関係はすべてオプションの追加機能で、必要なツールを使う場合にのみインストールされます。

uv sync --extra browser      # real-browser form testing (then: uv run playwright install chromium)
uv sync --extra excel        # reading .xlsx workbooks
uv sync --extra databases    # SQL Server / MySQL queries (pyodbc also needs an ODBC driver)
uv sync --all-extras         # everything

ワークスペースへの接続

認証情報がこのリポジトリ内のファイルに保存されることはありません。Windows 資格情報マネージャー、macOS のログインキーチェーン、Linux デスクトップのキーリングなど、お使いのマシンのストアに agents-and-tools:procesio:<secret> という名前で保存されます。

PROCESIO の認証方法は 2 種類ありますが、互いに同等ではありません。どちらかを名前付きプロファイルとして保存してください。

# Your user account. Carries everything that account can do.
python scripts/run-tool.py procesio add-credential --name account --type userpass     --username [email protected] --make-default

# An API key, scoped to one workspace.
python scripts/run-tool.py procesio add-credential --name qa --type apikey     --workspace-id <workspace-guid>

python scripts/run-tool.py procesio check-auth

--password、--key、--value を省略すると、入力内容を表示せずにプロンプトが表示されるため、シークレットがシェルの履歴やプロセス一覧に残ることはありません。--environment <Client>-<ENV> を追加すると、プロファイルを特定のインストール環境に紐づけられます。

どちらを使うべきか

	ユーザー名とパスワード	API キー
アクセス範囲	アカウントがアクセスできるすべてのワークスペース	1 つのワークスペース
ワークスペース GUID の要否	いいえ	はい。対象自身の GUID が必要で、ほかの GUID は使えません
適した用途	日常的な構築、複数のワークスペースにまたがる作業	CI、1 つの環境に固定したスクリプト、限定的なアクセスの共有

スコープはこのツールではなく、プラットフォームによって適用されます。ワークスペーススコープのキーは、キー名、キー値、workspaceid の 3 つのヘッダーを送信します。このヘッダーを付けずに送信すると 401 が返され、別のワークスペースの GUID を付けて送信した場合も 401 が返されます。そのため、API キーのプロファイルは、認証に必要な workspace_id とともに保存する必要があります。GUID は python scripts/run-tool.py procesio list-workspaces で取得できます。

選択する前に知っておくべき実用上の違いがあります。ユーザープロファイルからは、API キーではアクセスできないエンドポイントにもアクセスできます。たとえば、マスターワークスペースのサブワークスペース一覧は、キーでは 401、ユーザーでは 200 を返します。構築中はユーザーアカウントを優先し、特定のワークスペースに意図的に固定したい場合はキーを使ってください。

ヘッドレスマシンには書き込み可能な OS キーリングがありません。ストアを明示的に選択してください。

export AAT_CREDS_BACKEND=encrypted-file
export AAT_SECRETS_PASSPHRASE='...'      # or you will be prompted on a terminal
python scripts/set-credential.py procesio username

AAT_CREDS_BACKEND=file と =env は、ホストまたはクラスターがすでに管理しているシークレット（マウントされた Kubernetes Secret または 1 つの JSON blob）を読み取ります。設計上読み取り専用なので、コンテナーが読み取り元のストアを所有しているかのように振る舞うことはありません。

最初のコマンド

python scripts/list-tools.py                       # what is installed, and is it ready
python scripts/run-tool.py procesio --help         # every action, with its arguments
python scripts/run-tool.py procesio list-processes
python scripts/run-tool.py procesio run-process --id <process-id> --payload '{}'

各ツールは標準出力に JSON オブジェクトを 1 つだけ出力し、それ以外は何も出力しないため、そのまま jq や別のスクリプトにパイプできます。進行状況と警告は標準エラー出力に送られます。エラーが発生した場合は {"error": {"code", "message", "details"}} を出力し、ゼロ以外の終了コードで終了します。

AI アシスタントからの使用

このリポジトリは、内容を暗記するのではなく、必要なときに見つけられるように作られているため、初めて見るアシスタントでも利用できます。

• CLAUDE.md には、生成された機能ルーターが含まれています。これは、「ユーザーからの依頼」から、それを実行する正確なコマンドへの簡潔な対応表です。マニフェストから python scripts/build-router.py で再生成されるため、コードとの不整合が生じません。
• tools/procesio/SKILL.md は、マニフェストから同じく生成されるツールの完全なマニュアルです。アシスタントは --help の出力を推測する代わりに、これを読みます。
• python scripts/list-tools.py は、どの認証情報が不足しているかを含め、同じ情報を JSON で返すため、アシスタントは「未インストール」と「まだ未設定」を区別できます。

アシスタントにリポジトリのルートを指定し、scripts/run-tool.py を実行させてください。それ以外に必要なものはありません。

Claude Code にプラグインとしてインストールする

コマンドひとつで、Claude Code にツール、MCP サーバー、Agent Skills がまとめて追加されます。クローンも、設定ファイルに書き込むパスも不要です。

/plugin marketplace add Procesio-Externals/procesio-cli
/plugin install procesio@procesio-cli

プラグインは plugin/ フォルダーにあります。MCP サーバーの設定、4 つのスキル、アイコンが含まれています。uvx を通じて、このパッケージの PyPI での正確なリリースを起動するため、マシンに uv が必要です。それ以外は初回実行時に自動で解決されます。認証するには、下記の add-credential を使用してください。クローンがない場合は、uvx --from procesio-cli procesio add-credential ... として実行します。

インストールされる内容は固定されています。 プラグインには plugin/ に小さなランタイムプロジェクトが含まれています。pyproject.toml では procesio-cli のリリースをひとつ指定し、uv.lock ではそれとすべての依存関係をハッシュ付きの正確なバージョンに固定しています。また、サーバーは uvx procesio-cli==<that release> として起動します。ロックファイルに従うインストールでは、そのリリース向けにロックされた内容が正確にインストールされ、その日の PyPI で最新のものがインストールされることはありません。クローンでも constraints.txt と build-constraints.txt を使って同じことができます。これらのファイルでは、Windows、Linux（x86-64 と ARM）、Apple Silicon 上の Python 3.11～3.14 向けに、ビルド済みホイールがあるバージョンへすべてのパッケージを固定しています。Intel Mac は対象外です。cryptography は Intel Mac 向けのホイールを公開しなくなったため、インストールには Rust ツールチェーンが必要です。

Smart App Control が有効な Windows の場合。 Windows 11 では、発行元を確認できない Python ファイルの読み込みが拒否され、ファイルごとに「このアプリの一部がブロックされました」と表示されることがあります。uv が自身のためにダウンロードする Python ビルドは署名されていないため、プラグインはまず、すでにインストールされている Python を uv に使わせます（環境変数 UV_PYTHON_PREFERENCE=system を使用し、バージョンは 3.11 以上に限ります）。インストール済みのものがない場合に限り、uv 独自のビルドを使用します。これらの通知が表示された場合は、python.org から Python 3.11 以降をインストールしてください（例：winget install Python.Python.3.12）。この配布元のファイルには署名があります。インストール後、Claude Code を再起動してください。通知を無視しないでください。拒否されたファイルが Python のネットワークモジュールの場合、どのツール呼び出しも PROCESIO に接続できません。

渡されたツール一覧を確認できます。 MCP サーバーが公開するツールはリリースごとに固定されており、server.json の _meta > io.modelcontextprotocol.registry/publisher-provided > com.procesio/toolsDigest にそのダイジェストが記録されています。このファイルは、MCP Registry にバージョンが登録された後は変更できません。tools/list 呼び出しが返す tools 配列をハッシュ化して比較してください。

import hashlib, json
raw = json.dumps(tools, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
print("sha256:" + hashlib.sha256(raw.encode("utf-8")).hexdigest())

一致しない場合、そのサーバーは該当バージョンで公開された内容を提供していません。サーバーは server/discover でもダイジェストを報告しますが、これはラベルとしてのみ扱ってください。サーバー自身が自分の正当性を保証することはできません。

シェルを使わずに MCP 経由で接続する

webplatform/aat_mcp/ には、同じ基盤上で動作し、用途の異なる MCP サーバーが 2 つあります。どちらも stdio 経由で JSON-RPC を使用します。

	procesio-mcp-chat	procesio-mcp
ツール	21 個、各操作につき 1 つ	6 個、汎用
追加したツールを取り込むか	いいえ、宣言済みのリストです	はい、すぐに取り込みます
用途	各ツールが機能を説明する必要があるチャットクライアント	レジストリ全体を操作すること
起動方法	プラグインが .mcp.json 経由で起動	独自のクライアント設定

MCP Registry から、またはワンクリックバンドルとして。 チャットサーバーは公式 MCP Registry に io.github.Procesio-Externals/procesio-cli として登録されており、各リリースでは GitHub リリースに procesio-mcp-<version>.mcpb が添付されます。そのファイルを Claude Desktop で開くとインストールできます。ホストが uv で Python の依存関係を取得します。どちらもタグを起点とする release ワークフローで生成されます。このワークフローがバンドルのハッシュを埋め込み、server.json を公開するため、レジストリを手作業で編集する必要はありません。

厳選されたインターフェースは、構築するもの（プロセス、フォーム、コネクター）ごとにグループ化されています。呼び出し元から渡されるアクションを受け取るものはないため、リスト内のすべてのツールが、内容を読む人にも、どのツールを使うか選ぶモデルにも分かりやすくなっています。その内容は webplatform/aat_mcp/chat_surface.yaml で宣言されており、CI では、記載されているすべての操作が、指定された引数のまま存在していることを確認します。

短いリストよりも幅広い機能が必要な場合は、汎用インターフェースを使用してください。アクションごとに 1 つのツールを用意するのではなく、6 つのツールを通じてレジストリ全体を公開します。

ツール	機能
capabilities	ツール、エージェント、スキル、または 1 つの機能の引数スキーマ全体を一覧表示します
run_tool	構造化された JSON 引数でツールを実行します
run_agent	エージェントを実行します
run_tool_confirmed、run_agent_confirmed	取り消せないアクションを含め、同じ処理を実行します
get_skill	スキルの Markdown を取得します

レジストリを読み込むため、tools/procesio/ の隣にツールを追加すると、引数スキーマとともにすぐにアシスタントから使えるようになります。そのための連携コードを書く必要はありません。

このチェックアウトにある Python の絶対パスを指定して、MCP クライアントをサーバーに接続してください。

{
  "mcpServers": {
    "procesio": {
      "command": "/abs/path/to/procesio-cli/.venv/bin/python",
      "args": ["/abs/path/to/procesio-cli/webplatform/aat_mcp/server.py"]
    }
  }
}

Windows では、インタープリターは .venv\Scripts\python.exe です。キー名はクライアントごとに異なります（Claude Desktop と Cursor では mcpServers、opencode では "type": "local" を指定した mcp）が、コマンドと引数はどのクライアントでも同じです。コンテナー向けには HTTP トランスポートもあります。python webplatform/aat_mcp/http_server.py --host 0.0.0.0 --port 8901 --token <secret> を実行し、すべてのリクエストに Authorization: Bearer <secret> が必要です。トークンなしでループバック以外にバインドしないでください。

安全性ゲートについて。 run_tool は、可逆性チェックで取り消せないと判定されたアクションを拒否し、approval_required を返して *_confirmed の経路を示します。MCP クライアントはこれらを確認が必要なものとして扱うため、人が副作用ごとに承認でき、モデルが通常のツールを選んでゲートを回避することはできません。チェックの仕組みを理解しておいてください。これはアクション名と引数に含まれる英語の動詞を照合します。認識されている動詞が名前に含まれないアクションは可逆と判定されるため、何も示されないことは、問題がない保証ではなく、証拠がないということです。明らかなミスを防ぐためのガードレールとして扱い、サンドボックスとは考えないでください。また、見落としに気付いたら agents/_lib/reversibility.py に動詞を追加してください。ヘッドレス実行で確認済みのアクションも拒否するには、AAT_MCP_DENY_IRREVERSIBLE を設定してください。

わかりにくいルール

何かを構築する前に、 tools/procesio/PROCESIO-USAGE-GUIDE.mdをお読みください。 このガイドには、知らないと失敗に見えるプラットフォームの挙動がまとめられています。どれも共通点があります。呼び出しは成功し、ステータスは完了を示し、ログには何も記録されず、要求した処理は実行されません。検索してもエラーは見つからないため、見当違いの場所を調べてしまいます。

時間をかけて読む価値があるか判断できるよう、いくつか例を挙げます。Node の<%N%>は値をバインドせず、ソースに直接貼り付けるため、文字列が減算処理になります。Python アクションが返すのはスクリプトが PRINTS した内容だけなので、代入だけでは空の結果になります。また、型付き変数にバインドされた空のフォームコントロールは、画面には何も表示されないまま起動を失敗させます。

このガイドはツール独自のメモから生成されており、ルールとリンクを記載し、根拠はメモに残します。それぞれの事実は一度だけ掲載されています。

エージェント

生の API ツールに加えて、仕組みではなく手法を備えた構築・テスト用エージェントがあります。プロセスを適切に構築する方法、実行中の処理に照らして検証する方法、他の人のフローで注意すべき問題点を扱います。

python scripts/run-agent.py procesio guidance          # the playbook and best practices
python scripts/run-agent.py procesio checklist         # the self-test discipline
python scripts/run-agent.py procesio verify --process-id <id>
python scripts/run-agent.py procesio audit --process-id <id>

CI に組み込む価値があるのはverifyです。プロセスを検証し、デザイナーに表示される内容とランタイムの動作を比較して、プロセスを起動し、インスタンスのステータスを読み取ります。

代わりにブラウザーでセットアップする

セットアップでターミナルを使いたくない場合は、ローカルコンソールを利用できます。

python dashboard/serve.py

このコンソールはループバックインターフェースにのみバインドし、ライブレジストリに登録されたすべてのツール、エージェント、スキルを一覧表示するページを開きます。そこから、認証情報を OS の認証情報ストアに直接保存し（ファイルに書き込まれることはありません）、スキーマ検証済みの設定を編集し、使用可能なツールとシークレットが不足しているツールを確認して、ツールを実行し、動作を確認できます。入力した内容がマシンの外に出ることはありません。

API ドキュメントからコネクターを構築する

カスタムアクションは、プラットフォームの主要な拡張ポイントです。PROCESIO が標準で対応していない API をプロセスから呼び出すために使用します。connector-builderは API ドキュメントをコンパイル済みのカスタムアクションに変換するため、サードパーティの API をプロセスから呼び出せるようにする作業は、C# プロジェクトではなくビルドになります。

ビルダーはconnector-builder.procesio.appでホストされているサービスです。誰でもアカウントを作成できます。事前にこちらから何かを入手する必要はありません。始める前に、次の2点を確認してください。

• **LLM キーはご自身で用意してください。**ビルドパイプラインはモデル上で動作し、当社のプロバイダーアカウントではなく、ご自身のプロバイダーアカウントを使用します。一度設定すれば、ビルダー内から、またはここから利用できます。
• **認証にはacb_ API キー、またはアカウントのメールアドレスとパスワードを使用します。**API キーは長期間有効で、スクリプトでの利用が最も簡単です。ログインでは JWT が発行されます。

python scripts/set-credential.py connector-builder api-key      # acb_...
# or: set-credential.py connector-builder username / password

python scripts/run-tool.py connector-builder set-llm-key --provider anthropic --api-key sk-ant-...
python scripts/run-tool.py connector-builder create-build --api-url <docs-url>     --user-requirements "what the connector should do"

以降は、各段階を覚えるのではなく、エージェントが一連の作業を進めます。

python scripts/run-agent.py connector-builder next-step --build-id <id>

エージェントはビルダーからの確認質問に回答し、計画を承認して、生成とコンパイルを行い、ワークスペースにアップロードする.nupkgを返します。

構築したフォームをテストする

フォームの構築は作業の半分にすぎません。残りの半分について、エージェントのプレイブックは明確です。すべてのタブ、すべてのコントロール、すべてのイベントを実際に操作して確認し、ランタイム診断に問題がない状態になるまで、フォームは完成ではありません。スクリーンショットでは JS エラー、起動の失敗、画面のちらつきはわかりません。

python scripts/run-tool.py web save-session --name mine --url https://forms.procesio.app
python scripts/run-tool.py web run --session mine --url <form-url> --steps @steps.json

結果にはdiagnosticsブロックが含まれ、コンソール出力、ページエラー、失敗したリクエスト、不正なレスポンスが記録されます。ページエラー、コンソールエラー、またはフォーム独自の呼び出しで4xxや5xxがひとつでもあれば、まだ完成ではありません。

ここに含まれるもの

ツールが7つ、エージェントが2つ、スキルが2つ、そしてそのいずれにも該当しないコンポーネントが2つあります。すべてについてはレジストリが正本です。python scripts/list-tools.pyを実行すると、インストール済みのツール、それぞれが公開するアクションの数、不足している認証情報が表示されます。以下の数は、その一覧に基づいています。

ツール

python scripts/run-tool.py <tool> <action> [options] で実行できます。アクションは必須です。--help を指定すると、そのツールが公開しているアクションが一覧表示されます。

ツール	アクション数	機能
procesio	442	プラットフォーム API：プロセス、フォーム、ドキュメント、カスタムアクション、環境、認証情報、スケジュールを扱います。
connector-builder	55	API ドキュメントをコンパイル済みの PROCESIO カスタムアクションに変換します。カスタムアクションはプラットフォームの主な拡張ポイントであり、サードパーティ API をプロセスから呼び出せるようにする最短の手段です。
mysql	9	SQL アクションが接続する MySQL データベースにクエリを実行し、プロセスが実際に書き込んだ内容を確認します。
sqlserver	9	SQL Server でも同じ操作を行います。
web	9	実際のブラウザーを操作します：ページの描画、クリック、入力、スクリーンショットの撮影、実行時診断情報の読み取りを行います。
xlsx	3	プロセスの外部でワークブックを読み取ります。PROCESIO の Node 許可リストには xlsx ライブラリが含まれていません。
framework-map	2	インストール済みのすべての項目を、バイリンガルの 1 ページにまとめて表示します：python scripts/run-tool.py framework-map build。

エージェント

エージェントは手法を担い、仕組みは担いません。python scripts/run-agent.py <agent> <action> で実行します。

エージェント	アクション数	機能
procesio	5	構築とテストを行います：プレイブック、セルフテスト用チェックリスト、稼働中のプロセスに対する検証ゲート、非効率性や堅牢性に関する問題を検出する静的監査を提供します。
connector-builder	4	コネクターの一連の作業を最初から最後まで進めます：情報収集、計画、生成、コンパイル、フィードバックに基づく改善を行います。

スキル

AI アシスタントが説明文から自動的に読み込む知識です。実行するものはありません。python scripts/get-skill.py <name> --content で内容を出力します。

スキル	対象範囲
procesio-platform-advisor	プラットフォームに関する知識：機能、ユースケース、実現可能性の評価、実装の実践方法。
sql-server-optimizer	プロセスが実行する T-SQL をレビューします。フロー変数を SQL テキストに直接埋め込むことは、インジェクションの危険があり、アクション設定としても不適切です。このスキルはそれを検出します。

ツールではない 2 つのコンポーネント

dashboard/ はセットアップコンソールで、python dashboard/serve.py で起動します。レジストリには登録されておらず、run-tool.py 経由では実行されません。

webplatform/aat_mcp/ は MCP サーバーで、あなたではなく MCP クライアントが起動します。上のセクションを参照してください。

レイアウト

tools/procesio/      the API client, DTOs, flow model, layout engine, handlers
agents/procesio/     the build-and-test agent and its doctrine
tools/_lib/          credentials, JSON I/O contract, manifest loading
skills/              knowledge your assistant loads on its own
dashboard/           the local setup console
scripts/             run-tool, run-agent, list-tools, set-credential, build-router
registry.py          manifest discovery; nothing has a hardcoded tool list

ツールは、tool.yaml マニフェスト、エントリーポイント、README を含むディレクトリです。マニフェストが契約となります。レジストリはマニフェストを読み込み、その他すべてはレジストリを読み込みます。tools/procesio/ の隣に独自のツールを追加すると、どこにも登録しなくても list-tools.py とルーターに表示されます。

コントリビューション

イシューやプルリクエストの作成方法、およびこのリポジトリの構成に由来する 2 つのルール（ファイルを移動しないこと、.procesio エクスポートを決してコミットしないこと）については、CONTRIBUTING.md を参照してください。仕組みを簡単に説明すると、このリポジトリは内部モノレポから生成されるため、マージされた変更は上流にコピーされ、次回の公開時に戻ってきます。コントリビューターからは見えませんが、ここでのコミットがまとめて反映される理由はこれです。

セキュリティ上の問題については、イシューを作成しないでください。SECURITY.md を参照してください。

ライセンス

Apache-2.0。LICENSE と NOTICE を参照してください。