AI Development With HitKeep

Use HitKeep’s AI development surfaces according to the job. MCP is for governed aggregate analytics and docs lookup. Agent Skills teach assistants how to ask better HitKeep questions. The REST API is for application automation. Open exports and takeout are for portable owned data. Optional AI model configuration powers HitKeep product features such as Opportunity Recommendations.

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.

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.
Agent Skills	Teaching an assistant HitKeep’s analysis workflow, metric caveats, privacy boundary, and dashboard localization workflow.	Storing credentials, customer data, private URLs, or screenshots with private metrics.
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:

Install the HitKeep Agent Skills in the assistant client.
Enable the HitKeep MCP server on the HitKeep leader if it is not already enabled.
Create a dedicated personal or team API client token.
Grant the token only to the sites the assistant should query.
Configure the assistant’s MCP connection with the /mcp URL and bearer token.
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 work is different. Use the hitkeep-i18n skill for UI copy, Transloco keys, locale JSON files, PrimeNG locale behavior, and localized formatting. It does not need 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

Run the focused audit when MCP behavior changes:

GOFLAGS="$(./scripts/go-build-tags.sh goflags)" go test ./internal/mcpserver -run 'TestMCP.*Audit'
tests/scripts/mcp-audit.sh --schema-only

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

Update Agent Skills With The Tool Surface

Agent Skills are public instructions, so keep them boring and useful:

keep skill folders under skills/<skill-name>/SKILL.md
keep tool names, filters, and caveats aligned with the live MCP server
update skills/README.md when the skill pack shape changes
do not include credentials, private analytics, private URLs, or customer screenshots
tell assistants when to use MCP, REST API, dashboard, docs, exports, or takeout
keep hitkeep-i18n aligned with the dashboard language list, Transloco config, locale files, and locale checks

The parent hitkeep-analytics skill should stay aligned with the full MCP tool list. Narrower skills should explain domain-specific caveats, such as why AI crawler fetches are not the same as AI-referred human visits.

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.

Run the focused checks for AI provider, Opportunity, storage, and MCP exposure changes:

GOFLAGS="$(./scripts/go-build-tags.sh goflags)" go test ./internal/ai ./internal/opportunities ./internal/database ./internal/mcpserver

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.