Melbis Shop Guide: contents

3. MCP Server Reference › 3.7 Storefront › Concept

The shop family works with the store from outside: it opens a storefront page the way a visitor gets it, opens a web module the way the program opens it, runs the agent’s own module on the storefront and copies the store’s code onto this computer.

shop_page, shop_module and shop_agent require no rights: they go to the site, not to the engine, and the right to a module is checked by the module itself. One exception: shop_page with debug=true asks the engine for the debugger’s code and therefore requires the right “Get configuration”. shop_download requires the right “Export → Store”.

All the MCP server’s requests — to pages, to agent.php and to core/mcp.php — go from this computer with the User-Agent MelbisShop-MCP. If an access code is set in the store and the user has a license for today, the server appends it to the User-Agent, and the proxy in front of the site lets the requests through by it. The server takes the code before every request from the store’s settings, where the program keeps it — “Installation”, the “Security” section.

The Rules

The family has rules of its own — shop.md in the Engine\MCP folder. The first call of any shop_* tool in a session refuses with them; after they are confirmed through session_rules_accept all the tools of the family work.

The Page

shop_page requests a page the way a visitor’s browser does, and saves the HTML in pages\ of the conversation folder.

A visitor is defined by their cookies and headers. Without cookies a read is a new visit, without cookies and without a session. The answer returns the cookies after the request together with what the site has written, and the next call with them carries on the same visitor. This is how a page is opened with cookies set in advance — for example, with a chosen storefront version or currency — and how one sees what the site writes into the cookies. The request headers are set by headers: a phone’s User-Agent and Sec-CH-UA-Mobile: ?1 open the mobile version where the storefront chooses it by device. The site’s answer headers come in the headers field of the answer.

The page may come from the cache. Saving a module’s file resets the cache of that module only — what clears itself is described in “Configuration and Cache”. If an edit is not visible on the page, the reason is sometimes the cache of another module, the one that prints the changed place.

This is markup, not a picture. From the HTML one sees what has changed in the page’s code; how it looks is seen only by a person in a browser.

The debugger’s report. With debug the page is requested in the debugger’s machine-readable view (“Debugging Tools”): the whole report is saved next to the page, and the main numbers and the page’s modules come in the answer. The debugger’s code the server takes from the store’s configuration, so such a call requires the right “Direct access → Development → Get configuration”. The code gets neither into the answer nor into the file names. If there is no code, the owner sets it: “Development → Installation”, the “Debugger password” field. In the language your program runs in the captions may differ.

The Form

With the field post the call becomes a form submission. That is how everything alive on the storefront works: the cart, a request, a review, an order. Unlike a read, a submission changes the store — rows of the cart appear, requests, letters to the manager, and in a working store a real order too. The storefront has no test mode.

Submissions one after another are one visitor if the cookies are passed on: the next call goes with the cookies from the previous answer. In the demo store the cart answers to the fields func and id:

{"url": "/?mod=melbis_basket", "post": {"func": "Plus", "id": 12}}
{"url": "/?mod=melbis_basket", "post": {"func": "Goods"}, "cookies": {"MELBIS_SHOP": "k3fq9…"}}

The fields of a form are named the way the page’s markup writes them. A list of values goes as name[]=…, one per value — that is how a browser sends checkboxes and a multiple choice, and only so does PHP read the field as an array. The form’s token, if there is one, does not take itself: the page is read first.

The Web Module

shop_module opens a built-in or external web module the way the program opens it: a POST in the name of the session’s user — the server adds login, stamp and sign itself — with the window’s fields that the agent passed. That is how the modules a manager sees in the program’s windows are checked and developed. The answer is saved into modules\ of the conversation folder; with debug the debugger’s report comes, as for a page.

shop_module handles cookies like the page: the module’s session lasts while the agent passes the cookies from the answer to the next call.

A function of the module writes real data in the name of the session’s user: a call with func in a working store is the same action as pressing a button in the program’s window.

Which fields each window passes and how the module authorizes the user — “Web Modules”.

The Agent’s Module

shop_agent runs a module through the entry point agent.php in the site’s root and returns the storefront’s answer. That is how the work is done for which there is no AI tool: a report across several tables, a check of the whole catalog, a one-off edit with a logic of its own.

The entry point runs a module only if:

1. the session key fits — it is given out by session_connect;
2. the module’s name starts with agent_;
3. the module is in units/;
4. the module is an entry point: entry_point: 1 in the manifest, in the program — “Entry point module”.

The session key is one per login: parallel sessions of the same user share it. The store’s server keeps the key in memory for a day, every session_connect extends the term, and a restart of the server wipes the key.

The parameters go the same way as the fields of a form — a list comes as an array — and the module gets them in one serialized argument: post: serial is declared in the manifest, the values lie in $mVars['post'] — see “Modular Scripts”. The service login, secret and mod the entry point removes before running the module.

The answer passes through the parser like any page: templates, tags, cache. The whole of it is saved in runs\<module>.txt of the conversation folder. If the module has fallen, the message, the file and the line the engine writes into the storefront’s log core/log/melbis/front.log.

There are no rights for running. A ready agent_* module can be run by anyone who has signed in to the store; to create or change a module — a user with the right “Direct access → Development → Modify data”.

shop_agent and tool_run

Both run the store’s PHP code, but these are different doors.

tool_run is the working call, shop_agent is the workshop. A draft from the workshop often becomes an AI tool: “AI Tools”.

A Copy of the Store

shop_download is the only tool of the family that takes data from the engine. It collects the archive the same way as “Copying” in the program, and unpacks it on this computer:

config.json never gets into a copy. There is no kind of copy with the element files from files/: they are downloaded by engine_files_load.

A copy is a snapshot at the moment of the call. An edit in it does not go to the server, and later edits of the store do not get into it: the store’s files are changed by the engine_* tools.