feat: add User-Agent tracking for analytics #14

richhankins · 2026-01-31T23:40:48Z

Summary

Adds User-Agent tracking to identify context-connectors usage in Augment backend analytics.

User-Agent Format

Consistent with auggie CLI format (augment.cli/{version}/{mode}):

Entry Point	User-Agent
`ctxc search`	`augment.ctxc.cli/0.1.3`
`ctxc agent`	`augment.ctxc.cli/0.1.3`
`ctxc index`	`augment.ctxc.cli/0.1.3`
`ctxc mcp`	`augment.ctxc.mcp/0.1.3`
`ctxc mcp` + Claude Desktop	`augment.ctxc.mcp/0.1.3/claude-desktop/1.0.0`
SDK usage	`augment.ctxc.sdk/0.1.3`

MCP Client Info

When an MCP client connects, the User-Agent is updated to include client info:

Format: augment.ctxc.mcp/{version}/{clientName}/{clientVersion}
Same RFC 9110 sanitization as auggie CLI
Same max lengths: name=32 chars, version=8 chars

Changes

New utilities (`src/core/utils.ts`)

buildClientUserAgent(product, mcpClientInfo?) - Constructs User-Agent string
sanitizeForUserAgent(value, maxLength) - RFC 9110 compliant sanitization
getVersion() - Gets package version at runtime

Updated configs

IndexerConfig.clientUserAgent - Passed to DirectContext.create()
SearchClientConfig.clientUserAgent - Passed to DirectContext.import()
MultiIndexRunnerConfig.clientUserAgent - Passed to SearchClient
CLIAgentConfig.clientUserAgent - Passed to AugmentLanguageModel

CLI commands

cmd-search.ts - Uses augment.ctxc.cli
cmd-agent.ts - Uses augment.ctxc.cli
cmd-index.ts - Uses augment.ctxc.cli
mcp-server.ts - Uses augment.ctxc.mcp, captures MCP client info on initialize

Dependencies

