本記事ではWebMCPの命令型APIを使って、従業員の検索と従業員の作成、変更、削除を行う４つのWebMCPツールを作成します。
以下のGIF動画で、作成した４つのWebMCPツールを実行しています。
- WebMCPツールsearch_employeesを呼び出し、ACCOUNTING部門の従業員を一覧します。
- WebMCPツールsearch_employeesを呼び出し、SALES部門の従業員を一覧します。
- 作成ボタンをクリックし、従業員の作成フォームを開きます。
- WebMCPツールregister_employeeを呼び出し、従業員を一人作成します。
- レポートの画面に戻ります。
- 作成した従業員を編集するフォームを開きます。
- WebMCPツールupdate_employeeを呼び出し、従業員の給与を8000に更新します。
- レポートの画面に戻ります。
- 作成した従業員を編集するフォームを開きます。
- WebMCPツールdelete_employeeを呼び出し、従業員を削除します。
- レポートの画面に戻ります。
- WebMCPツールはdocumentに登録されるため、ツール内の処理でページを遷移するのは難しい（documentが変わるため）です。できないわけではないようですが、ツールの実行結果がnullになることがあるようです。その場合、ツール実行が成功したのか失敗したのか、WebMCPツールを呼び出したAIに伝わりません。そのため、従業員の編集フォームを開き、WebMCPツールによって従業員の作成、変更、削除を行った後にレポートのページに戻っていません。WebMCPツールの呼び出し元であるAIが、ページのナビゲーションを行ってくれることを期待しています。
- 一般的に、APEXでは編集フォームはモーダル・ダイアログやドロワーとして実装します。モーダル・ダイアログやドロワーは親ページであるレポートのページとdocumentが同じになります。WebMCPツールの登録をフォームのページのページ・ロード時に実行すると、親ページのドキュメントにフォームを開けるたびに同じWebMCPツールが登録されます。回避策はあるようですが手間なので、単純にフォームのページを標準ページとして作成しています。レポートとフォームは別のページとなり、documentもそれぞれのページが持ちます。
WebMCPツールを登録するレポートとフォームのページは、先日の記事で作成したAPEXアプリケーションWebMCP Testに追加します。
ページの作成を開始します。
クラシック・レポートを選択します。
WebMCPツールでの検索に、対話モード・レポートや対話グリッドが持つ機能を実装するのはあまり現実的ではありません。ここでは、WebMCPツールの検索結果と画面上のレポートの表示を一致させることができるクラシック・レポートを選択します。
WebMCPツールのコードにページ番号が含まれています。レポートのページ番号は5、フォームのページ番号は6としておくと、後でコードを変更しなくて済みます。
レポートのページ名はEmployees - WebMCPとして、フォーム・ページを含めるをオンにします。フォームのページ名はEmployee - WebMCPとします。レポートもフォームもページ・モードに標準を選択します。
データ・ソースの表/ビューの名前にEMPを指定します。
次へ進みます。
主キー列1はEMPNO(Number)です。ページの作成を実行します。
以上でレポートとフォームのページが作成されます。
作成されたレポートのページは以下です。
フォームのページは以下です。
最初にレポートのページにWebMCPツールsearch_employeesを作成します。
従業員名または部門名による完全一致を検索の条件とします。検索条件となる従業員名および部門名を入力するページ・アイテムと、検索を実行するボタンを作成します。従業員名のページ・アイテムはP5_ENAME、部門名のページ・アイテムはP5_DNAME、検索ボタンはSEARCHとします。
ページ・アイテムとボタンを配置するリージョンをWebMCP Search Toolとして作成します。タイプは静的コンテンツです。
作成したリージョンにページ・アイテムP5_ENAMEとP5_DNAMEを作成します。タイプはテキスト・フィールドです。両方のページ・アイテムで、詳細の保存されていない変更の警告を無視、セッション・ステートのストレージをリクエストごと(メモリーのみ)に変更します。AIエージェントがページ・アイテムへ検索条件の設定した後、ページ遷移しようとすると警告されます。検索条件は無条件で破棄して良いので、警告が発生しないように無視します。
セッション・ステートのストレージは、ページ・アイテムの値を永続化する必要がない場合は、無駄にリソースを使わないようにできるだけリクエストごと(メモリーのみ)にします。
ボタンSEARCHを作成し、トリガー・アクションとしてクラシック・レポートのリフレッシュを作成します。
識別のアクションにリフレッシュを選択します。影響を受ける要素の選択タイプとしてリージョンを選び、リージョンとしてクラシック・レポートのリージョンEmployees - WebMCPを選びます。
クラシック・レポートに検索条件が反映されるようにします。
ソースのタイプをSQL問合せに変更し、SQL問合せとして検索条件を追加した以下のSELECT文を記述します。
select
e.empno,
e.ename,
e.job,
e.mgr,
e.hiredate,
e.sal,
e.comm,
e.deptno
from emp e
where (:P5_ENAME is null or e.ename = :P5_ENAME)
and (
:P5_DNAME is null
or exists (
select 1
from dept d
where d.deptno = e.deptno
and d.dname = :P5_DNAME
)
)送信するページ・アイテムにP5_ENAMEおよびP5_DNAMEを設定します。
以上で、従業員または部門名を指定して従業員を検索するページが作成できました。
ページを実行すると、手作業による検索動作を確認できます。
WebMCPツールsearch_employeesを作成します。
最初に検索結果をJSONで返すAjaxコールバックを作成します。名前はSEARCH_EMPLOYEESとします。ソースのPL/SQLコードに以下を記述します。
クラシック・レポートと同じ検索結果（列FORM_URLは追加）をJSON配列で返します。
declare
l_result json_object_t := json_object_t();
l_employees clob;
begin
select json_arrayagg(
json_object(
'EMPNO' value e.empno,
'ENAME' value e.ename,
'JOB' value e.job,
'MGR' value e.mgr,
'HIREDATE' value to_char(e.hiredate,'YYYY/MM/DD'),
'SAL' value e.sal,
'COMM' value e.comm,
'DEPTNO' value e.deptno,
'FORM_URL' value apex_page.get_url(
p_page => 6,
p_clear_cache => '6',
p_items => 'P6_EMPNO',
p_values => e.empno,
p_plain_url => true
)
returning clob
)
returning clob
)
into l_employees
from emp e
where (:P5_ENAME is null or e.ename = :P5_ENAME)
and (
:P5_DNAME is null
or exists (
select 1
from dept d
where d.deptno = e.deptno
and d.dname = :P5_DNAME
)
);
l_result := json_object_t();
l_result.put('success', true);
if l_employees is null then
l_result.put('search_result', json_array_t());
else
l_result.put('search_result', json_array_t(l_employees));
end if;
htp.p(l_result.to_clob());
exception
when others then
l_result := json_object_t();
l_result.put('success', false);
l_result.put('message', sqlerrm);
htp.p(l_result.to_clob());
end;
このAjaxコールバックを呼び出すWebMCPツールsearch_employeesを、ページに登録します。ページ・ロード時に実行される動的アクションで、以下のJavaScriptを実行します。
(async () => {
await document.modelContext.registerTool({
name: 'search_employees',
description: 'Lists employee information according to the specified conditions.',
inputSchema: {
type: 'object',
properties: {
ename: {
type: 'string',
description: 'Employee name to search for'
},
dname: {
type: 'string',
description: 'Department to which the employee belongs'
}
}
},
execute: async ({ ename,dname }) => {
try {
apex.item('P5_ENAME').setValue(ename ?? '');
apex.item('P5_DNAME').setValue(dname ?? '');
apex.region('employees-report').refresh();
return await apex.server.process(
'SEARCH_EMPLOYEES',
{
pageItems: [
'P5_ENAME',
'P5_DNAME'
]
}
);
} catch (error) {
return {
success: false,
errorCode: 'REQUEST_ERROR',
message: error.message || 'Employee search request failed.'
};
}
}
});
})();
以上でWebMCPツールsearch_employeesが作成できました。Chrome拡張機能のWebMCP Toolを開き、search_employeesを実行できます。
AjaxコールバックとしてREGISTER_EMPLOYEEを作成します。ソースのPL/SQLコードは以下です。
declare
l_empno emp.empno%type;
l_result json_object_t;
begin
insert into emp (
ename,
job,
mgr,
hiredate,
sal,
comm,
deptno
)
values (
upper(:P6_ENAME),
:P6_JOB,
:P6_MGR,
:P6_HIREDATE,
:P6_SAL,
:P6_COMM,
:P6_DEPTNO
)
returning empno into l_empno;
:P6_EMPNO := l_empno;
l_result := json_object_t();
l_result.put('success', true);
l_result.put('empno', l_empno);
l_result.put('message', 'Employee registered successfully.');
htp.p(l_result.to_clob());
exception
when others then
l_result := json_object_t();
l_result.put('success', false);
l_result.put('message', sqlerrm);
htp.p(l_result.to_clob());
end;
AjaxコールバックとしてUPDATE_EMPLOYEEを作成します。ソースのPL/SQLコードは以下です。
APEXの標準プロセスによるアップデート処理では、チェックサムによる同時実行制御やロスト・ライトの対応が行われています。今回はそこまでの実装はせず、単純に受け取った値でUPDATE文を実行しています。
declare
l_result json_object_t;
begin
update emp set
ename = :P6_ENAME,
job = :P6_JOB,
mgr = :P6_MGR,
hiredate = :P6_HIREDATE,
sal = :P6_SAL,
comm = :P6_COMM,
deptno = :P6_DEPTNO
where empno = :P6_EMPNO;
l_result := json_object_t();
l_result.put('success', true);
l_result.put('empno', :P6_EMPNO);
l_result.put('message', 'Employee updated successfully.');
htp.p(l_result.to_clob());
exception
when others then
l_result := json_object_t();
l_result.put('success', false);
l_result.put('message', sqlerrm);
htp.p(l_result.to_clob());
end;
AjaxコールバックとしてDELETE_EMPLOYEEを作成します。ソースのPL/SQLコードは以下です。
declare
l_result json_object_t;
begin
delete from emp where empno = :P6_EMPNO;
l_result := json_object_t();
l_result.put('success', true);
l_result.put('empno', :P6_EMPNO);
l_result.put('message', 'Employee deleted successfully.');
htp.p(l_result.to_clob());
exception
when others then
l_result := json_object_t();
l_result.put('success', false);
l_result.put('message', sqlerrm);
htp.p(l_result.to_clob());
end;
これらのAjaxコールバックを呼び出すWebMCPツールをページに登録します。
従業員を作成するWebMCPツールregister_employeeは、ページ・アイテムP6_EMPNOがnullのときに作成します。そのため、アクションのクライアント側の条件のタイプにアイテムはnullを選択し、アイテムとしてP6_EMPNOを指定します。
ページ・ロード時に実行される動的アクションで、以下のJavaScriptを実行します。
(async () => {
await document.modelContext.registerTool({
name: 'register_employee',
description: 'Register new employee information.',
inputSchema: {
type: 'object',
properties: {
ename: { type: 'string', description: 'employee name' },
job: { type: 'string', description: 'job' },
mgr: { type: 'string', description: 'empno of the manager' },
hiredate: { type: 'string', description: 'hire date' },
sal: { type: 'string', description: 'salary' },
comm: { type: 'string', description: 'commission' },
deptno: { type: 'string', description: 'departement number' }
},
required: [ 'ename','job','hiredate','sal','deptno' ]
},
execute: async ({ ename,job,mgr,hiredate,sal,comm,deptno }) => {
try {
apex.item('P6_ENAME').setValue(ename);
apex.item('P6_JOB').setValue(job);
apex.item('P6_MGR').setValue(mgr ?? '');
apex.item('P6_HIREDATE').setValue(hiredate);
apex.item('P6_SAL').setValue(sal);
apex.item('P6_COMM').setValue(comm ?? '');
apex.item('P6_DEPTNO').setValue(deptno);
return await apex.server.process(
'REGISTER_EMPLOYEE',
{
pageItems: [
'P6_ENAME',
'P6_JOB',
'P6_MGR',
'P6_HIREDATE',
'P6_SAL',
'P6_COMM',
'P6_DEPTNO'
]
}
);
} catch (error) {
return {
success: false,
errorCode: 'REQUEST_ERROR',
message: error.message || 'Employee registration request failed.'
};
}
}
});
})();
従業員情報を更新するWebMCPツールupdate_employeeと、従業員を削除するWebMCPツールdelete_employeeは、ページ・アイテムP6_EMPNOがnullではないのときに作成します。そのため、アクションのクライアント側の条件のタイプにアイテムはnullではないを選択し、アイテムとしてP6_EMPNOを指定します。
ページ・ロード時に実行される動的アクションで、以下のJavaScriptを実行します。
(async () => {
/*
* This tool updates the information for the employee already selected,
* so P6_EMPNO should not be included as a parameter.
*/
await document.modelContext.registerTool({
name: 'update_employee',
description: 'Update existing employee information.',
inputSchema: {
type: 'object',
properties: {
ename: { type: 'string', description: 'employee name' },
job: { type: 'string', description: 'job' },
mgr: { type: 'string', description: 'empno of the manager' },
hiredate: { type: 'string', description: 'hire date' },
sal: { type: 'string', description: 'salary' },
comm: { type: 'string', description: 'commission' },
deptno: { type: 'string', description: 'departement number' }
}
},
execute: async ({ ename,job,mgr,hiredate,sal,comm,deptno }) => {
try {
ename != null && apex.item('P6_ENAME').setValue(ename);
job != null && apex.item('P6_JOB').setValue(job);
mgr != null && apex.item('P6_MGR').setValue(mgr);
hiredate != null && apex.item('P6_HIREDATE').setValue(hiredate);
sal != null && apex.item('P6_SAL').setValue(sal);
comm != null && apex.item('P6_COMM').setValue(comm);
deptno != null && apex.item('P6_DEPTNO').setValue(deptno);
return await apex.server.process(
'UPDATE_EMPLOYEE',
{
pageItems: [
'P6_EMPNO',
'P6_ENAME',
'P6_JOB',
'P6_MGR',
'P6_HIREDATE',
'P6_SAL',
'P6_COMM',
'P6_DEPTNO'
]
}
);
} catch (error) {
return {
success: false,
errorCode: 'REQUEST_ERROR',
message: error.message || 'Employee update request failed.'
};
}
}
});
/*
* This tool removes the employee currently selected in P6_EMPNO,
* so no parameters need to be specified.
*/
await document.modelContext.registerTool({
name: 'delete_employee',
description: 'delete existing employee information.',
execute: async ({}) => {
try {
return await apex.server.process(
'DELETE_EMPLOYEE',
{
pageItems: [
'P6_EMPNO'
]
}
);
} catch (error) {
return {
success: false,
errorCode: 'REQUEST_ERROR',
message: error.message || 'Employee delete request failed.'
};
}
}
});
})();
以上で、予定していた４つのWebMCPツールの作成は完了です。この記事の先頭のGIF動画で行っている操作を、WebMCPツールを使って実施できます。
今回作成したAPEXアプリケーションの、APEXlang形式のエクスポートを以下に置きました。
https://github.com/ujnak/APEXlang-exports/tree/main/webmcp-test
Oracle APEXのアプリケーション作成の参考になれば幸いです。
完
