@amplitude/ai 0.2.1 → 0.3.0

package/.claude/commands/instrument-with-amplitude-ai.md

@@ -0,0 +1,12 @@
+---
+description: Auto-instrument a JS/TS AI app with @amplitude/ai.
+allowed-tools: mcp__amplitude-ai__scan_project, mcp__amplitude-ai__validate_file, mcp__amplitude-ai__instrument_file, mcp__amplitude-ai__generate_verify_test, mcp__amplitude-ai__validate_setup, mcp__amplitude-ai__suggest_instrumentation, mcp__amplitude-ai__get_event_schema, mcp__amplitude-ai__get_integration_pattern, mcp__amplitude-ai__search_docs, Bash, Read, Write, Edit, Glob, Grep
+---
+
+# /instrument-with-amplitude-ai
+
+Read and follow `node_modules/@amplitude/ai/amplitude-ai.md` step by step.
+
+That file contains the complete 4-phase workflow: **Detect → Discover → Instrument → Verify**.
+
+If the `amplitude-ai` MCP server is connected, use `scan_project`, `validate_file`, `instrument_file`, and `generate_verify_test` tools to accelerate each phase.

package/.cursor/skills/instrument-with-amplitude-ai/SKILL.md

@@ -1,50 +1,12 @@
 ---
 name: instrument-with-amplitude-ai
-description: Detect framework, install @amplitude/ai dependencies, scaffold init code, and identify likely LLM call sites in JavaScript/TypeScript projects.
+description: Auto-instrument a JS/TS AI app with @amplitude/ai. Detects framework, discovers agents and LLM call sites, applies instrumentation, and verifies with tests.
 ---
 
 # /instrument-with-amplitude-ai
 
-## Goal
+Read and follow `node_modules/@amplitude/ai/amplitude-ai.md` step by step.
 
-Instrument a JS/TS app with `@amplitude/ai` quickly and safely.
+That file contains the complete 4-phase workflow: **Detect → Discover → Instrument → Verify**.
 
-## Steps
-
-1. Detect project type from `package.json` and lockfiles:
-   - web apps: `next`, `react`, `vite`
-   - APIs: `express`, `fastify`, `hono`
-   - workers/CLI: no web framework, but provider SDKs present
-2. Install deps:
-   - `pnpm add @amplitude/ai`
-   - provider packages used by the app (`openai`, `@anthropic-ai/sdk`, etc.)
-3. Scaffold bootstrap:
-   - run `amplitude-ai init`
-   - ensure `AMPLITUDE_AI_API_KEY` is documented in `.env.example`
-4. Identify likely LLM call sites (priority order):
-   - provider SDK direct calls:
-     - `openai.chat.completions.create`
-     - `openai.responses.create`
-     - `anthropic.messages.create`
-   - framework integrations:
-     - route handlers (`app.get/post`, `router.*`, Next route handlers)
-     - agent orchestration loops and tool executors
-5. Add instrumentation (choose one path):
-   - zero-code: `patch({ amplitudeAI })`
-   - explicit wrappers: `wrap(existingClient, amplitudeAI)`
-   - explicit lifecycle: `ai.agent(agentId, { userId }).session({ sessionId })`
-   - function tracing: `tool(...)` / `observe(...)`
-6. Validate:
-   - run `amplitude-ai doctor`
-   - run tests and typecheck
-   - verify generated files are fresh: `pnpm --filter @amplitude/ai check:generated`
-7. Suggested ripgrep probes:
-   - `openai|anthropic|chat\\.completions|responses\\.create|messages\\.create`
-   - `agent\\(|session\\(|tool\\(|observe\\(`
-
-## Safety checks
-
-- Do not modify unrelated files.
-- Prefer adding instrumentation near existing provider calls.
-- Keep content mode explicit if privacy constraints apply.
-- Do not duplicate instrumentation (avoid wrapping and patching the same call path twice).
+If the `amplitude-ai` MCP server is connected, use `scan_project`, `validate_file`, `instrument_file`, and `generate_verify_test` tools to accelerate each phase.

package/AGENTS.md

@@ -1,12 +1,55 @@
-<!-- GENERATED FILE: do not edit manually -->
-
 # AGENTS.md
 
-Package: `@amplitude/ai` v0.2.1
+Package: `@amplitude/ai` v0.3.0
 
 ## Install
 
