AI-Assisted Analytics Development with HitKeep

Use HitKeep’s AI surfaces according to the job. Production MCP is for governed aggregate analytics and docs lookup. Analytics Agent Skills teach external assistants how to reason about that data. Ask AI uses the same transport-neutral analytics procedures with an internal tool bridge. Contributor skills and the local hk developer MCP are for changing HitKeep itself.

Do not give assistants dashboard cookies or raw exports just because they are convenient. Create a scoped API client token for MCP, keep the token in the assistant’s secret store, and grant only the sites the assistant should query.

Route production AI through a gateway

HitKeep has a rudimentary global AI request and token limiter. It is a coarse process-level safeguard, not per-user, per-site, per-provider-key, or a security policy engine. For production use, route model traffic through an AI gateway or provider policy layer that can enforce detailed quotas, model allowlists, key isolation, audit logging, redaction, and network controls. See GoAI’s supported provider options and generic OpenAI-compatible provider docs for the underlying base URL, token, header, and custom endpoint patterns.

Choose The Right Surface

Surface	Use it for	Do not use it for
MCP server	Read-only aggregate analytics, imported Search Console rows, Web Vitals aggregates, saved Opportunities, and official docs lookup.	Site creation, goal mutation, billing, token management, raw hit exports, or dashboard session access.
Analytics Agent Skills	Teaching an external assistant HitKeep’s analytics workflow, metric caveats, and privacy boundary.	Repository setup, contributor QA, or storing credentials and customer data.
Ask AI shared procedures	Grounding the dashboard assistant in the same transport-neutral analytics reasoning through its internal tool bridge.	MCP token setup or external-client instructions.
Contributor Agent Skills	Operating the repository-owned hk CLI and local developer MCP for setup, workspaces, QA, and localization.	Customer analytics or production deployment operations.
REST API	Normal application automation with authenticated request and response contracts.	Free-form agent access to admin actions without a product-specific workflow and permission model.
Dashboard	Human setup, admin review, visual investigation, and workflow checks.	Reusing dashboard cookies in an AI client.
Open exports and takeout	Portable owned files, offline analysis, account-level export workflows, and audit handoff.	Live assistant queries that only need aggregate answers.
AI model configuration	Enabling optional HitKeep product features that need structured model output.	Running a general chat assistant inside HitKeep.

Build An Analytics Assistant

For live analytics assistant workflows, use MCP and Agent Skills together:

1. Install the HitKeep Agent Skills in the assistant client.
2. Enable the HitKeep MCP server on the HitKeep leader if it is not already enabled.
3. Create a dedicated personal or team API client token.
4. Grant the token only to the sites the assistant should query.
5. Configure the assistant’s MCP connection with the /mcp URL and bearer token.
6. Ask the assistant to name the site, date range, comparison range, and data source it used.

MCP answers should stay aggregate. If the assistant needs raw files for a one-off audit, use takeout or open exports instead of expanding the MCP token.

Dashboard localization is contributor work. Use the hitkeep-i18n skill from .agents/skills for UI copy, Transloco keys, locale JSON files, OptimusUI locale behavior, and localized formatting. It uses hk for QA and does not need production MCP access.

Keep MCP Changes Safe

If you contribute to HitKeep’s MCP server, keep the public contract stable:

• tools remain read-only and aggregate-only
• each tool sets a read-only annotation
• analytics tools stay closed-world
• docs tools are the only tools that fetch official docs markdown
• API client bearer tokens and site grants remain the authorization model
• raw hit exports, write workflows, billing, token management, takeout, and dashboard sessions stay outside MCP

Use hk to select and run the current production-MCP gates when MCP behavior changes:

./hk qa changed --gate mcp-audit --gate mcp-schema

The public HitKeep Agent Guide explains the repository-level contributor rules for MCP, Agent Skills, AI output validation, docs, and tests.

Keep both skill packs aligned

The analytics pack is canonical under skills/:

• keep the five public analytics skill identities independently installable;
• keep each SKILL.md as the production-MCP adapter;
• keep each references/procedure.md transport-neutral because Ask AI embeds it;
• keep current tool names and mutable schemas in the live tool surfaces and docs, not copied into procedures;
• do not include credentials, private analytics, private URLs, or customer screenshots
• update skills/README.md and this public guide when the analytics pack shape changes.

The contributor pack is canonical under .agents/skills/. Keep hitkeep-development, hitkeep-workspace, hitkeep-qa, and hitkeep-i18n focused on hk and repository policy. Never copy these bodies under skills/ or embed them into Ask AI.

Optional AI Model Features

HitKeep’s optional AI provider route is for product features, not for unrestricted assistant access.

Opportunity Recommendations are the first model-backed workflow. HitKeep reads aggregate analytics, runs deterministic detectors, and asks the configured model for a small structured response. HitKeep validates the response before storage.

HitKeep should not store raw prompts, raw provider payloads, raw external error bodies, provider headers, or provider secrets. Saved AI output should contain safe product fields such as localization keys, interpolation params, cited evidence IDs, detector metadata, status, and audit metadata.

If you change GoAI-backed Opportunity generation, keep the saved output contract key-based and deterministic. New saved fields, message keys, interpolation params, action types, or evidence shapes should have validator coverage before they are accepted.

Use the repository-owned QA planner for AI provider, Opportunity, storage, and MCP exposure changes:

./hk qa plan changed --output json
./hk qa changed

Use AI Model Configuration for provider setup and Opportunity Recommendations for the customer-visible behavior.

When REST API Or Exports Are Better

Use the REST API when you are building a product integration that needs explicit request and response contracts. API clients, site grants, and normal server permissions still apply.

Use open exports or takeout when the user needs portable files, raw records that are available through export workflows, or a compliance/audit handoff. MCP intentionally avoids raw hit export tools because assistant access should remain scoped, revocable, and aggregate by default.

Related

• Official MCP Server
• HitKeep Agent Skills
• AI Model Configuration
• API Clients
• Open Exports and Takeout
• Facts and Limits