# Conviu MCP Server

> MCP (Model Context Protocol) server for the Conviu platform. It gives AI assistants a single, secure interface to a Conviu organization's data sources (imports), data writer jobs (exports) and products. Every tool acts with the caller's own identity and permissions.

This file follows the llms.txt convention (https://llmstxt.org). The tool names and descriptions below are public; calling any tool requires an authorized MCP session.

## Connecting
- MCP endpoint: https://mcp.conviu.io/mcp (Streamable HTTP transport)
- Authentication: OAuth 2.0. Protected-resource metadata (RFC 9728): https://mcp.conviu.io/.well-known/oauth-protected-resource

## Resources
- Full tool catalogue with parameters (JSON): https://mcp.conviu.io/tools.json
- Product documentation: https://napoveda.conviu.cz
- Human-friendly overview: https://mcp.conviu.io/

## Tools
- **add_data_writer_job** — read-write. Create a new export (data writer job) that takes one or more existing imports (data queries) and writes them out in a chosen format to a destination (Conviu internal storage, FTP, API). Provide the source data query uids, the output format, the destination (writer), and a schedule.
- **add_data_writer_job_rule** — read-write. Create a new export rule on a data writer job. First follow get_workflow(create_export_rule). The group is derived from the single `settings` branch. Settings element references and export-field FQL both use the exact full `fields` key from get_data_writer_job (FQL wraps it in single quotes); dynamic keys are validated again before writing. The tool always stores conditions in RULES mode.
- **clone_data_source** — read-write. Create copies of one or more existing data sources (pass an array of UID32s).
- **clone_data_writer_job** — read-write. Create a copy of one or more export jobs with all their rules.
- **clone_data_writer_job_rule** — read-write. Create a copy of one or more export rules, optionally into a different job.
- **create_data_source** — read-write. Create a new data source to import product data from an external feed (XML, CSV, JSON, API). The `configuration` is a composite object { reader, formatter, import } — reader-specific keys (the url, etc.) go under `configuration.reader`, NOT at the top level.
- **delete_data_source** — read-write. DESTRUCTIVE: Permanently delete a data source and all its imported data. This action cannot be undone.
- **delete_data_writer_job** — read-write. WARNING: Permanently deletes an export job and all its rules. This action cannot be undone.
- **delete_data_writer_job_rule** — read-write. WARNING: Permanently deletes one or more export rules. This action cannot be undone.
- **detect_feed_format** — read-only. Detect the format of a feed from its URL by analyzing its structure. Returns ranked candidates { formatSmallUid, name, countryCode, confidence } plus the content type (xml/csv/json/xlsx). Use this FIRST when the user provides a feed URL for a new import: a single high-confidence candidate just needs the user's confirmation; several equal candidates mean structurally identical formats — ask the user to pick (2-4 options). The feed is downloaded for analysis, so a very large feed can take a little while.
- **edit_data_writer_job** — read-write. Update an existing export (data writer job): its name, schedule, output format, destination, compression, which items it exports, its "block export when…" guard conditions (blockWhen), or its source imports. Pass dataWriterJobUid plus ONLY the fields you want to change — everything else (including the full existing configuration) is preserved automatically.
- **edit_data_writer_job_rule** — read-write. WARNING: Modifies an export rule. First follow get_workflow(edit_export_rule). Pass only changed top-level metadata; omit `settings` for metadata-only edits. If settings changes, supply its complete input-valid branch rather than raw get output or a nested patch. The tool preserves omitted values (including the rule's conditions editing mode), sends core a full normalized replace, validates exact parent-job field keys, enforces the immutable group, and keeps BULK_EDIT conditions empty.
- **get_data_source** — read-only. Get full configuration and status details of a single data source by UID.
- **get_data_source_formats** — read-only. List the supported data formats (XML, CSV, JSON, etc.), optionally filtered by direction, reader type, or object definition type. Returns the full matching set (name-ordered) so you can find a specific format and read its exact smallUid — it is not truncated. IMPORTANT: some formats are country-specific and share the SAME name (e.g. several "UPgates" entries that differ only by country); use the returned `country` field to pick the right one (e.g. country code SK vs PL) and take that entry's smallUid.
- **get_data_source_job_logs** — read-only. Get import execution logs with timing and error details for a data source.
- **get_data_source_readable** — read-only. Test whether a given URL/configuration is accessible and returns valid data before creating a data source.
- **get_data_source_readers** — read-only. List available reader types (connection methods) for importing data into Conviu. Each reader includes a configurationSchema describing the keys to put under "configuration.reader" when calling create_data_source/update_data_source with that readerType (the configuration is a composite { reader, formatter, import } object).
- **get_data_source_writers** — read-only. List available writer types (output destinations) for exporting data from Conviu. Each writer includes a configurationSchema describing the keys to put in the "configuration" object when calling add_data_writer_job/edit_data_writer_job with that writerType.
- **get_data_writer_job** — read-only. Get export job details including state, schedule, AI/translation flags, item count, output links, `fields` and `variables`. In `fields`, the map KEY is the full element path (segments joined by " > ") and each record reports `hasChildren` plus a `label` that is IDENTICAL to the key; rule SETTINGS take that key verbatim, never shortened to its last segment. A field in rule FQL has exactly TWO valid forms: `%variable%` (PREFERRED) — an exact `name` from `variables`, percent signs INCLUDED, reading the item source data; or `'FULL > PATH'` — an exact `fields` key in single quotes (key "SHOPITEM > EAN" becomes `'SHOPITEM > EAN'`) — reading the rendered output, only when the user asks about the finished feed or no variable fits. Anything else silently never matches. `list_data_queries` returns neither catalogue.
- **get_data_writer_job_latest_download_logs** — read-only. Get recent export download activity for monitoring external access.
- **get_data_writer_job_latest_validation** — read-only. Get the most recent data feed validation result for a data writer job.
- **get_data_writer_job_logs** — read-only. Get export execution history with timing and error details.
- **get_data_writer_job_rule** — read-only. Get single export rule details including conditionsType, typed settings, applicability dates, the parent job with its exact output `fields`, and the `variables` catalogue its conditions can filter on. Settings paths are exact `fields` map keys, never shortened to the last segment. A field in rule FQL has exactly TWO valid forms: `%variable%` (PREFERRED) — an exact `name` from `variables`, percent signs INCLUDED, reading the item source data; or `'FULL > PATH'` — an exact `fields` key in single quotes — reading the rendered output, only when the rule targets the finished feed or no variable fits. Anything else silently never matches. The `settings` output materializes null branches and output-only helpers, so never send it back verbatim. When editing metadata only, omit `settings` from edit_data_writer_job_rule and the tool safely projects the current configuration.
- **get_data_writer_job_validation** — read-only. Get full detail of a specific data feed validation by its UID.
- **get_documentation_page** — read-only. Return the full text of a Conviu help page by its path (as returned by search_documentation), for when a search passage is not enough and you need the complete page.
- **get_module_jobs_by_data_source** — read-only. List all module jobs (data writer jobs, campaigns, pricing calculators, etc.) connected to a data source.
- **get_organization** — read-only. Returns key details about a Conviu organization: name, active status, subscription info, billing period, and data source presence. Provide either uid (UID32) or smallUid (UID10) to identify the organization.
- **get_organization_modules** — read-only. Returns the status of every Conviu module an organization uses (product import/export, pricing calculator, bidding, competition monitoring, marketplaces, PPC advertisement, …) — the same overview the Conviu dashboard shows. Use it to answer "how is my organization doing?", to spot which module needs attention, or to sweep several organizations for problems. Pass locale to get titles and messages in the user's language (whoami returns it). Each module reports: title (the human module name), status (an internal code — 'error' | 'warning' | 'success' | 'info' — describe it in plain words, never show the code itself), statusMessage and primaryMessages (ready-made human explanations of what is wrong), lastUpdatedAt, dataObjectDefinitionType, and route — the app page for that module or problem, as { name, parameters } where parameters carry ids such as uid, so a client can link the user straight to the affected import, export or campaign.
- **get_workflow** — read-only. Fetch the step-by-step playbook for a multi-step Conviu task BEFORE you start it, so you collect exactly the right information, in the right order, every time. Call this FIRST — before any other tool — whenever the user wants to perform one of the available workflows. Available workflows: create_import (create a new data source / import), create_export (create a new export / data writer job from existing imports), create_export_rule (create a rewriting/filtering rule on an export), edit_import (change an existing data source / import), edit_export (change an existing export / data writer job), edit_export_rule (change an existing export rule), diagnose (find out why an import or export is not working and fix it).
- **list_data_connector_accounts** — read-only. List connected external accounts (Google, Shoptet, Upgates, Heureka, Kaufland, Allegro, etc.) for an organization. Use this to obtain the connectorAccountUid required by marketplace/API reader and writer configurations. Returns uid, name, valid, and connector { code, name, accountRequired }.
- **list_data_queries** — read-only. List the data queries available as the SOURCE of an export (data writer job). Each existing import has a data query — pass the chosen ones' "uid" values as dataQueryUids when calling add_data_writer_job. Returns uid, name, type, itemCount and the backing dataSource (uid, active, state).
- **list_data_sources** — read-only. List all data sources for an organization with optional filtering, sorting and pagination.
- **list_data_writer_job_rules** — read-only. List all export rules for a job with their configuration, status, and position. Returns totalCount.
- **list_data_writer_jobs** — read-only. List all export jobs for an organization with their state, schedule, and item counts. Supports FQL filtering, sorting, and offset/limit pagination. Returns uid, name, state, active, schedule, lastWrittenAt, processArtificialIntelligence, processTranslation, itemCount, and totalCount.
- **list_items** — read-only. Lists data items (products or other objects) for a Conviu organization. Supports FQL filtering, sorting, and offset/limit pagination. Returns item id, dataSourceUid, approval status, manual flag, data fields, customData, variables, and totalCount.
- **list_organizations** — read-only. Lists the Conviu organizations the currently authenticated user has access to. Supports an optional search string (matches name, or exact smallUid / uid), sorting (name, createdAt, active) and offset/limit pagination. Returns each organization's uid, smallUid, name and active status, plus totalCount.
- **search_documentation** — read-only. Search the official Conviu help documentation (Czech) for how-to and conceptual questions about using Conviu — features, settings, step-by-step guides, troubleshooting. Returns the most relevant passages with their page title and public URL. Use this to ground product advice in the docs instead of guessing; use the data tools (not this) for the user's own imports, exports and items.
- **set_data_source_active** — read-write. Enable or disable automatic imports for a data source. CAUTION: Disabling stops all scheduled processing for this source.
- **set_data_writer_job_active** — read-write. Enable or disable automatic export job execution. WARNING: Setting active=false stops all scheduled executions.
- **set_data_writer_job_rule_active** — read-write. WARNING: Enable or disable an export rule. Disabled rules are skipped during execution.
- **trigger_data_source** — read-write. TRIGGERS an immediate data source import outside the regular schedule. Use for testing or urgent refreshes. This starts a real import job.
- **trigger_data_writer_job** — read-write. WARNING: Manually triggers immediate job execution outside the regular schedule. This starts a real export run.
- **trigger_data_writer_job_validation** — read-write. WARNING: Manually requests a data feed validation run for the specified data writer job.
- **update_data_source** — read-write. Update an existing data source (import): its name, schedule, format, connection details (e.g. the feed URL), or import settings. Changes take effect on the next import. Pass organizationUid + dataSourceUid plus ONLY the fields you want to change — everything else (including the full existing configuration and any custom-format field mapping) is preserved automatically. Reader-config changes go under `reader` (e.g. { "url": "…" }), import-level changes under `import`.
- **whoami** — read-only. Returns basic profile information about the currently authenticated Conviu user (email, name, locale). Takes no arguments.