-- `pnpm add @amplitude/ai`
+```bash
+pnpm add @amplitude/ai
+```
+
+## MCP Server Setup
+
+The SDK ships an MCP server for AI coding agents. It provides project scanning,
+file validation, instrumentation, test generation, and the complete API reference.
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+```json
+{
+  "mcpServers": {
+    "amplitude-ai": {
+      "command": "npx",
+      "args": ["amplitude-ai", "mcp"]
+    }
+  }
+}
+```
+Then point the agent at the instrumentation guide: `node_modules/@amplitude/ai/amplitude-ai.md`
+
+### Claude Code
+
+```bash
+claude mcp add amplitude-ai -- npx amplitude-ai mcp
+```
+Then point the agent at the instrumentation guide: `node_modules/@amplitude/ai/amplitude-ai.md`
+
+### OpenAI Codex CLI
+
+Add to `~/.codex/config.toml`:
+```toml
+[mcp_servers.amplitude-ai]
+command = "npx"
+args = ["amplitude-ai", "mcp"]
+```
+Codex auto-reads this `AGENTS.md` file for context.
+
+### Generic (any MCP-compatible agent)
+
+```json
+{ "amplitude-ai": { "command": "npx", "args": ["amplitude-ai", "mcp"] } }
+```
 
 ## Decision Tree
 
@@ -15,28 +58,53 @@ Package: `@amplitude/ai` v0.2.1
 - Need user/session lineage: use `ai.agent(...).session(...)`.
 - Multiple agents collaborating: use `session.runAs(childAgent, fn)` for automatic identity propagation.
 - Need tool telemetry: use `tool()`.
+- Need span/observability: use `observe()`.
 - Need agent-assistant guidance: run MCP prompt `instrument_app`.
 
-## Canonical Patterns
+## MCP Surface
 
-- zero-code patching
-- wrap-openai
-- bound-agent-session
-- multi-agent-runas
-- tool-decorator
-- express-middleware
+Tools:
+- `get_event_schema`
+- `get_integration_pattern`
+- `validate_setup`
+- `suggest_instrumentation`
+- `validate_file`
+- `search_docs`
+- `scan_project`
+- `generate_verify_test`
+- `instrument_file`
+
+Resources:
+- `amplitude-ai://event-schema`
+- `amplitude-ai://integration-patterns`
+- `amplitude-ai://instrument-guide`
+
+Prompt:
+- `instrument_app` — Full guided instrumentation with embedded SKILL.md
 
-## MCP Surface
+## Canonical Patterns
 
-- Tools: `get_event_schema`, `get_integration_pattern`, `validate_setup`, `suggest_instrumentation`, `validate_file`, `search_docs`
-- Resources: `amplitude-ai://event-schema`, `amplitude-ai://integration-patterns`
-- Prompt: `instrument_app`
+- zero-code patching — `patch({ amplitudeAI: ai })`
+- wrap-openai — `wrap(existingClient, ai)`
+- bound-agent-session — `ai.agent('id').session({ userId }).run(fn)`
+- multi-agent-runas — `s.runAs(childAgent, fn)`
+- tool-decorator — `tool(fn, { name: 'tool_name' })`
+- observe-spans — `observe(fn, { name: 'span-name' })`
+- express-middleware — `createAmplitudeAIMiddleware({ amplitudeAI: ai, userIdResolver })`
 
 ## Gotchas
 
 - `tool()` in Node requires explicit JSON schema for robust agent input shaping.
 - Keep `AMPLITUDE_AI_API_KEY` available in runtime env for telemetry delivery.
 - Use `MockAmplitudeAI` for deterministic tests.
+- Call `ai.flush()` before returning from serverless handlers (Next.js, Lambda, Vercel).
+- `session.run()` relies on `AsyncLocalStorage`; not available in Edge Runtime.
+
+## CLI
+
+- `amplitude-ai mcp` — Start the MCP server for AI coding agents
+- `amplitude-ai doctor [--json]` — Validate environment, deps, and event pipeline
+- `amplitude-ai status [--json]` — Show SDK version, installed providers, and env config
 
 ## Testing
 
@@ -44,13 +112,6 @@ Package: `@amplitude/ai` v0.2.1
 - Run typecheck: `pnpm --filter @amplitude/ai test:typescript`
 - Run docs freshness: `node scripts/generate-agent-docs.mjs --check`
 
-## CLI
-
-- `amplitude-ai init [--dry-run] [--force]`
-- `amplitude-ai doctor`
-- `amplitude-ai status`
-- `amplitude-ai mcp`
-
 ## Examples
 
 - `examples/zero-code.ts`
@@ -59,13 +120,10 @@ Package: `@amplitude/ai` v0.2.1
 - `examples/framework-integration.ts`
 - `examples/real-openai.ts` (requires OPENAI_API_KEY)
 
-## Extended Reference
-
-- `llms-full.txt` — Full API signatures and canonical patterns for LLM agents
-
-## Cursor Skill
+## Instrumentation Guide
 
-- `.cursor/skills/instrument-with-amplitude-ai/SKILL.md`
+- `amplitude-ai.md` — **Start here.** Complete 4-phase instrumentation workflow + API reference. Paste into any coding agent.
+- `llms-full.txt` — Extended API reference with MCP tools and patterns
 
 ## Event Schema (names)