Requires @augmentcode/auggie-sdk >= 0.1.15 with clientUserAgent option (PR #47 merged).

Testing

179 tests passing
New unit tests for buildClientUserAgent and sanitizeForUserAgent

Add clientUserAgent support to identify context-connectors usage in Augment backend analytics. This enables tracking: - Which product is calling (context-connectors vs other SDK consumers) - Which interface is being used (CLI, SDK, MCP, agent) - For MCP: which client is connecting (prepared for future use) User-Agent format: context-connectors/{version} via:{interface} Changes: - Add buildClientUserAgent() utility in src/core/utils.ts - Add clientUserAgent option to Indexer, SearchClient, MultiIndexRunner, CLIAgent - Pass clientUserAgent to DirectContext and AugmentLanguageModel - Set appropriate interface IDs in CLI commands (cli-search, cli-index, cli-agent, mcp) - Export ClientInterface and MCPClientInfo types - Add unit tests for buildClientUserAgent Requires auggie-sdk >= 0.1.15 (PR #47 merged, awaiting npm release) Agent-Id: agent-0d00d75b-1ac5-4e85-a310-90e1af295ee3

augment-app-staging · 2026-01-31T23:43:24Z

🤖 Augment PR Summary

Summary: Adds a consistent clientUserAgent signal so Augment backend analytics can attribute Context Connectors usage by entry point (CLI, MCP, SDK).

Changes:

Introduces buildClientUserAgent(product, mcpClientInfo?) plus ClientProduct/MCPClientInfo types in src/core/utils.ts.
Threads clientUserAgent through Indexer, SearchClient, MultiIndexRunner, and the CLI agent’s Augment model configuration.
Updates CLI commands (ctxc search/index/agent) to send augment.ctxc.cli/{version} on API calls.
Updates MCP server startup to send augment.ctxc.mcp/{version}, then enrich it with MCP client name/version after initialization.
Re-exports the new UA utilities from src/core/index.ts.
Adds Vitest coverage for UA building/sanitization behavior in src/core/utils.test.ts.

Technical Notes: Version is resolved at runtime from package.json (cached and falling back to unknown on failure), and MCP client tokens are sanitized per RFC 9110 constraints.

_{🤖 Was this summary useful? React with 👍 or 👎}

augment-app-staging

Review completed. 3 suggestions posted.

Comment augment review to trigger a new review at any time.

augment-app-staging · 2026-01-31T23:43:25Z

src/core/utils.test.ts

+describe("buildClientUserAgent", () => {
+  it("should build basic user agent for cli-search", () => {
+    const ua = buildClientUserAgent("cli-search");
+    expect(ua).toMatch(/^context-connectors\/\d+\.\d+\.\d+ via:cli-search$/);


These assertions only accept strict x.y.z; if package.json ever uses pre-release/build metadata (e.g. 0.1.3-beta.1) the tests will fail even though buildClientUserAgent() is behaving correctly.

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augment-app-staging · 2026-01-31T23:43:25Z

src/core/utils.ts

+function getVersion(): string {
+  if (cachedVersion === null) {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../../package.json');


getVersion() assumes ../../package.json is always readable at runtime; in bundled/packaged environments where package.json isn’t present this will throw and make buildClientUserAgent() crash callers. It may be worth making the version lookup resilient so UA building can’t break normal execution.

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augment-app-staging · 2026-01-31T23:43:25Z

src/core/utils.ts

+  mcpClientInfo?: MCPClientInfo
+): string {
+  let ua = `context-connectors/${getVersion()} via:${clientInterface}`;
+  if (mcpClientInfo) {


buildClientUserAgent() appends client:{name}/{version} whenever mcpClientInfo is provided, even if clientInterface isn’t mcp, which could produce misleading analytics strings if misused.

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

When an MCP client (like Claude Desktop or Cursor) connects, we now capture its name and version from the initialize request and include it in the User-Agent string. Format: context-connectors/{version} via:mcp client:{name}/{version} Example: context-connectors/0.1.3 via:mcp client:claude-desktop/1.0.0 Changes: - Add updateClientUserAgent() method to MultiIndexRunner - Handle InitializeRequestSchema in mcp-server.ts to capture client info - Update User-Agent dynamically after receiving MCP client info Agent-Id: agent-0d00d75b-1ac5-4e85-a310-90e1af295ee3

Change format from: context-connectors/{version} via:{interface} context-connectors/{version} via:mcp client:{name}/{version} To: context-connectors/{version}/{interface} context-connectors/{version}/mcp/{clientName}/{clientVersion} This matches the auggie CLI format: augment.cli/{version}/{mode}/{clientName} Also: - Add sanitizeUserAgentToken() per RFC 9110 (same as auggie CLI) - Make MCPClientInfo.version optional - Limit client name to 32 chars, version to 8 chars

Change User-Agent format from context-connectors/{version} to augment.ctxc/{version} to be consistent with other Augment products (augment.cli, augment.intellij, etc.)

Use augment.ctxc.{product}/{version} format: - augment.ctxc.cli/{version} for all CLI commands (search, agent, index) - augment.ctxc.mcp/{version} for MCP server - augment.ctxc.sdk/{version} for SDK/programmatic usage MCP with client info: augment.ctxc.mcp/{version}/{clientName}/{clientVersion}

In bundled/packaged environments where package.json isn't present, getVersion() now returns 'unknown' instead of throwing an error. This prevents buildClientUserAgent() from crashing callers.

….json read - Add scripts/generate-version.js to generate src/generated/version.ts at build time - Update utils.ts to import VERSION from generated file instead of reading package.json - Add prebuild script to package.json to run version generation before build - Add src/generated/ to .gitignore (auto-generated files) This makes version lookup resilient in bundled/serverless environments where package.json may not be available at runtime. Agent-Id: agent-0d00d75b-1ac5-4e85-a310-90e1af295ee3

richhankins · 2026-02-01T21:59:52Z

augment review

augment-app-staging

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

augment-app-staging · 2026-02-01T22:03:43Z

src/core/utils.ts

 * Shared utility functions
 */

+import { VERSION } from "../generated/version.js";


buildClientUserAgent() now imports VERSION from ../generated/version.js, but src/generated/ is gitignored and isn’t created by test/cli scripts, so a clean checkout can fail at import time (e.g., vitest run, tsx src/bin/index.ts). Consider ensuring the generator runs for those entry points too, not just via prebuild.

Other Locations

package.json:27

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augment-app-staging · 2026-02-01T22:03:43Z

src/clients/mcp-server.ts

+    // Return the standard initialize response
+    // The Server class will merge our capabilities with the standard response
+    return {
+      protocolVersion: "2024-11-05",


This custom initialize handler hardcodes protocolVersion: "2024-11-05"; if an MCP client negotiates a different protocol version, initialization could fail or behave unexpectedly. Consider deriving the response protocol version from the request/SDK defaults so protocol negotiation stays correct.

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

- Add pretest script for unit tests - Add precli scripts for CLI commands - Add pretest:integration for integration tests - Add prepare script for npm install This ensures src/generated/version.ts exists before any script that imports buildClientUserAgent() runs.

- Remove redundant pre-scripts (pretest, precli, etc.) - Keep only prebuild and prepare for the happy path - Use createRequire with try/catch for resilient fallback - Try .js first (compiled), then .ts (dev/test) for compatibility - Falls back to 'unknown' instead of crashing on missing version file

- Read version from package.json at runtime (like auggie-sdk) - Remove generated version file approach - Remove prebuild/prepare scripts - Single source of truth for version

Instead of overriding the initialize handler (which bypassed the SDK's protocol version negotiation), use the oninitialized callback to capture MCP client info after the SDK handles initialization. This ensures: - Protocol version negotiation works correctly with all MCP clients - Client info is still captured for User-Agent tracking - No hardcoded protocol version that could become stale

richhankins · 2026-02-01T23:37:53Z

augment review

augment-app-staging

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

package.json

augment-app-staging · 2026-02-01T23:41:13Z

src/clients/mcp-server.ts

+  // Use the SDK's oninitialized callback to capture MCP client info
+  // This preserves the SDK's protocol version negotiation
+  server.oninitialized = () => {
+    const clientInfo = server.getClientVersion();


Can we confirm @modelcontextprotocol/sdk (at our pinned version) actually exposes server.getClientVersion() and the server.oninitialized callback? If either isn’t supported, this will throw at runtime and prevent the MCP server from starting.

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

Confirmed! Both APIs exist in @modelcontextprotocol/sdk version 1.25.3:

Agent-Id: agent-0d00d75b-1ac5-4e85-a310-90e1af295ee3

augment-app-staging bot reviewed Jan 31, 2026

View reviewed changes

richhankins added 8 commits January 31, 2026 15:49

chore: require auggie-sdk ^0.1.15 with clientUserAgent support

ac790cd

refactor: Use augment.ctxc prefix for consistent User-Agent format

7065f6d

Change User-Agent format from context-connectors/{version} to augment.ctxc/{version} to be consistent with other Augment products (augment.cli, augment.intellij, etc.)

fix: make getVersion() resilient to missing package.json

827b610

In bundled/packaged environments where package.json isn't present, getVersion() now returns 'unknown' instead of throwing an error. This prevents buildClientUserAgent() from crashing callers.

fix: restore @augmentcode/auggie-sdk dependency (^0.1.15)

96560ad

augment-app-staging bot reviewed Feb 1, 2026

View reviewed changes

richhankins added 4 commits February 1, 2026 14:08

refactor: simplify version loading to match auggie-sdk-typescript

e806b63

- Read version from package.json at runtime (like auggie-sdk) - Remove generated version file approach - Remove prebuild/prepare scripts - Single source of truth for version

augment-app-staging bot reviewed Feb 1, 2026

View reviewed changes

fix: add @augmentcode/auggie-sdk dependency (^0.1.15)

3c0dca8

Agent-Id: agent-0d00d75b-1ac5-4e85-a310-90e1af295ee3

richhankins requested a review from igor0 February 1, 2026 23:59

igor0 approved these changes Feb 2, 2026

View reviewed changes

richhankins added 2 commits February 2, 2026 15:58

fix: regenerate package-lock.json with @augmentcode/[email protected]

4ebef83

fix: regenerate package-lock.json with all dependencies

f537701

richhankins merged commit ef6a46a into main Feb 3, 2026
1 check passed

feat: add User-Agent tracking for analytics #14

feat: add User-Agent tracking for analytics #14

Uh oh!

Conversation

richhankins commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

User-Agent Format

MCP Client Info

Changes

New utilities (src/core/utils.ts)

Updated configs

CLI commands

Dependencies

Testing

Uh oh!

augment-app-staging bot commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

augment-app-staging bot left a comment

Choose a reason for hiding this comment

Uh oh!

augment-app-staging bot Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

augment-app-staging bot Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

augment-app-staging bot Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

richhankins commented Feb 1, 2026

Uh oh!

augment-app-staging bot left a comment

Choose a reason for hiding this comment

Uh oh!

augment-app-staging bot Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

augment-app-staging bot Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

richhankins commented Feb 1, 2026

Uh oh!

augment-app-staging bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

augment-app-staging bot Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

richhankins Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

richhankins commented Jan 31, 2026 •

edited

Loading

New utilities (`src/core/utils.ts`)

augment-app-staging bot commented Jan 31, 2026 •

edited

Loading