feat: add plugin attribution via operation_context

[arorashivam96]

Summary

Add User-Agent attribution to every outbound Dataverse request the plugin originates. A single operation_context string (app/skill/agent) is appended to the UA header, enabling server-side MAU/MAT, skill split, and agent distribution dashboards from existing Dataverse logs — no new telemetry backend, no PII.

How it works

auth.py gains two new public functions that centralize attribution:

• get_client(skill) — returns a DataverseClient with OperationContext baked into the UA. Replaces the old 4-line DataverseClient(...) setup pattern.
• get_plugin_headers(skill, token) — returns headers dict for raw Web API calls with the same UA attribution.

Both validate against closed allowlists (_ALLOWED_SKILLS, _ALLOWED_AGENTS) and a strict regex. Free-form text, PII, unknown keys, emails, and control characters are rejected.

get_credential() is renamed to _get_credential() (private) — all callers migrated.

Resulting User-Agent per channel

Channel	UA
Python SDK	DataverseSvcPythonClient:0.1.0b10 (app=dataverse-skills/1.5.0;skill=dv-data;agent=claude-code)
CLI MCP proxy	DataverseCli/1.0.0 (app=dataverse-skills/1.5.0;skill=unknown;agent=claude-code)
Raw Web API	Python-urllib (app=dataverse-skills/1.5.0;skill=dv-metadata;agent=claude-code)

Changes (22 files)

Core infrastructure

File	Change
scripts/auth.py	get_client, get_plugin_headers, _get_credential (private), allowlists, regex validation
scripts/enable-mcp-client.py	Migrated to get_client("dv-connect")
evals/static_checks.py	EVAL-SKILLS-SYNC-01: checks _ALLOWED_SKILLS matches skill directories

Skill files — SDK Setup blocks

File	Change
skills/dv-data/SKILL.md	Setup + CSV import → get_client("dv-data")
skills/dv-query/SKILL.md	Setup → get_client("dv-query")
skills/dv-metadata/SKILL.md	Setup → get_client("dv-metadata")
skills/dv-solution/SKILL.md	2 blocks → get_client("dv-solution")

Skill files — raw Web API blocks

File	Change
skills/dv-solution/SKILL.md	N:N $expand → get_plugin_headers("dv-solution")
skills/dv-query/references/web-api-advanced.md	N:N $expand + $apply → get_plugin_headers("dv-query")
skills/dv-metadata/references/forms-and-views.md	Form creation → get_plugin_headers("dv-metadata")
skills/dv-admin/references/orgdb-settings.md	Read + update → get_plugin_headers("dv-admin")
skills/dv-admin/references/recycle-bin.md	→ get_plugin_headers("dv-admin")
skills/dv-admin/references/settings-overrides.md	→ get_plugin_headers("dv-admin")
skills/dv-data/references/sample-data-generation.md	EntityDefinitions → get_plugin_headers("dv-data")

Level 3 SDK references

File	Change
skills/dv-data/references/multi-table-fk-import.md	→ get_client("dv-data")
skills/dv-metadata/references/alternate-keys.md	→ get_client("dv-metadata")

Routing and docs

File	Change
skills/dv-overview/SKILL.md	Updated routing hint to get_client
skills/dv-connect/SKILL.md	Step 3: writes PLUGIN_VERSION/PLUGIN_AGENT to .env; Step 4: fixed auth.py copy path; Step 6: DATAVERSE_OPERATION_CONTEXT for MCP
templates/CLAUDE.md	Migrated to get_client
CLAUDE.md	Updated auth pattern section

Version

File	Change
4 manifest files	1.4.5 → 1.5.0 (MINOR)

Depends on

