Polish Avo MCP docs for Claude AI catalog submission#1708
Merged
Conversation
Polish the Avo MCP overview for Claude AI catalog submission and align the tools reference with the post-merge state of the server. Overview: - Replace the Read/Write bullet split with three workflow walkthroughs: search the tracking plan, design tracking for a new feature, review and implement an Avo branch. - Drop the dense "Recommended agent flows" section. - Add Troubleshooting (6 entries) and Support and privacy (support email + Avo Privacy Policy link) to meet Anthropic Software Directory Policy requirements (sections 3.A, 3.B, 3.C, 3.E). - Restructure the capability matrix around the canonical agent intents (Entry / Discover / Understand / Change / Progress). Tools reference: - Remove deprecated tools that have been replaced: health_check, get_sources, get_branch_details, get_branch_code_snippets, and get_branch_implementation_guide. Each is functionally covered by get(type:"source"|"branch", include:[...]). - Mark list_branches as transitional until search(type:"branch") ships. - Expand the `get` reference with the `branch` and richer `workspaceConfig` types, the include axis (overview/changes/code_snippets), and source/destination/groupType enumeration when id/name are both omitted. - Document `search` filter mode fully (12 filter parameters, mode auto-selection, pagination, 400 on combining query+filters). - Add `update_branch_description` action to `workflow`. - Add `property_bundle` and `metric` item types and the `archive` op to `save_items`, plus per-event property settings via `eventConfigs`, addPropertyBundles/removePropertyBundles on event updates, and the updated NotYetImplemented list (archive event, remove event_variant, set.sendAs). - Add canonical sample JSON responses next to the `search` and `save_items` definitions. Closes AVO-2879. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR updates Avo MCP reference documentation to reflect API consolidation and expanded capabilities. The overview page restructures its capability matrix and introduces troubleshooting guidance; tools reference reorganizes its intro by intent, marks ChangesAvo MCP API Documentation Consolidation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Member
📝 Changed routes:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@pages/reference/avo-mcp/tools.mdx`:
- Line 386: Update the sentence about eventConfigs so it doesn't contradict
itself: remove the parenthetical "(or the same batch, ordered before the
property update that references it)" and replace it with an explicit statement
that eventConfigs can only reference events that existed before the batch
started because $tmp: references are not supported in eventConfigs fields; refer
to eventConfigs and $tmp: in the clarification so readers know which symbols are
affected.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: f8b6f6a5-0caf-4736-bbb3-75e25b44967c
📒 Files selected for processing (2)
pages/reference/avo-mcp/overview.mdxpages/reference/avo-mcp/tools.mdx
Every tool now follows the same h3 outline so the right-side TOC reads the same across the page: ### Parameters ### Returns ### Examples #### Example title (h4) ### Common errors Add one or two examples per tool, each framed as a natural-language prompt plus a short context line and the resulting tool call. The save_items examples keep the new-event-with-new-property pattern and swap the allowed-values demo for a funnel-metric creation so the new metric capability is exercised inline. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…s growth
- Reorder tool sections to match the canonical surface order returned
by tools/list: list_workspaces, search, get, save_items, workflow,
list_branches. The tool index at the top of the page already matched.
- Rewrite the get tool intro to foreground the four type families
it now serves (tracking-plan items, workspace metadata, workspace
config, branches), document that include defaults to ["overview"] for
branch lookups, and point to workspaceConfig as the source of valid
customField and pii names for search filters.
- Add customField and pii filter parameters to search's filter-mode
parameter table.
- save_items growth:
- op enum: archive is canonical for events, remove is accepted as a
legacy alias that behaves identically. Properties and bundles
continue to use op: remove for archive.
- Supported ops by type: event archive is implemented; mark remove as
legacy alias for events. Update the corresponding row.
- Add tags to create-event and create-property field tables.
- Add set.name (rename) plus top-level addTags/removeTags to
update-event field table.
- Add set.name (rename), top-level addTags/removeTags, and top-level
isList (scalar/list toggle) to update-property field table.
- Add an Archive-event section showing both the canonical op:archive
and the legacy op:remove shape.
- Drop archive-event from the NotYetImplemented list (now implemented);
only remove event_variant and set.sendAs remain.
- Sync the overview troubleshooting entry so it lists the new
NotYetImplemented set.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Overview: - Move the workspace-discovery sequence into the lead of "What you can do" as a brief intro + "Getting started" paragraph. Drop the standalone "Getting started" section. - Add a transition line stating the three workflows are the major use cases and many more flows are possible through the same tools. Tools reference: - Replace the bullet-grouped tool index with the same capability matrix table used on the overview (local anchors instead of cross-page links). Same content as before but easier to scan. - Trim the OAuth scope callout's redundant "grouped below" line. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
GEO and Anthropic Software Directory polish pass on the MCP docs. Overview: - Add MDX frontmatter (title, description) for AI engines that scrape the raw source. The theme renders <title> from the H1 today, but the description gives raw-MDX crawlers a clean summary line. - Rename the "What you can do" section to "Use cases" to match the catalog policy §3.E and submission-form vocabulary verbatim. - Add a "Limits" section listing the per-call caps for save_items, search (semantic + filter), and list_branches, plus a note that workspace access is verified at call time. - Add an "FAQ" section with five question-form headings (does the MCP merge?, data collection, admin requirement, multi-user, supported clients). Question headings rank well in AI summaries. - Expand the "Support and privacy" section with a "Privacy summary" sub-block covering the four catalog §3.A topics (what is collected, how it's used, storage/retention, third-party sharing) inline, with the linked policy for full detail. Tools reference: - Add MDX frontmatter. - Add a "Quick reference" Callout at the top of save_items listing six common patterns: create-event-with-properties, allowed values, rename, archive, funnel metric, scalar/list toggle. Helps readers orient before the 280-line per-type breakdown. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address the remaining items from the catalog/GEO review that weren't in the first polish pass. Overview: - Tighten the page lead: "Avo MCP gives AI coding assistants direct access..." is more entity-first (better for AI summarization) than the previous "The Avo MCP server exposes...". Move the parenthetical Model Context Protocol expansion to a trailing aside with a link to the protocol site. - Drop the duplicate intro paragraph at the top of "Use cases" that restated the page header. Section now leads with the Getting started paragraph that gives the reader an immediate action. - Promote the OAuth first-call paragraph that lived at the bottom of Setup into a Callout at the top of Setup. Same content, more visible — and it covers the CI-runner edge case up front. Tools reference: - save_items: add a "Scope: write · Destructive: archive / remove ops" inline header line and a warning Callout describing exactly which ops are destructive and that property archives cascade across events. Covers Anthropic Software Directory §5.E (destructiveHint) at the documentation level even where server-side annotations may not surface to all clients. Verified: - Right-side TOC ships with nextra-theme-docs@^3.3.1 by default, so the earlier "long page without TOC" concern is moot. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
thoragudf
changed the title
Address CodeRabbit feedback on PR #1708: the previous wording said "create the event in an earlier call (or the same batch, ordered before the property update)" — the parenthetical contradicted the preceding clause and the $tmp: resolution list. Per SaveItems_description.res, $tmp: references are not supported in eventConfigs fields, so a same-batch create-event item is invisible to eventConfigs regardless of ordering. The event must come from a prior save_items call. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Move tool-specific troubleshooting (search returning nothing, ambiguous branch names, save_items NotYetImplemented) to a new Troubleshooting section at the end of tools.mdx. Keep authentication and workspace-access entries on the overview where catalog reviewers land. Each page now cross-links to the other for navigation. The split sharpens both audiences: catalog reviewers see the universal auth/access trio on first scroll of the overview; developers reading the tool reference find tool-specific behavioral gotchas next to the tools themselves. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Capability matrix already links each tool to its tools.mdx anchor and ends with a "See the Tools reference" pointer. The standalone Tools h2 section three sections later just repeated that pointer. Removed. No inbound links to the #tools anchor on the overview. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reorder H2 sections so the FAQ comes before Setup. Every FAQ entry is a pre-installation question (does it merge to main?, what data is collected?, admin required?, multi-user?, supported clients?) — they serve the reader better before the install steps, not after. Final overview H2 order: Use cases → Capability matrix → Limits → FAQ → Setup → Authentication → Troubleshooting → Support and privacy Trades the FAQ-at-the-bottom web convention for a better narrative flow during the read-then-evaluate pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
thoragudf
requested review from
a team and
stefaniabje
and removed request for
a team
bjornj12
reviewed
Jun 2, 2026
|
|
||
| ### What data does Avo collect through the MCP? | ||
|
|
||
| The MCP reads and writes tracking-plan content (events, properties, metrics, etc.) already stored in your Avo workspace. It does not collect your codebase, your prompts, or any data your MCP client sends to its model. Standard operational telemetry — request IDs, error counts — is retained for reliability. See the [Avo Privacy Policy](https://www.avo.app/l/privacy) for full details. |
Contributor
There was a problem hiding this comment.
lets include a full list here instead of "etc"
Contributor
Author
There was a problem hiding this comment.
Fixed in 6710d4e. Replaced "etc" with the full enumeration: events, properties, event variants, metrics, categories, and property bundles. Matches the canonical itemType enum from the tools reference.
bjornj12
reviewed
Jun 2, 2026
| | `workspaceId` | No | Workspace ID. | | ||
|
|
||
| **Parameters:** | ||
| **Semantic mode** *(pass `query`)* |
Contributor
There was a problem hiding this comment.
Semantic search requires the workspace to have AI enabled in their workspace settings,
It makes us embed the events/properties/metrics/event-variants with openAI embed and do vector search
Contributor
Author
There was a problem hiding this comment.
Good context — folded that detail into the Semantic search description in 6710d4e:
Avo embeds each item with OpenAI embeddings and runs a vector-similarity search at query time, so
"user signed up"matchesAccount CreatedorRegistration Completedeven when no keyword overlaps. Requires Avo Intelligence Smart Search to be enabled in Workspace Settings.
The Smart Search prerequisite was previously only in a callout below; it now appears inline as well so the requirement isn't easy to miss.
- overview.mdx: enumerate the full tracking-plan item set (events, properties, event variants, metrics, categories, property bundles) in the "What data does Avo collect" FAQ entry instead of trailing off with "etc". The list matches the canonical itemType enum. - tools.mdx: expand the Semantic search description with the implementation detail Björn provided — Avo embeds items with OpenAI embeddings and runs vector-similarity search at query time. Also surfaces the Smart Search prerequisite inline (was previously only in the callout below). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Move the Smart Search prerequisite from buried-inside-Parameters position to the most prominent slot — directly under the two-mode overview bullets. Drop the inline mention at the end of the Semantic search bullet so the callout is the single canonical location for the requirement. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Gives the bullet list a discoverable heading in the right-side TOC and makes the section parallel to the three heavyweight use cases above. Same content, h3-shaped now. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…wner/stakeholder, variant overrides, nameMappings
Bring docs back in sync with the SaveItems server source after a
gap-analysis pass.
Must-fix:
- Batch cap is 50, not 100 (corrected in tools.mdx item-shape note,
Common errors, and the overview Limits section).
- event_variant: op: "archive" is supported (with baseEventId +
variantId); only op: "remove" remains unsupported. Updated the
Supported ops by type table and the NotYetImplemented callout, and
added an Archive-event_variant section.
- Added category as a 6th item type: type enum, categoryId ID field,
ops table row (create/update/remove; archive via remove; does not
cascade), Update-category fields table, Remove-category section.
Should-fix:
- addCategories / removeCategories cross-cutting field on event,
property, and metric updates. Documented that values are category
names (or $tmp: refs), not IDs.
- Owner and stakeholder section with a BRANCH-INDEPENDENT warning
callout — owner.stakeholder, stakeholders.add, stakeholders.remove
on event/property/metric items take effect workspace-wide even if
the branch is discarded. Load-bearing safety warning.
- Merging categories recipe — no merge op exists, so an agent must
update every member entity with addCategories: ["B"],
removeCategories: ["A"] and remove category A in one batch.
- Full variant override surface: clearAttachedProperties,
addSourceOverrides / removeSourceOverrides / clearSourceOverrides,
addBundleOverrides / removeBundleOverrides / clearBundleOverrides,
addVariantPropertyRegex / removeVariantPropertyRegex /
clearVariantPropertyRegexOverride. Documented the three-state
add/remove/clear lattice.
Nice-to-have:
- set.triggers on Update-event_variant.
- nameMappings field on event and property items (tagged-object form:
{kind: "allDestinations"} or {kind: "destination", destinationId}).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Switch privacy policy URL from /l/privacy to /privacy (cleaner; 301-redirects to the same destination). - Move the "Model Context Protocol" expansion inline at first mention of Avo MCP, instead of a trailing parenthetical at the end of the paragraph. Reads more naturally. - Rewrite the Getting started paragraph to lead with what the tools let you do (search the plan, design tracking, review branches) before dropping into the workspaceId discovery sequence. - Drop the stdio / WORKSPACE_ID environment variable aside from Getting started. Stdio is a niche path for a hosted MCP, and the detail doesn't belong in the first paragraph anyone reads. - Drop the now-redundant "These are the three use cases below…" transition line. The new Getting started already previews the three flows by name, and the h3 sections immediately below carry the load. - Expand PRD on first use to "PRD (product requirements document)" for the same reason we expand MCP — consistent treatment of acronyms helps non-product readers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per bjornj12 feedback: the previous single bullet ("Combine Avo with
your data MCP to diagnose tracking gaps from real data") missed the
stronger use case — that Avo's tracking plan IS the semantic layer
the AI needs to write correct queries against the data MCP. Splitting
into two bullets:
1. Query your product data correctly — Avo provides metric
definitions and event-composition rules so the AI builds accurate
queries instead of guessing.
2. Diagnose tracking gaps — compare data MCP results against the
plan to find what's missing.
Same data-MCP pairing (Amplitude / Mixpanel / BigQuery / etc.), two
distinct values.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
This PR prepares the Avo MCP overview and tools reference for submission to the Claude AI catalog. Two drivers shaped every change:
Closes AVO-2879.
Catalog compliance
support@avo.appsurfaced in the support sectionsave_itemsheader line + warning Callout listing which ops are destructive and that property archives cascadeGEO improvements
title+description) on both pages for raw-MDX crawlers.Checkout Completedevent with aCheckout Methodproperty for Web and iOS."Final overview h2 order
Tools reference
get/search:health_check,get_sources,get_branch_details,get_branch_code_snippets,get_branch_implementation_guide.list_branchesstays as a transitional tool untilsearch(type:"branch")ships.tools/list(list_workspaces→search→get→save_items→workflow→list_branches).getdocuments thebranchtype with theincludeaxis (overview/changes/code_snippets, defaults to["overview"]), source/destination/groupType enumeration when bothidandnameare omitted, and the expandedworkspaceConfig(custom-field + PII type lists).searchdocuments both modes (semantic and filter), every filter parameter includingcustomFieldandpii, pagination, the 400 returned whenqueryand filters are combined, and the Smart Search prerequisite as a callout directly under the mode bullets. Semantic search now mentions the OpenAI-embedding + vector-similarity mechanism.save_itemsdocumentsproperty_bundle,metric, andcategoryitem types, all four ops (create/update/remove/archive), per-event property settings viaeventConfigs,addPropertyBundles/removePropertyBundles,addCategories/removeCategories(note: by name, not ID),tags/addTags/removeTags,set.namefor renames, top-levelisListtoggle,nameMappings(tagged-object shape), the full variant override surface (3-state add/remove/clear lattice across attached properties, source overrides, bundle overrides, variant property regex overrides) plusset.triggers, and the updatedNotYetImplementedlist. A Quick reference Callout at the top lists the six most common ops. Owner and stakeholder fields get their own subsection with a⚠️Branch-independent warning — these mutations take effect workspace-wide and do not roll back if the branch is discarded. Merging categories has its own subsection explaining the no-merge-op recipe.workflowdocuments the newupdate_branch_descriptionaction.searchandsave_items.save_itemsbatch cap corrected to 50 items per call (was previously documented as 100).Review feedback addressed
tools.mdx:435) — clarifiedeventConfigsevent-reference constraints; the previous wording contradicted the$tmp:resolution list. Now states explicitly thateventConfigscan only reference events from earliersave_itemscalls. (Commitddf6e68c.)overview.mdx:78) — enumerated the full tracking-plan item set in the data-collection FAQ entry instead of trailing off with "etc". (Commit6710d4ec.)tools.mdx:73) — added the implementation detail Björn provided: Avo embeds items with OpenAI embeddings and runs vector-similarity search at query time; Smart Search prerequisite promoted to a callout under the mode bullets. (Commits6710d4ec+24182a66.)Test plan
support@avo.app,https://www.avo.app/l/privacy).get's branch facets,searchfilter mode + Smart Search callout,save_itemscategoryandevent_variantarchive support, owner/stakeholder branch-independent warning, variant override lattice,addCategories/removeCategorieson event/property/metric updates,nameMappingsshape, the corrected 50-item batch cap.yarn spellcheck).tools.mdxanchor IDs.Notes for MCP owners
projects/mcp/src/tools/GetItemDetails.res:1116advertisesinclude: ["details", "code_snippets"]in a source-listing hint, but the include enum only hasoverview | changes | code_snippets. This PR documents the canonical enum values; fixing the hint string is owner work.ListWorkspaces_description.resandGetItemDetails_description.resas colocated description files, but those files don't yet exist in the monorepo. Description text for those tools is currently inline (let description = ...) in their.resfiles. Worth confirming the colocated files were intended to ship alongside.abb0971edocumented several fields (exact form of stakeholder references,nameMappingsverb on update, full variant override field list) using the names and shapes from the analysis. These weren't visible in the snapshot ofSaveItems_description.resaccessible from this worktree, so worth cross-checking against the current schema during review — the docs may need a touch-up if any field names drifted between the gap analysis and the current code.🤖 Generated with Claude Code