ukraine.com.ua MCP

MCP server for the adm.tools / ukraine.com.ua hosting API.

This project is public and is being built around confirmed API behavior from the adm.tools panel and dynamic API documentation.

Current Tools

• adm_get_services: read-only service inventory via POST https://adm.tools/action/get_services/.
• adm_hosting_accounts: read-only hosting account inventory via GET https://adm.tools/action/hosting/account/list/.
• adm_hosting_sites: read-only site/subdomain inventory via POST https://adm.tools/action/hosting/virtual/list/.
• adm_hosting_webapp_info: read-only web-app process/start command info via POST https://adm.tools/action/hosting/account/app/systemd/info/.
• adm_api_catalog_search: search the generated full API catalog.
• adm_api_action_info: inspect generated metadata for one documented action.
• adm_api_call: call any documented action through the generated catalog.
• adm_api_raw: advanced raw call to https://adm.tools/action/{action}/.

Setup

npm install
npm run postinstall:playwright
cp .env.example .env

Set one local token variable:

ADMTOOLS_API_TOKEN=...

UKRAINE_COM_UA_API_TOKEN is also accepted as a compatibility fallback.

Run locally:

npm run build
npm run dev

MCP Client Config

{
  "mcpServers": {
    "ukraine-com-ua": {
      "command": "node",
      "args": ["/absolute/path/to/ukraine.com.ua-mcp/dist/index.js"],
      "env": {
        "ADMTOOLS_API_TOKEN": "your-token"
      }
    }
  }
}

Dynamic API Docs Capture

The authenticated API docs page is:

https://adm.tools/user/api/#/tab-sandbox

Without a session it redirects to auth.adm.tools. The hash route is not sent to the server, so after authentication the capture script navigates back to the full docs URL.

Start a headed browser and save the authenticated storage state:

npm run docs:capture -- --headed --save-auth

Log in manually in the browser window, wait for the API docs page to load, then press Enter in the terminal. Captures are written to .cache/admtools-docs/ and auth state is written to .auth/admtools.json; both are ignored by git.

If bundled Chromium is unstable on your machine, run the same flow with the installed Google Chrome binary:

npm run docs:capture -- --headed --save-auth --browser chrome

This opens a Playwright-controlled Chrome window with an isolated automation profile. Attaching to an already-open personal Chrome window requires Chrome to have been started with a remote debugging port.

For Google OAuth flows that reject automation-controlled browsers, start a separate normal Chrome instance with a local DevTools port:

open -na "Google Chrome" --args \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/.chrome-debug-profile"

Then run the capture against that Chrome:

npm run docs:capture -- --save-auth --cdp http://127.0.0.1:9222

The .chrome-debug-profile, .auth, and .cache directories must stay local and are ignored by git.

Next runs can reuse the saved auth state:

npm run docs:capture

Export a sanitized local index from the captured actions_tree response:

npm run docs:export

Export selected detail docs through the debug Chrome session:

npm run docs:export -- --details --filter '^hosting/account/(list|app/systemd/info)$' --cdp http://127.0.0.1:9222

Export the full docs catalog through the HTTP detail exporter:

npm run docs:export -- --details --http --delay-ms 2500

Exporter output stays in .cache/admtools-docs/ for review before any public documentation is curated.

Generate the public TypeScript/Markdown catalog after exporting details:

npm run docs:generate

See docs/admtools-docs-extraction.md for the extraction workflow.