• Python SDK: OperationContext + context kwarg (#178, merged)
• Python SDK: key/value allowlisting (#181)
• Dataverse CLI: --context flag + DATAVERSE_OPERATION_CONTEXT env var + allowlisting

Test plan

• python .github/evals/static_checks.py — passes (pre-existing dv-overview token budget only)
• SDK: get_client("dv-data") creates/deletes record successfully
• End-to-end: MCP create + SDK bulk insert + SDK query + SDK update + MCP confirm — all passed
• Agent generates correct get_client calls with attribution comments
• _get_credential rename — no runtime errors

🤖 Generated with Claude Code

[suyask-msft]

Suggestion: keep host-specific knowledge in auth.py, make SKILL.md generic

Today the version-detection block has host-specific paths and env vars (CLAUDE_PLUGIN_ROOT, VSCODE_PID, CURSOR_TRACE_DIR) baked into a Python block the agent is asked to execute. Two issues:

1. Paths don't resolve in the user's CWD. The candidate paths (.github/plugins/dataverse/.claude-plugin/plugin.json etc.) are repo-relative — the user's project doesn't contain them. The code falls through to plugin_version = "unknown" if executed literally. It only works today because Claude Code skips the literal code and substitutes the version from its loaded plugin context. A weaker agent (or future host) following the skill literally writes unknown to .env.

2. Adding a new host = SKILL.md edit + auth.py edit. Host-specific knowledge is scattered.

Proposed shape

Move all host-specific knowledge into auth.py (one file, one list to maintain). Make the SKILL.md generic by asking the agent to substitute literals from its own context — it always knows them.

auth.py — version resolution lives here

# Host env vars that point at the loaded plugin root.
# Adding a new agent = one line here + one entry in _ALLOWED_AGENTS.
_PLUGIN_ROOT_ENV_VARS = (
    "CLAUDE_PLUGIN_ROOT",       # Claude Code
    "COPILOT_PLUGIN_ROOT",      # GitHub Copilot CLI
    # Add new host env vars here as they emerge.
)


def _read_version_from_manifest(plugin_root):
    """Read version from plugin.json at the given plugin root. Returns None on miss."""
    import json
    pj = os.path.join(plugin_root, ".claude-plugin", "plugin.json")
    if not os.path.exists(pj):
        return None
    try:
        with open(pj) as f:
            return json.load(f).get("version")
    except (OSError, ValueError):
        return None


def _plugin_version():
    """Resolve plugin version with three-tier lookup."""
    # 1. Live read from the plugin manifest — source of truth, survives plugin upgrades.
    for env_var in _PLUGIN_ROOT_ENV_VARS:
        root = os.environ.get(env_var)
        if root:
            ver = _read_version_from_manifest(root)
            if ver:
                return ver
    # 2. Fall back to the value dv-connect baked into .env (offline / unknown host).
    return os.environ.get("DATAVERSE_PLUGIN_VERSION", "unknown")

dv-connect/SKILL.md Step 3 — zero host-specific code

Replace the version-detection prose and Python block with:

Also set plugin attribution variables for User-Agent tagging. Fill in the two literals below from your own context — you (the agent) loaded this plugin, so you already know both values:

• PLUGIN_VERSION — the version field of your loaded plugin manifest (e.g. "1.5.0"). At runtime, auth.py._plugin_version() re-reads this from the live manifest; this .env entry is a fallback for offline cases.
• AGENT — your host identity, one of: claude-code, copilot, cursor, codex, or unknown. Must match an entry in _ALLOWED_AGENTS in auth.py — if you don't recognize your host, use unknown.

# Substitute these two literals from your loaded plugin context.
# Do NOT leave the angle-bracket placeholders — replace with real values.
PLUGIN_VERSION = "<plugin manifest version, e.g. 1.5.0>"
AGENT          = "<your host name: claude-code | copilot | cursor | codex | unknown>"

with open(".env", "w") as f:
    f.write(f"DATAVERSE_URL={dataverse_url}\n")
    f.write(f"TENANT_ID={tenant_id}\n")
    f.write(f"MCP_CLIENT_ID={mcp_client_id}\n")
    f.write(f"DATAVERSE_PLUGIN_VERSION={PLUGIN_VERSION}\n")
    f.write(f"DATAVERSE_PLUGIN_AGENT={AGENT}\n")
    f.write(f"SOLUTION_NAME={solution_name}\n")
    f.write(f"PUBLISHER_PREFIX=\n")
    f.write(f"PAC_AUTH_PROFILE=nonprod\n")

Why this shape

• SKILL.md has zero host-specific code. No CLAUDE_PLUGIN_ROOT, VSCODE_PID, or CURSOR_TRACE_DIR strings. New agent hosts don't require SKILL.md edits.
• One file owns host knowledge. Adding a new agent = append to _PLUGIN_ROOT_ENV_VARS and _ALLOWED_AGENTS in auth.py. Two-line change.
• Live version resolution. _plugin_version() re-reads the manifest on every get_client() call, so plugin upgrades without re-running dv-connect still report the current version. The .env value is a fallback, not the source of truth.
• Agent identity from agent itself. The agent knows its own name better than any env-var heuristic. Validation in _current_agent() catches incorrect substitutions on first SDK call.
• Placeholders fail loud. If a weak agent leaves <plugin manifest version, e.g. 1.5.0> literally in .env, _CONTEXT_RE rejects it (angle brackets aren't in the allowed character class) — immediate ValueError at first SDK call instead of silent "unknown" telemetry.

Optional follow-up

Since auth.py now resolves version live from the manifest, DATAVERSE_PLUGIN_VERSION in .env becomes a pure fallback for hosts that don't set any of the known _PLUGIN_ROOT_ENV_VARS. Consider dropping it from .env entirely in a follow-up PR, or documenting it as offline-fallback-only.