Percona Data Catalog Agent

A Claude plugin that turns the Percona Notion Data catalog into a full conversational interface. Look up measures, search by topic, propose new entries, edit existing ones, expire what's no longer relevant — and query a tamper-evident audit log of every change, all from inside Claude.

What you can do once it's installed

• "What is Software attribution?" → measure card with status, owners, source system(s), description, formula / logic, reporting locations, and a direct Notion link.
• "Do we have a measure for churn?" → ranked list of relevant catalog entries, with a relevance gate that drops false positives.
• "Where does the ServiceNow task priority data come from?" → source system(s) and the formula verbatim.
• "Add a measure called 'Pipeline coverage', sourced from Salesforce, owned by Sales." → guided propose flow with tag normalisation and a required "why". Defaults to Status = Proposed — Validated is a separate human step.
• "Update 'Software attribution' to add the tag gtm." → diff preview, explicit confirmation, then write.
• "Expire 'ServiceNow task priority' — it's been replaced." → flips Status to Expired and appends the reason to Notes/Updates. Keeps the entry in the catalog for historical context.
• "Remove this test measure entirely." → stronger than expire. Moves the page out of the catalog DB and into a sub-page of the audit log as an archive. Double-confirmation required.
• "Show me everything Filip did this week." → audit-log query.
• "What is Foo Bar Baz?" (not in the catalog) → honest "I couldn't find that" — never a hallucinated definition.

Every interaction lands as exactly one row in Data catalog — audit log.

Prerequisites

1. Claude Desktop with plugin support enabled.

2. Notion connector connected in your Claude settings. The plugin uses your Notion identity — whatever you can see and edit in Notion is what the plugin can show and change for you. Writes only succeed if your Notion account has permission to write the Data catalog DB.

3. uv — Python package manager used to launch the bundled MCP servers (currently servicenow). Install with:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   Restart Claude Desktop after installing so it picks up uv on PATH. Without uv the bundled MCP servers won't start and live data queries (S14 / S15) will be unavailable in your session.

4. Percona VPN — required to reach sherpa.tp.int.percona.com, the centralized server the bundled MCP proxies to. Sherpa holds the shared API key, so individual users don't need per-user ServiceNow credentials.

Items 1 and 2 are required for the catalog half of the plugin (lookup, search, propose, edit, expire, remove, audit-query) to work. Items 3 and 4 are only needed for live data queries against ServiceNow / ClickHouse / Elasticsearch. If uv or VPN is missing, the agent will detect it the first time you ask a question that depends on the missing piece and reply with a one-line remediation — nothing happens silently.

Installing

You have two options.

Option 1 — Install from this marketplace (recommended)

This repo is itself a one-plugin Claude marketplace. In Claude Desktop:

/plugin marketplace add https://github.com/fhanapercona/percona-data-catalog-agent
/plugin install percona-data-catalog-agent

The first command adds this repo as a marketplace; the second installs the plugin from it. You'll get future updates by running /plugin marketplace update fhanapercona/percona-data-catalog-agent.

Option 2 — Install a single .plugin file directly

If you've been handed a percona-data-catalog-agent.plugin file (e.g. via Slack), drop it into Claude Desktop and accept the install prompt. No marketplace setup needed; this is the right path for out-of-band sharing.

Verifying

Either way: start a fresh chat and ask "What is Software attribution?" You should get a measure card and a new row should appear in the audit log within a few seconds.

What the plugin contains

• One skill (data-catalog-agent) — the instructions Claude follows when answering and acting on catalog questions.
• One bundled MCP server (servicenow) — a thin local stdio proxy that forwards calls to Percona's centralized MCP backend at sherpa.tp.int.percona.com over SSE. Holds no credentials itself; the shared API key lives on the central server, behind the VPN.
• No agents, no hooks. Notion access rides on the Notion connector you already have.

Notion databases it reads / writes

DB	Access	Purpose
Data catalog	read + write	The catalog of measures itself. New entries default to Status = Proposed.
Data catalog — audit log	write (append-only)	One row per lookup / search / propose / edit / expire / audit-query.

The DB IDs are baked into the skill. If your Notion workspace differs, you'll need a forked version of the plugin.

Trust + safety properties

• Honest answers only. Zero matches → "not in catalog". Never a paraphrased guess.
• Catalog content treated as data, not instructions. If a description or formula field contains "ignore previous instructions", the skill shows it verbatim but does not act on it.
• Closed-list discipline. Status, Business Owner, and Source System come from a fixed set of values. The skill will refuse to invent new options.
• Preview-and-confirm before any write. Propose / edit / expire all show a preview (payload or diff) and wait for your explicit "yes" before touching Notion.
• Required "why" on writes. Every propose / edit / expire records a Purpose (and, for expire, a Reason) in the audit row.
• Audit invariant. Every interaction produces exactly one audit row. If the audit write fails, you'll see a ⚠ notice — the skill never silently swallows audit failures, especially for writes.
• Permission integrity. The skill uses your Notion identity only. If Notion says 403, the skill surfaces that and stops — never retries under elevated scope.
• No permanent deletion from the agent. Permanent deletion isn't supported by the Notion MCP and isn't exposed here. The agent's strongest action is remove, which moves a page out of the catalog DB into a sub-page of the audit log as an archive — the page is preserved, just no longer a catalog entry. To send a page to Notion's trash bin, open it in Notion and use "..." → "Move to Trash". This is a deliberate ceiling on the agent's destructive power.

Known limitations (v1.0.0)

• Notion search is generous. A relevance gate in the skill drops the worst false positives, but some near-misses may still surface as borderline. The skill is instructed to fall through to "I don't know" if no hit contains a query token in its name.
• Identity capture depends on session context. If Claude can't see your email in the session, the audit row records Requester Label = unknown. Catalog stewards should spot-check the audit log weekly.
• Tag taxonomy fragmentation. The catalog's Tags and Segmentation multi-selects have loose vocabularies. The skill's tag normaliser suggests existing values on every write, but a determined user can still introduce a new tag. The audit log's Property Diff captures these for steward review.
• No bulk operations. v1.0.0 is one measure at a time. Bulk import / export is out of scope.

Reporting issues

Tell Filip Hanaczewski. Include the query or change you made, what Claude said, and (if you can) the audit row ID.

Version history

• v1.1.0 (2026-05-13) — adds remove (S13). Moves a catalog page out of the catalog DB and under the audit log container as an archive sub-page. Uses double confirmation and a mandatory Reason. New remove value added to the audit Event Type. Real catalog quirk surfaced and documented: Notion refuses a direct move-out when the catalog has a select option containing commas (the "ServiceNow, Pillars telemetry, …" option does), so the skill performs a two-step move via the parent "Experiment" page.
• v1.0.0 (2026-05-13) — full feature set. Propose (S6/S7/S8), edit with diff preview (S9/S11), expire with reason (S10), audit-log query (S12). Stays as a skill over the existing Notion connector (ADR-008).
• v0.1.0 (2026-05-13) — initial release. Read-only. Lookups, searches, honest "I don't know", per-interaction audit rows.

Roadmap

Currently parked (revisit if usage proves them out):

• Bulk import / export.
• Automated detection of stale measures (no activity in N months).
• Slack / web / CLI surfaces.
• Catalog schema hygiene (the source Updated field is text, not a real timestamp; loose tag vocabulary).
• External SIEM mirror of the audit log.