From 5d6c9b4bd5320674183721e5aab8a1bc82b2731f Mon Sep 17 00:00:00 2001 From: "wizard-ci-bot[bot]" <254716194+wizard-ci-bot[bot]@users.noreply.github.com> Date: Thu, 8 Oct 2026 09:30:36 +0000 Subject: [PATCH] wizard-ci: typescript-sdk/stdio-server --- .../skills/mcp-analytics/.posthog-wizard | 0 .../.claude/skills/mcp-analytics/SKILL.md | 399 ++++ .../mcp-analytics/references/COMMANDMENTS.md | 12 + .../references/conversation-id.md | 98 + .../mcp-analytics/references/custom-events.md | 147 ++ .../references/custom-servers.md | 58 + .../skills/mcp-analytics/references/events.md | 153 ++ .../references/identifying-users.md | 156 ++ .../mcp-analytics/references/installation.md | 58 + .../skills/mcp-analytics/references/intent.md | 204 ++ .../skills/mcp-analytics/references/sdk-v2.md | 58 + .../mcp-analytics/references/start-here.md | 377 ++++ .../typescript-sdk/stdio-server/.gitignore | 1 + .../stdio-server/package-lock.json | 1801 +++++++++++++++++ .../typescript-sdk/stdio-server/package.json | 2 + .../posthog-mcp-analytics-report.md | 27 + .../typescript-sdk/stdio-server/src/index.ts | 18 + 17 files changed, 3569 insertions(+) create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/.posthog-wizard create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/SKILL.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/COMMANDMENTS.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/conversation-id.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/custom-events.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/custom-servers.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/events.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/identifying-users.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/installation.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/intent.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/sdk-v2.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/start-here.md create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/.gitignore create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/package-lock.json create mode 100644 apps/mcp-analytics/typescript-sdk/stdio-server/posthog-mcp-analytics-report.md diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/.posthog-wizard b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/.posthog-wizard new file mode 100644 index 000000000..e69de29bb diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/SKILL.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/SKILL.md new file mode 100644 index 000000000..601cd6cd3 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/SKILL.md @@ -0,0 +1,399 @@ +--- +name: mcp-analytics +description: >- + Add PostHog MCP analytics to a TypeScript, JavaScript, or Python MCP server. + Captures tool calls, agent intent, failures, and protocol revision, plus + self-reported model identity on supported TypeScript paths. Both SDKs support + legacy sessions and the handshake-free 2026-07-28 revision. Detects the server + style and wires in compatible instrumentation, credentials, conversation + correlation, and graceful shutdown. +metadata: + author: PostHog + version: dev +--- + +# Add PostHog MCP analytics + +Use this skill to instrument a user's own **MCP server** with PostHog MCP analytics. Once instrumented, every tool call, agent intent, and failure the server handles is captured as a `$mcp_*` event in PostHog. Supported TypeScript instrumentation paths can also capture the agent's self-reported model, so the user can compare quality, errors, and latency by model. + +There are two SDKs and this skill handles both: +- **TypeScript / JavaScript** — the [`@posthog/mcp`](https://posthog.com/docs/mcp-analytics) Node package. +- **Python** — `posthog.mcp`, which ships inside the [`posthog`](https://posthog.com/docs/libraries/python) package (like `posthog.ai`). + +This is **not** about adding the PostHog MCP *server* to a coding agent (that's `wizard mcp add`). This skill instruments the user's *own* MCP server code so it reports analytics about itself. + +## Scope and guardrails + +- **TypeScript / JavaScript and Python are supported.** Detect the language in STEP 1 and follow the matching part of every step. If the MCP server is written in anything else (Go, Rust, …), **stop**: emit `[ABORT] unsupported language for mcp analytics` on its own line and do nothing else. +- **This must be an MCP server.** Search thoroughly before concluding there isn't one: check dependency manifests *and* source for the STEP 1 signals across the whole project, including monorepo workspace packages and subdirectories — a server is often under `packages/*`, `apps/*`, `server/`, or `src/`, not the repo root. Only after an exhaustive search finds nothing, **stop**: emit `[ABORT] no mcp server found` on its own line, and in the same message tell the user where you looked and to re-run the command from inside the package or directory that actually defines their MCP server. Do nothing else. +- **Beta SDK.** Both SDKs are pre-1.0 and may ship breaking changes in minor releases. Pin a version (see STEP 3). +- **Minimal, additive changes only.** Add instrumentation alongside the existing server; do not restructure tool handlers or change their behavior. The wrapper is designed to be one line. + +### Abort cases + +If anything blocks instrumentation, **always** emit exactly one `[ABORT] ` line and stop — never halt, finish, or error out silently. The wizard catches `[ABORT]` and terminates the run for you; don't try to exit yourself. A silent stop is recorded as a failed run with no reason, which can't be acted on, so every dead end must carry a reason. Use one of: + +- `[ABORT] no mcp server found` — an exhaustive search (see the guardrail above) found no MCP server in the project. +- `[ABORT] unsupported language for mcp analytics` — the server is neither TypeScript/JavaScript nor Python. +- `[ABORT] could not locate the server entry point` — MCP signals are present, but the place the server is constructed or where requests are dispatched couldn't be found to instrument. +- `[ABORT] ` — anything else that blocks the run (e.g. no readable project, or no PostHog credentials and no MCP server connected to fetch them). Keep it short and specific so it's useful when aggregated across runs. + +## Instructions + +Follow these steps IN ORDER. Each step has a **TypeScript / JavaScript** part and a **Python** part — use the one for the language you detect in STEP 1. + +### STEP 1: Identify the language and the MCP server entry point + +Determine the language first, then route to the matching instructions throughout: + +- **TypeScript / JavaScript** — there's a `package.json`. Look for MCP signals in dependencies and source: + - `@modelcontextprotocol/sdk` — the official SDK, **v1** (most common). + - `@modelcontextprotocol/server` / `@modelcontextprotocol/core` / `@modelcontextprotocol/client` — the official SDK, **v2**. A v2 project has no `@modelcontextprotocol/sdk` at all, so never read that one package's absence as "no MCP server here". + - `mcp-handler` — the Next.js / Vercel adapter. + - `@rekog/mcp-nest` — the NestJS adapter (tools defined with `@Tool()` decorators; the server is built inside `McpModule.forRoot(...)`, so there's no `new McpServer` in user code). + - `fastmcp`, `xmcp`, or a similar TS MCP framework. + - A custom HTTP/edge handler speaking the MCP protocol directly (JSON-RPC methods like `tools/call`, `initialize`, an `Mcp-Session-Id` header) with none of the above. + + Determine the package manager from the lockfile (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`). + + **Record which SDK major the project is on.** STEP 2, STEP 3, and STEP 4 each contain a **For `@modelcontextprotocol/sdk` (v1)** and a **For `@modelcontextprotocol/server` (v2)** section — follow only the one matching the major found here. `sdk-v2.md` is the reference for everything v2-specific. + +- **Python** — there's a `pyproject.toml`, `requirements.txt`, or `setup.py`, or `.py` sources. Look for MCP signals: + - the official `mcp` package — `from mcp.server.fastmcp import FastMCP` on 1.x, `from mcp.server.mcpserver import MCPServer` on 2.x, or `from mcp.server.lowlevel import Server` on either major. + - jlowin's standalone `fastmcp` 2.0 — `from fastmcp import FastMCP`. + - a custom HTTP/edge dispatcher (FastAPI / Starlette / Flask / edge) speaking the MCP protocol directly with no server object to wrap. + + Determine the installer (pip / uv / poetry) from the lockfile / `pyproject.toml`. + + Record which official `mcp` major the project uses. The wrapper is tested against `mcp>=1.26,<3`; don't confuse this with jlowin's separately versioned `fastmcp` package. + +- If it's neither TS/JS nor Python, apply the guardrail above and stop. + +Then identify the file and the exact place where the server is constructed or where MCP requests are dispatched, and read it before editing. If PostHog MCP analytics is already wired in (an `instrument(` call, or a `PostHogMCP` client in either language), don't duplicate it. Verify the existing setup against STEP 4, add supported modern options that are missing, then continue through STEP 7. + +### STEP 2: Choose the instrumentation path + +Pick exactly one based on what STEP 1 found. When in doubt, read the bundled reference docs — `installation.md` covers the wrapping paths; `custom-servers.md` covers the custom-dispatcher paths; `sdk-v2.md` covers what differs on MCP SDK v2. + +#### TypeScript / JavaScript + +- **Path A — official SDK server object** (`new Server(...)` or `new McpServer(...)` from the official SDK, either major): wrap it with `instrument(server, posthog)`. One line. `instrument()` detects the server's shape at runtime, so the call is the same on both majors — never branch the code you write on which major is installed. +- **Path B — `mcp-handler`** (`createMcpHandler((server) => { ... })`): same `instrument(server, posthog)` call, inside the setup callback. Because Vercel's transport is stateless, also wire `identify` (STEP 4) and flush per invocation (STEP 6). +- **Path C — custom dispatcher** (Hono / Express / Cloudflare Worker / edge function with no SDK server object to wrap): use the `PostHogMCP` client and call `captureToolCall` / `captureInitialize` yourself at the dispatch points. +- **Path D — `@rekog/mcp-nest`** (NestJS): the framework builds the server, so there's no `new McpServer` for you to wrap. Instrument it through the module's `serverMutator` hook in `McpModule.forRoot(...)`. See STEP 4. + +On Paths A and B, the SDK major recorded in STEP 1 decides the specifics — STEP 3 and STEP 4 each have a matching section per major: + +##### For @modelcontextprotocol/sdk (v1) + +The server object comes from `@modelcontextprotocol/sdk`. Follow the **v1** sections of STEP 3 and STEP 4; `installation.md` is the reference. + +##### For @modelcontextprotocol/server (v2) + +The server object comes from `@modelcontextprotocol/server`. Follow the **v2** sections of STEP 3 and STEP 4; `sdk-v2.md` is the reference for everything v2-specific. + +#### Python + +- **Path P1 — a high-level or low-level server** (the official `mcp` package's 1.x `FastMCP`, 2.x `MCPServer`, or `Server` from either major; or jlowin's standalone `fastmcp` package): wrap it with `instrument(server, posthog)`. One line — the SDK detects the framework and major. +- **Path P2 — custom dispatcher** (FastAPI / Starlette / Flask / edge with no server object to wrap): use the `PostHogMCP` client and call `capture_tool_call` / `capture_initialize` yourself at the dispatch points. + +### STEP 3: Install the SDK + +#### TypeScript / JavaScript + +Install `@posthog/mcp` and `posthog-node` with the project's package manager, pinning `@posthog/mcp` to its current published version (it's pre-1.0) — e.g. `pnpm add @posthog/mcp@ posthog-node`. Read the installed version back from `package.json` / the lockfile rather than guessing. Self-reported model capture requires `@posthog/mcp>=0.12.0` on wrapping paths and `@posthog/mcp>=0.13.0` on the custom-dispatcher path; upgrade an older installed version before enabling it. + +**Never install an MCP SDK.** Both majors are *optional* peer dependencies of `@posthog/mcp`, and the project already has the one it uses. Adding the other pulls in a whole SDK the code never imports. + +##### For @modelcontextprotocol/sdk (v1) + +No extra constraint — pinning the current published `@posthog/mcp` release is enough. + +##### For @modelcontextprotocol/server (v2) + +`@posthog/mcp` must be **`>=0.11.2`**. If the project already depends on something older, upgrade it — earlier versions rejected high-level v2 servers in a compatibility check that `instrument()` swallows, so the integration looked healthy and captured nothing at all. + +#### Python + +The SDK ships inside `posthog`, so install (or require) `posthog>=7.40.0` with the project's installer — e.g. `pip install "posthog>=7.40.0"`, `uv add "posthog>=7.40.0"`, `poetry add "posthog>=7.40.0"`. Version 7.40.0 added official MCP SDK 2.x and `2026-07-28` support. The MCP SDK is a peer dependency tested across `mcp>=1.26,<3`; don't add or change it as part of this command. jlowin's standalone `fastmcp` package is also supported. A custom-dispatcher (path P2) project needs nothing beyond `posthog`. + +### STEP 4: Instrument the server + +Create the PostHog client **once at module scope** (never per request), reading credentials from env (set up in STEP 5). + +#### TypeScript / JavaScript + +```ts +import { PostHog } from "posthog-node" + +const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, { + host: process.env.POSTHOG_HOST, // https://us.i.posthog.com or https://eu.i.posthog.com +}) +``` + +**Path A — official SDK server:** wrap the server with `instrument(server, posthog)` immediately after constructing it. `instrument()` is idempotent per server and returns an analytics handle (used later for custom events). It works on both the low-level `Server` and the high-level `McpServer`, and the wrapping line is identical on both majors — only the SDK import differs. Use the section matching the major from STEP 1: + +##### For @modelcontextprotocol/sdk (v1) + +```ts +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js" +import { instrument } from "@posthog/mcp" + +const server = new McpServer({ name: "my-mcp-server", version: "1.0.0" }) +const analytics = instrument(server, posthog, { + captureModel: true, +}) // wrap immediately after constructing the server +// register tools as usual — tools added after instrument() are still captured +``` + +##### For @modelcontextprotocol/server (v2) + +```ts +import { McpServer } from "@modelcontextprotocol/server" +import { instrument } from "@posthog/mcp" + +const server = new McpServer({ name: "my-mcp-server", version: "1.0.0" }) +const analytics = instrument(server, posthog, { + captureModel: true, + enableConversationId: true, +}) // wrap immediately after constructing the server +// register tools with registerTool() as usual — tools added after instrument() are still captured +``` + +v2 reminders: + +- Tools register with `registerTool()` — the deprecated `server.tool()` was removed in v2. +- `@posthog/mcp` must be `>=0.11.2` (STEP 3). +- If the project already calls `instrument(server.server)` — a workaround for an old compatibility check that rejected high-level v2 servers — change it back to `instrument(server)`. + +**Path B — `mcp-handler`:** call `instrument(server, posthog)` as the first line of the setup callback, with the `posthog` client created at module scope (not per request). Because the transport is stateless, group calls by user with `identify`: + +```ts +import { instrument, getRequestHeaders } from "@posthog/mcp" + +const handler = createMcpHandler((server) => { + instrument(server, posthog, { + captureModel: true, + enableConversationId: true, + identify: async (request, extra) => { + const token = getRequestHeaders(extra)?.["authorization"] + return token ? { distinctId: await resolveUserId(token) } : null + }, + }) + server.registerTool("...", { /* ... */ }, async () => { /* ... */ }) +}) +``` + +**Always read request headers through `getRequestHeaders(extra)`** — in `identify`, `intentFallback`, `eventProperties` and `beforeSend` alike, on either major. The callbacks receive the MCP SDK's `extra` unchanged, and the two majors shape its headers differently — a hand-rolled read that works on one silently returns `undefined` on the other, so `identify()` returns `null` and every event goes out anonymous with no error anywhere. The helper handles both majors and returns a plain lowercase-keyed object. `sdk-v2.md` documents the per-major shapes. + +**Path C — custom dispatcher:** swap the existing PostHog client for `PostHogMCP` (a drop-in `posthog-node` subclass) and call the capture helpers at the dispatch points. Read `custom-servers.md` for the full field reference before editing. + +```ts +import { PostHogMCP } from "@posthog/mcp" + +const posthog = new PostHogMCP(process.env.POSTHOG_PROJECT_TOKEN, { + host: process.env.POSTHOG_HOST, + captureModel: true, +}) + +// when building the tools/list response: +const serverTools = getServerTools() +const advertisedTools = posthog.prepareToolList(serverTools) + +// only on a 2025-11-25 initialize handshake: +posthog.captureInitialize({ clientName, clientVersion, distinctId, protocolVersion: "2025-11-25" }) + +// after each tools/call resolves (wrap the existing handler, time it): +const start = Date.now() +const originalTool = serverTools.find((tool) => tool.name === request.params.name) +const { args, intent, intentSource, llmModel, llmModelSource } = posthog.prepareToolCall( + request.params.name, + request.params.arguments, + { originalTool }, +) +const result = await runTool(request.params.name, args) +posthog.captureToolCall({ + toolName: request.params.name, + parameters: args, + response: result, + durationMs: Date.now() - start, + isError: false, + intent, + intentSource, + llmModel, + llmModelSource, + distinctId, // who the request is from, if known + sessionId, // your transport/session id, if you have one + protocolVersion, // read this from the current request +}) +``` + +Return `advertisedTools` from `tools/list`. Always dispatch the cleaned `args`, not the raw request arguments. Pass the raw `originalTool` descriptor on every call so model ownership remains correct when `tools/list` and `tools/call` reach different replicas. The helper preserves an application-owned `llm_model` field and declines to capture it. + +Resolve `distinctId` / `sessionId` from whatever auth/session the dispatcher already has; omit them rather than inventing values. Pass `protocolVersion` on every capture. On `2025-11-25`, use the revision the dispatcher's existing session state negotiated during initialize. On `2026-07-28`, read `MCP-Protocol-Version` from the current request because there is no initialize handshake or protocol session. If the dispatcher exposes neither source, omit the property rather than hardcoding a revision. Don't fabricate `$mcp_initialize` on `2026-07-28`. Conversation-id injection isn't available on the custom-dispatcher path. Model capture is self-reported and unverified. These calls are fire-and-forget and never throw, so they can't take down a tool. + +**Path D — `@rekog/mcp-nest` (NestJS):** the framework builds the server, so pass a `serverMutator` to `McpModule.forRoot(...)`. Prefer the `instrumentMutator` helper — it instruments the server and returns it, so it drops straight into the hook: + +```ts +import { Module } from "@nestjs/common" +import { McpModule } from "@rekog/mcp-nest" +import { PostHog, instrumentMutator } from "@posthog/mcp" + +const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, { + host: process.env.POSTHOG_HOST, +}) + +@Module({ + imports: [ + McpModule.forRoot({ + name: "my-mcp-server", + version: "1.0.0", + serverMutator: instrumentMutator(posthog, { + enableConversationId: true, + }), + }), + ], +}) +class AppModule {} +``` + +`instrumentMutator` returns the server (not `instrument()`'s handle), so it slots straight into the hook. Compose with an existing `serverMutator` if there is one, and handlers nest registers after the mutator runs are still captured. For [custom events](https://posthog.com/docs/mcp-analytics/custom-events), call `instrument()` directly inside your own mutator and keep its handle, returning the server yourself. + +If mcp-nest keeps one persistent server instance, also set `captureModel: true`. Don't enable it when `statelessMode: true` creates a fresh low-level server per request: that path advertises `llm_model` but can't confirm ownership before the call, so the model property stays empty. + +##### For @modelcontextprotocol/server (v2), any path — sessions and protocol revisions + +Protocol revision is a property of each *request*, not of the server. A v2 server serves `2025-11-25` traffic too, so instrument once and never branch on the major. The `2026-07-28` revision removed the `initialize` handshake and the `Mcp-Session-Id` header, so on that traffic **every request becomes its own `$session_id`** unless `enableConversationId: true` is set. Enable it on supported v2 wrapping paths. `captureModel: true` works on both revisions, and its value is self-reported and unverified. `sdk-v2.md` has the rest, including MCP Apps compatibility and the current instrumentation gaps. + +#### Python + +```python +import os +from posthog import Posthog + +posthog = Posthog( + os.environ["POSTHOG_PROJECT_TOKEN"], + host=os.environ["POSTHOG_HOST"], # https://us.i.posthog.com or https://eu.i.posthog.com +) +``` + +**Path P1 — FastMCP / low-level Server:** + +```python +from posthog.mcp import instrument + +server = FastMCP("my-mcp-server") +analytics = instrument(server, posthog) # wrap right after constructing the server +# register tools as usual — tools added after instrument() are still captured +``` + +`instrument()` is idempotent per server and returns an analytics handle (used later for custom events). The same call works on the official MCP SDK 1.x `FastMCP`, 2.x `MCPServer`, the low-level `Server` from either major, and jlowin's standalone `fastmcp` package. + +For the official `mcp` 2.x SDK, enable conversation IDs because `2026-07-28` has no protocol session: + +```python +from posthog.mcp.types import MCPAnalyticsOptions + +analytics = instrument( + server, + posthog, + MCPAnalyticsOptions(enable_conversation_id=True), +) +``` + +**Path P2 — custom dispatcher:** swap the existing client for `PostHogMCP` (a drop-in `posthog` client subclass) and call the capture helpers at the dispatch points. Read `custom-servers.md` for the full field reference before editing. + +```python +import time +from posthog.mcp import PostHogMCP + +posthog = PostHogMCP(os.environ["POSTHOG_PROJECT_TOKEN"], host=os.environ["POSTHOG_HOST"]) + +# only on a 2025-11-25 initialize handshake: +posthog.capture_initialize( + client_name=client_name, + client_version=client_version, + distinct_id=distinct_id, + protocol_version="2025-11-25", +) + +# after each tools/call resolves (time it): +start = time.monotonic() +# ...run the tool... +posthog.capture_tool_call( + request.params.name, + parameters=arguments, + response=result, + duration_ms=(time.monotonic() - start) * 1000, + is_error=False, + distinct_id=distinct_id, # who the request is from, if known + session_id=session_id, # your transport/session id, if you have one + protocol_version=protocol_version, # read this from the current request +) +``` + +Resolve `distinct_id` / `session_id` from whatever auth/session the dispatcher already has; omit them rather than inventing values. Pass `protocol_version` on every capture. On `2025-11-25`, use the revision the dispatcher's existing session state negotiated during initialize. On `2026-07-28`, read `MCP-Protocol-Version` from the current request because there is no initialize handshake or protocol session. If the dispatcher exposes neither source, omit the property rather than hardcoding a revision. Don't call `capture_initialize` on `2026-07-28`. Python doesn't support self-reported model capture yet, so don't add an `llm_model` field. These calls are fire-and-forget and never throw, so they can't take down a tool. + +### STEP 5: Wire up credentials + +- Check existing env files (`.env`, `.env.local`, etc.) for a PostHog project token. If a valid `phc_…` token and host are already set, reference those and skip the rest of this step. +- If the token is missing, use the PostHog MCP server's `projects-get` tool to fetch the project's `api_token`. If multiple projects come back, ask the user which to use. If the MCP server isn't connected, ask the user for their project token directly. +- Host: `https://us.i.posthog.com` for US Cloud, `https://eu.i.posthog.com` for EU Cloud. +- Write `POSTHOG_PROJECT_TOKEN` and `POSTHOG_HOST` to the appropriate env file and reference them in code (`process.env.*` in JS, `os.environ[...]` in Python) — never hardcode the token. + +### STEP 6: Ensure events get flushed + +The PostHog client batches events; the user owns the client's lifecycle. + +**TypeScript / JavaScript:** + +- **Long-running server (STDIO or a persistent HTTP server):** drain on shutdown. + + ```ts + process.on("SIGTERM", async () => { + await posthog.shutdown() + process.exit(0) + }) + ``` + +- **Serverless / edge (mcp-handler on Vercel, Workers, Lambda):** `SIGTERM` is unreliable — flush at the end of each invocation with `await posthog.flush()`, or `ctx.waitUntil(posthog.flush())` where supported. +- **STDIO transports specifically:** the server's stdout is the protocol channel. Do not add `console.log` for debugging — it corrupts the MCP stream. If you need SDK-internal warnings, pass a `logger` option to `instrument()` that writes to stderr or a file. + +**Python:** + +- **Long-running server (STDIO or persistent HTTP):** drain on exit. On the `instrument()` path, `await analytics.flush()` waits for in-flight auto-capture events, then `posthog.shutdown()` flushes and stops the client — call both from your shutdown path. For `PostHogMCP`, `posthog.shutdown()` (or `posthog.flush()`) drains the MCP captures first. +- **STDIO transports specifically:** stdout is the protocol channel — never `print()` to it. For SDK-internal warnings pass `logger=lambda m: print(m, file=sys.stderr)` (or a file writer) via `MCPAnalyticsOptions(...)`. + +### STEP 7: Verify + +- **TypeScript / JavaScript:** run the project's type-check and/or build script (e.g. `tsc --noEmit`, `pnpm build`) and fix any errors your changes introduced. Run any linter/formatter the project uses on the files you touched. +- **Python:** run the project's type-check / tests if present (`mypy`, `pytest`) and fix any errors your changes introduced. Run any formatter the project uses (`ruff`, `black`) on the files you touched. +- For any supported TypeScript path with model capture, verify `tools/list` advertises a required `llm_model` string, the tool handler doesn't receive it, and a non-`unknown` answer lands on `$mcp_tool_call` as `$mcp_llm_model` with `$mcp_llm_model_source = "self_reported"`. +- For a `2026-07-28` wrapping path, verify the first tool call captures without an initialize request. When conversation IDs are enabled, verify the returned handle is echoed on the next call and produces the same `$session_id`. +- Don't expect automatic `$mcp_resources_list`, `$mcp_resource_read`, `$mcp_prompts_list`, or `$mcp_prompt_get` events. Those names are reserved, but the wrappers don't emit them yet. +- Check every event name in the final report against `events.md`. Failed tools remain `$mcp_tool_call` events with `$mcp_is_error = true` and can emit a sibling `$exception`; there is no `$mcp_tool_failed` event. +- Summarize for the user: which path you used, the files you changed, the env vars to set, and that they'll see `$mcp_*` events in PostHog once the server handles its next request. Link them to https://posthog.com/docs/mcp-analytics for the dashboard and event reference. + +## Reference files + +- `references/installation.md` - Install mcp analytics +- `references/sdk-v2.md` - MCP TypeScript SDK v1 vs v2 — read when the project uses @modelcontextprotocol/server +- `references/custom-servers.md` - Install mcp analytics +- `references/intent.md` - Capturing agent intent +- `references/identifying-users.md` - Identifying users +- `references/conversation-id.md` - Conversation ids +- `references/events.md` - Event and property reference +- `references/custom-events.md` - Custom events and metadata +- `references/start-here.md` - Getting started with mcp analytics +- `references/COMMANDMENTS.md` - Framework-specific rules the integration must follow + +`installation.md` is the source of truth for the wrapping paths (A/B and Python P1) and the full `instrument()` options table (`identify`, `context`/intent, TypeScript-only `captureModel`, `enableConversationId`/`enable_conversation_id`, `reportMissing`/`report_missing`, `beforeSend`/`before_send`, `eventProperties`/`event_properties`). `custom-servers.md` is the source of truth for the custom-dispatcher paths (C and P2), including the `2026-07-28` rule that no initialize event exists. `sdk-v2.md` is the source of truth for both SDK-major splits, sessions on `2026-07-28`, MCP Apps compatibility, and current instrumentation gaps. `intent.md`, `identifying-users.md`, and `conversation-id.md` cover optional enrichment; `events.md` and `custom-events.md` describe what gets captured. + +## Key principles + +- **One server, one wrapper.** `instrument()` is idempotent; don't call it twice on the same server. +- **Module-scope client.** Construct the `PostHog` / `Posthog` / `PostHogMCP` client once, not per request. +- **Env, never hardcode.** The project token and host come from environment variables. +- **Additive only.** Don't change tool behavior or restructure the server — just wrap/capture. +- **Don't break STDIO.** No `console.*` (JS) or `print()` (Python) on STDIO transports; use a `logger` instead. +- **Pin the beta SDK** and tell the user it's pre-1.0. (Python: `posthog.mcp` ships inside `posthog`; require `posthog>=7.40.0` for MCP SDK 2.x support.) diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/COMMANDMENTS.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/COMMANDMENTS.md new file mode 100644 index 000000000..18e04ed70 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/COMMANDMENTS.md @@ -0,0 +1,12 @@ +# Framework rules + +Follow these when integrating PostHog into this framework. + +- A missing PostHog configuration must never break the app — read keys optionally (never a required setting), guard init and capture behind their presence, and keep build and boot working with no PostHog environment set — but never silently: in development or debug builds fail loudly, using the language's idiomatic error, with the message " variable required by PostHog is missing or un-configured, this causes events to be silently missed. This error stops appearing once is configured" (substituting the actual variable name); production stays a no-op +- posthog-node is the Node.js server-side SDK package name; posthog-js is browser-only, so use posthog-node on the server instead +- Include enableExceptionAutocapture: true in the PostHog constructor options +- Add posthog.capture() calls in route handlers for meaningful user actions – every route that creates, updates, or deletes data should track an event with contextual properties +- Add posthog.captureException(err, distinctId) in the application's error handler (e.g., Express error middleware, Fastify setErrorHandler, Koa app.on('error')) +- The SDK batches events and flushes asynchronously. await flush() or await shutdown() before letting that process exit. If unsure, set flushAt 1 and flushInterval 0. +- `posthog.capture()` enqueues synchronously and returns; the batched HTTP send happens afterwards. Treat every per-request handler as short-lived even when the framework feels like a server: Next.js / Nuxt / SvelteKit / Remix route handlers, serverless and edge functions, and Lambda are torn down per invocation before the send runs. Create the client with flushAt 1 and flushInterval 0, then await the send before returning. Always use `await posthog.flush()` for a shared/singleton client, `await posthog.shutdown()` for a per-request client. Never skip the awaited flush or risk the enqueued event being silently dropped. +- Reverse proxy is NOT needed for server-side Node.js – only client-side JavaScript needs a proxy to avoid ad blockers diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/conversation-id.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/conversation-id.md new file mode 100644 index 000000000..2164ad918 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/conversation-id.md @@ -0,0 +1,98 @@ +> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt + +# Conversation IDs + +A PostHog `$session_id` normally follows the MCP protocol session. The handshake-free `2026-07-28` revision has no protocol session, so each request gets a new session unless you add another correlation signal. + +`$mcp_conversation_id` groups those calls by conversation. The SDK also derives `$session_id` from an accepted conversation handle, so PostHog session queries group the same calls. + +**Enabled by default** + +Conversation IDs are enabled by default. Calls stay correlated when the agent echoes the handle returned in tool results. + +## Enabling + +Conversation IDs are on by default in every SDK, with no configuration. + +The SDK does three things: + +1. **Injects an optional `conversation_id` argument** into compatible tool schemas, with a description telling the agent to reuse the value the server returns. +2. **Creates a handle** when needed and returns it on eligible tool responses as a `{"conversation_id":"…"}` text block. +3. **Captures the handle** as `$mcp_conversation_id`. When the agent echoes a valid handle, the SDK derives a stable `$session_id` from it. Until then, existing protocol sessions remain in use. + +The SDK reuses an echoed UUIDv7 that matches the handles it creates. It replaces missing or arbitrary values with a new handle to avoid merging unrelated conversations. + +The Go SDK mints a handle only when the call has no transport session. When there is one, it ignores an invalid value instead. It never mints a handle for an unknown tool, a handler error, or an `input_required` round. + +## Event properties + +``` +{ + event: "$mcp_tool_call", + properties: { + "$session_id": "ses_2a3f…", // derived from the conversation handle + "$mcp_conversation_id": "0198f2d6-…", // echoed UUIDv7 conversation handle + "$mcp_tool_name": "search_events", + ... + } +} +``` + +A new request or connection made by the same agent reusing the same `conversation_id` shares both `$mcp_conversation_id` and `$session_id`. You can group by the conversation property in HogQL: + +SQL + +[Run in PostHog](https://us.posthog.com/sql?open_query=SELECT%0A++properties.%24mcp_conversation_id+AS+conversation%2C%0A++arrayDistinct%28groupArray%28properties.%24mcp_tool_name%29%29+AS+tools_called%2C%0A++count%28%29+AS+tool_calls%0AFROM+events%0AWHERE+event+%3D+'%24mcp_tool_call'%0A++AND+properties.%24mcp_conversation_id+IS+NOT+NULL%0A++AND+timestamp+%3E+now%28%29+-+INTERVAL+7+DAY%0AGROUP+BY+conversation%0AORDER+BY+tool_calls+DESC%0ALIMIT+50) + +```sql +SELECT + properties.$mcp_conversation_id AS conversation, + arrayDistinct(groupArray(properties.$mcp_tool_name)) AS tools_called, + count() AS tool_calls +FROM events +WHERE event = '$mcp_tool_call' + AND properties.$mcp_conversation_id IS NOT NULL + AND timestamp > now() - INTERVAL 7 DAY +GROUP BY conversation +ORDER BY tool_calls DESC +LIMIT 50 +``` + +## Caveats + +**Some tools can't take the injection** + +The SDK cannot add `conversation_id` to schemas that use `oneOf`, `allOf`, `anyOf`, or `$ref`. It also skips tools without an input schema. It logs a warning and returns no handle for these tools. Use [`identify`](/docs/mcp-analytics/identifying-users.md) to group their calls by user. + +A client with a stale cached tool listing does not know about the new parameter. The `ttlMs` setting on `tools/list` can extend this period. + +**The handle is visible in tool output** + +The SDK returns the handle as a `{"conversation_id":"…"}` text block. Clients that display raw tool results also display this JSON. The block contains data rather than an instruction because hardened clients can treat instructions in tool results as prompt injection. + +The SDK preserves structured output and result metadata. Clients that only consume structured output may never see the text block, so they may not echo the handle. + +**Agent-controlled values** + +The SDK only reuses UUIDv7 values that match the shape of handles it can create. It replaces other values with a new handle. A client can still reuse a valid-looking handle across users, so don't use `$mcp_conversation_id` as a security boundary. + +**It also anchors the PostHog session** + +PostHog's session-level joins use `$session_id`. When conversation IDs are enabled, the SDK hashes the accepted `conversation_id` into a deterministic `$session_id`. Separate server instances derive the same value without shared storage. + +## When to skip this + +If your MCP server runs over a long-lived `2025-11-25` connection that already matches your conversation boundaries, you can disable conversation IDs. Turn conversation IDs off in your SDK's configuration to omit the injected argument and response block. See your [language's installation page](/docs/mcp-analytics/installation.md) for the option name. + +Keep it enabled when: + +- The same logical conversation crosses connections (HTTP/SSE clients that reconnect). +- Your server handles the `2026-07-28` revision and you want more than one request in each PostHog session. + +### Still have questions? + +Ask PostHog AI + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/custom-events.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/custom-events.md new file mode 100644 index 000000000..e56feb22b --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/custom-events.md @@ -0,0 +1,147 @@ +> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt + +# Custom events and metadata + +Use an event properties callback (`eventProperties` in TypeScript, `event_properties` in Python and Ruby, `WithProperties` in Go) to add metadata to captured events. Use `analytics.capture()` for events that are not MCP requests. + +## Add metadata to every event + +Pass a callback to attach extra properties to automatically captured MCP events. The callback receives request context, such as headers, transport, and the request ID. + +### TypeScript + +```typescript +import { instrument, getRequestHeaders } from "@posthog/mcp" + +const analytics = instrument(server, posthog, { + eventProperties: async (request, extra) => ({ + $app_version: process.env.GIT_SHA ?? "unknown", + request_id: getRequestHeaders(extra)?.["x-request-id"], + }), +}) +``` + +### Python + +```python +import os +from posthog.mcp import instrument, get_request_headers +from posthog.mcp.types import MCPAnalyticsOptions + +def event_properties(request, extra): + return { + "$app_version": os.environ.get("GIT_SHA", "unknown"), + "request_id": (get_request_headers(extra) or {}).get("x-request-id"), + } + +analytics = instrument(server, posthog, MCPAnalyticsOptions(event_properties=event_properties)) +``` + +### Go + +```go +posthogmcpsdk.Instrument(server, posthogmcp.New(client), + posthogmcpsdk.WithProperties(func(ctx context.Context, req *mcp.CallToolRequest, result *mcp.CallToolResult, err error) (posthog.Properties, error) { + props := posthog.NewProperties().Set("$app_version", os.Getenv("GIT_SHA")) + if req.Extra != nil { + props.Set("request_id", req.Extra.Header.Get("X-Request-Id")) + } + return props, nil + }), +) +``` + +### Ruby + +```ruby +analytics = PostHog::MCP.instrument( + server, posthog, + event_properties: ->(_request, extra) { { "$app_version" => ENV.fetch("GIT_SHA", "unknown"), "request_id" => extra["headers"]["x-request-id"] } } +) +``` + +In TypeScript, `getRequestHeaders` reads headers on both MCP SDK majors – see [MCP SDK v2](/docs/mcp-analytics/installation/typescript.md#read-request-headers-on-both-sdk-majors). + +The returned object is spread flat onto the event's properties alongside the built-in `$mcp_*` keys: + +JSON + +```json +{ + "event": "$mcp_tool_call", + "properties": { + "$mcp_tool_name": "search_events", + "$app_version": "a1b2c3d", + "region": "iad", + "request_id": "req_…" + } +} +``` + +Return constants from the callback to add the same values to captured MCP events. This is similar to `posthog.register(...)` in other SDKs. Return values from the request context when metadata must vary between calls. + +For group analytics, return `groups` from [`identify`](/docs/mcp-analytics/identifying-users.md). The SDK adds `$groups` to events for the session. + +The Go SDK drops returned keys that start with `$mcp_` or equal `$groups`, `$set`, `$process_person_profile`, `$session_id`, or `$exception_level`. + +Returned values must be JSON-serializable. The SDK catches callback errors and sends them to your `logger`. These errors do not interrupt tool execution. + +## Send a custom event + +Use `analytics.capture()` for events that aren't MCP requests, such as UI feedback or workflow milestones. It uses the SDK's sanitization, current server session and identity, and `beforeSend` hook. In TypeScript it returns a promise, and in Python it returns a coroutine, so `await` it. In Ruby it runs synchronously and returns `nil`. + +Custom capture has no request context and doesn't run the event properties callback. Pass custom metadata in `properties`. + +You name the event. It's sent verbatim – it's your event, so it is **not** `$`\-prefixed. + +### TypeScript + +```typescript +const analytics = instrument(server, posthog) + +await analytics.capture({ + event: "feedback_submitted", + properties: { rating: 5 }, +}) +``` + +### Python + +```python +analytics = instrument(server, posthog) + +await analytics.capture("feedback_submitted", {"rating": 5}) +``` + +### Ruby + +```ruby +analytics = PostHog::MCP.instrument(server, posthog) + +analytics.capture("feedback_submitted", { rating: 5 }) +``` + +The Go SDK has no analytics handle. Call `client.Enqueue(posthog.Capture{...})` on your `posthog-go` client instead. That path has no SDK redaction. + +PostHog receives: + +- One event under the verbatim `event` name you passed, with your `properties` merged in. +- The current server session and cached identity apply. These may differ from the session of a concurrent tool request. + +`capture()` is a method on the handle that `instrument()` returns, so you call it on the instrumented server's analytics handle directly. + +## Which one to use + +| You want to... | Use | +| --- | --- | +| Attach the same properties to every auto-captured event | The event properties callback | +| Emit a one-off event that isn't an MCP request | `analytics.capture()` | +| Attach data only to matching requests | Check the request in the callback and return properties only for matches. | + +### Still have questions? + +Ask PostHog AI + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/custom-servers.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/custom-servers.md new file mode 100644 index 000000000..631ce9230 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/custom-servers.md @@ -0,0 +1,58 @@ +> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt + +# Install MCP Analytics + +MCP Analytics captures how agents use your MCP server. Add the SDK for your server's language, and every tool call becomes a `$mcp_tool_call` event in PostHog. + +## Install with the wizard + +The wizard detects your server, installs the SDK, and adds the instrumentation. It supports TypeScript and Python servers, and [LLM coding agents](/blog/envoy-wizard-llm-agent.md) such as Cursor: + +`npx @posthog/wizard mcp-analytics` + +## Install by hand + +Choose your server's language: + +- [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/nodejs.svg)TypeScript](/docs/mcp-analytics/installation/typescript.md) + +- [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/python.svg)Python](/docs/mcp-analytics/installation/python.md) + +- [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/go.svg)Go](/docs/mcp-analytics/installation/go.md) + +- [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/ruby.svg)Ruby](/docs/mcp-analytics/installation/ruby.md) + +Each page has a Markdown version for coding agents. Add `.md` to the URL, such as [`/docs/mcp-analytics/installation/python.md`](/docs/mcp-analytics/installation/python.md). + +## What each SDK captures + +Every SDK sends the core events, `$mcp_tool_call` for each tool call and `$exception` for each failed call, so your insights and dashboards work across languages. The SDKs differ in which other events and features they implement: + +| Feature | TypeScript | Python | Go | Ruby | +| --- | --- | --- | --- | --- | +| Tool calls and failures (`$mcp_tool_call`, `$exception`) | Yes | Yes | Yes | Yes | +| Tool listings, handshakes, and resource reads | Yes | Yes | No | Yes | +| Unknown-tool calls (`$mcp_unknown_tool`) | No | No | Yes | No | +| `input_required` rounds (`$mcp_input_required`) | No | No | Yes | No | +| [Agent intent](/docs/mcp-analytics/intent.md) (`context` argument) | Yes | Yes | Yes | Yes | +| Intent fallback callback | Yes | Yes | No | Yes | +| [Model capture](/docs/mcp-analytics/events.md#model-capture) | Yes | Yes | Yes | Yes | +| [Conversation IDs](/docs/mcp-analytics/conversation-id.md) | Yes | Yes | Yes | Yes | +| [Identifying users](/docs/mcp-analytics/identifying-users.md) | Yes | Yes | Yes | Yes | +| [Missing capabilities](/docs/mcp-analytics/missing-capability.md) (`get_more_tools`) | Yes | Yes | No | Yes | +| Stateless session token | Yes | Yes | No | Yes | +| Custom dispatchers | Yes | Yes | Yes | Yes | +| Wizard | Yes | Yes | No | No | +| Support | Beta | Beta | Beta | Experimental | + +The Go SDK sends no `$identify` event. + +All SDKs remove credentials and binary content from captured payloads. See [Privacy](/docs/mcp-analytics/privacy.md). + +### Still have questions? + +Ask PostHog AI + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/events.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/events.md new file mode 100644 index 000000000..9d70b6449 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/events.md @@ -0,0 +1,153 @@ +> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt + +# Event and property reference + +This page is the wire-level contract for the MCP Analytics SDKs. TypeScript-only properties are marked below. All property keys are prefixed with `$mcp_*` so they never collide with PostHog autocapture, Web analytics, or other product events. + +## Events + +| Event name | When it fires | Notable extras | +| --- | --- | --- | +| `$mcp_tool_call` | Every `tools/call` request. In Go, a call to an unregistered tool and an `input_required` round fire the events below instead | `$mcp_tool_name`, `$mcp_tool_description`, `$mcp_parameters`, `$mcp_response`, `$mcp_duration_ms`, `$mcp_is_error`, `$mcp_error_type`/`$mcp_error_message` (on errors), optionally `$mcp_intent`/`$mcp_intent_source` and `$mcp_llm_model`/`$mcp_llm_model_source` | +| `$mcp_unknown_tool` | A `tools/call` names a tool the server hasn't registered. Go SDK only. | `$mcp_tool_name` (the requested name, redacted), and `$mcp_conversation_id` only if the agent sent a valid handle | +| `$mcp_input_required` | A tool ends a `2026-07-28` round by asking the client for input. Go SDK only. | `$mcp_tool_name`, `$mcp_duration_ms`, and `$mcp_input_request_methods` (string\[\] of the request methods, at most 100, never their contents) | +| `$mcp_tools_list` | Every `tools/list` response | `$mcp_listed_tool_names` (string\[\] of advertised tool names), `$mcp_response` (the response envelope as sent, including `nextCursor` and the 2026-07-28 `ttlMs`/`cacheScope` directives) | +| `$mcp_resources_list` | Every `resources/list` and `resources/templates/list` request | `$mcp_response` (the listing as sent: names, URIs, URI templates, MIME types, `nextCursor`), `$mcp_duration_ms`, `$mcp_is_error`. `$mcp_parameters.request.method` tells the two listings apart. | +| `$mcp_resource_read` | Every `resources/read` request | `$mcp_resource_name` (the URI, with credentials redacted), `$mcp_parameters`, `$mcp_duration_ms`, `$mcp_is_error`, `$mcp_error_type`/`$mcp_error_message` (on errors). The resource body is never captured. | +| `$mcp_initialize` | Every `2025-11-25` client/server handshake | `$mcp_client_name`, `$mcp_client_version`, `$mcp_server_name`, `$mcp_server_version`, `$mcp_protocol_version` | +| *(your event name)* | A call to `analytics.capture({ event, properties })` | Sent under the verbatim `event` name you pass (a customer event, not `$`\-prefixed), with your `properties` merged in. See [Custom events](/docs/mcp-analytics/custom-events.md). | +| `$mcp_missing_capability` | The `get_more_tools` virtual tool is invoked | The agent's reasoning is captured as `$mcp_intent`. See [Tracking missing capabilities](/docs/mcp-analytics/missing-capability.md). | +| `$identify` | `identify()` returns a new identity for a session | `$set` populated from the identity's `properties` | +| `$exception` | Sibling event whenever a tool call or resource request errors (unless `enableExceptionAutocapture: false`) | `$exception_list`, `$exception_level`, plus the same `$mcp_*` context as the main event | + +The TypeScript, Python, and Ruby SDKs capture resource events. The Go SDK doesn't yet. The Go SDK sends neither `$mcp_tools_list` nor `$mcp_initialize`. Only the Ruby SDK emits `$mcp_prompts_list` and `$mcp_prompt_get`. Prompt payloads pass through unchanged. + +## Core properties + +Present on most `mcp_*` events. + +| Wire key | Type | Source | +| --- | --- | --- | +| `$session_id` | string | The MCP session ID (`ses_<32-hex>`). Go also emits `ses_` for a session it generates. See [session resolution](#session-resolution) below. | +| `$mcp_source` | string | Always `"posthog_mcp_analytics"`. Use this to filter out non-MCP events when querying mixed projects. The Go SDK's `$mcp_unknown_tool`, `$mcp_input_required`, and `$mcp_missing_capability` events don't carry it. | +| `$mcp_resource_name` | string | Tool or prompt name, or on resource events the resource URI with its credentials redacted (see [Privacy](/docs/mcp-analytics/privacy.md)) | +| `$mcp_tool_name` | string | Same as `$mcp_resource_name`, but only on `$mcp_tool_call`. The Go SDK also sets it on `$mcp_unknown_tool` and `$mcp_input_required` | +| `$mcp_tool_description` | string | The tool's `description` at the moment of the call. Cached from `tools/list` and (for `McpServer`) seeded from `_registeredTools`. Only on `$mcp_tool_call` and the paired `$exception` event. | +| `$mcp_tool_category` | string | Your own grouping label for the tool, when you set one. Only on `$mcp_tool_call` and the paired `$exception` event. | +| `$mcp_listed_tool_names` | string\[\] | Names of tools advertised in a `tools/list` response. Only on `$mcp_tools_list`. Useful for joining against `$mcp_tool_call` via `$session_id` to find tools advertised but never called. | +| `$mcp_duration_ms` | number (ms) | Wall-clock duration of the tool call or resource request | +| `$mcp_is_error` | boolean | True if the handler threw or returned `isError: true` | +| `$mcp_error_type` | string | Failure category, present only when `$mcp_is_error` is true. Defaults to the thrown error type. In Go, the default is the package-qualified Go type, such as `fs.PathError`. Typed `mcp.AddTool` errors keep their type, plain errors give `Error`, and the Go adapter has no override. Override it with a label such as `validation`, `permission`, `timeout`, or `rate_limited`. Use it to group failures without joining `$exception` events. | +| `$mcp_error_message` | string | The failed call's error message, truncated and passed through the same redaction as `$mcp_parameters` and `$mcp_response`. Only set when `$mcp_is_error` is true. | +| `$mcp_server_name` | string | `server._serverInfo.name`. Go sets it only from `WithServerInfo`. | +| `$mcp_server_version` | string | `server._serverInfo.version`. Go sets it only from `WithServerInfo`. | +| `$mcp_client_name` | string | The calling client as it reports itself. Resolved per request, field by field, through the MCP SDK v2 request envelope, then `params._meta`, then the server's own `getClientVersion()`. On a `2025-11-25` stateless server, they're absent only when the transport can't return or replay the session token, such as on the legacy `createMcpHandler` path. Go reads only the session's `initialize` params. On `2026-07-28`, go-sdk v1.8.0 fills them from the request `_meta`. On a `2025-11-25` stateless Go server, they're absent. | +| `$mcp_client_version` | string | Same resolution as `$mcp_client_name`. | +| `$mcp_client_user_agent` | string | The client's raw `User-Agent`. It can distinguish clients that share a `clientInfo.name`, such as Claude Code CLI and Agent SDK. Available only on HTTP transports. Go reads only `User-Agent`, redacts credential shapes, and caps it at 256 bytes. | +| `$mcp_vendor_client` | string | The calling client's vendor client header, captured raw. HTTP transports only. Go reads only `X-Anthropic-Client`, redacts credential shapes, and caps it at 256 bytes. PostHog resolves this and the user agent into friendly product labels at query time, so labels keep improving without an SDK upgrade. | +| `$mcp_protocol_version` | string | The request's MCP revision, such as `2025-11-25`. Resolution order: v2 request envelope, `params._meta`, `MCP-Protocol-Version` header, then server accessors. On `2026-07-28`, each request declares its revision, so one session can contain multiple revisions. Use it to compare adoption, errors, and latency by revision. | +| `$mcp_intent` | string | From the `context` argument the agent passed, or from your `intentFallback` callback. See [Capturing agent intent](/docs/mcp-analytics/intent.md). | +| `$mcp_intent_source` | `"context_parameter" \| "inferred"` | Tells you which path produced the intent. Absent when no intent was captured. | +| `$mcp_llm_model` | string | The model from recognized client metadata or an SDK-injected `llm_model` argument. Enabled by default. Missing, blank, and `unknown` values are omitted. Both sources are unverified. | +| `$mcp_llm_model_source` | `"client_metadata" \| "self_reported"` | How the model identifier was obtained. Recognized client metadata takes priority over self-report. | +| `$mcp_parameters` | object | Sanitized request arguments. SDK-owned analytics arguments are removed before dispatch. Arguments declared by the application remain application data. See [Privacy & redaction](/docs/mcp-analytics/privacy.md). | +| `$mcp_response` | object | Sanitized tool result, or the listing on `$mcp_tools_list` and `$mcp_resources_list`. Never a resource body. | +| `$mcp_conversation_id` | string | Present when `enableConversationId` is on. See [Conversation IDs](/docs/mcp-analytics/conversation-id.md). | + +### Session resolution + +The SDK checks these sources in order and uses the first match: + +1. An accepted agent-provided `conversation_id`, when [conversation IDs](/docs/mcp-analytics/conversation-id.md) are enabled. +2. A session ID carried by the request on `2025-11-25`. +3. The server instance's session ID, which rotates after 30 minutes of inactivity. + +In Go, source 3 applies only to sessionless one-client connections (stdio and in-memory). A stateless HTTP request with neither a handle nor a session header gets a new ID per request. + +`2026-07-28` has no protocol sessions, so only sources 1 and 3 apply. Conversation handles support correlation across reconnects, restarts, and server instances. The SDK derives the session ID deterministically, without a salt. Separate pods therefore derive the same session ID from the same handle. + +### How the harness label is resolved + +A **harness** is the client label on the dashboard, such as "Claude Code", "Cursor", or "ChatGPT". PostHog derives it at query time from these properties, in priority order: + +1. **`$mcp_vendor_client`** – the vendor header (e.g. `x-anthropic-client`), the only signal separating Anthropic's pooled surfaces (Claude.ai, Cowork, Claude Design) from each other, since they all report the same `clientInfo.name`. +2. **`$mcp_client_user_agent`** – identifies the Claude Code interface: `(cli)`, `(sdk-ts)`, `(claude-vscode)`, or `(claude-desktop)`. It is also the fallback when no client name is available. +3. **`$mcp_client_name`** – the `clientInfo.name` the client reported. + +Requests through a vendor's gateway identify the gateway, not necessarily the original client. Claude.ai web, desktop, and mobile connectors use the same Anthropic fetcher. They share the `Claude-User` user agent and vendor header value. These requests resolve to "Claude.ai" because the request does not distinguish the three clients. + +A call without these properties is unattributed. An unrecognized client appears as "Other". + +If you see mostly "Other", check whether these properties contain values. On HTTP transports, the SDK captures headers automatically. Custom dispatchers must pass them explicitly, as in the [Python example](/docs/mcp-analytics/installation/python.md#custom-dispatchers). In Go, set `ClientUserAgent` and `VendorClient` on `ToolCall`. Stdio and in-memory transports have no headers, so only the client name is available. + +## Model capture + +MCP has no standard field for the calling model. The SDK reads recognized client metadata first, then the agent's self-reported `llm_model` argument, which the SDK adds to compatible tool schemas. Events include `$mcp_llm_model` and `$mcp_llm_model_source` (`"client_metadata"` or `"self_reported"`). + +The recognized metadata field is Codex's `params._meta["x-codex-turn-metadata"].model`. The Go SDK reads `io.modelcontextprotocol/aiInvocation` first, then `x-codex-turn-metadata`. Other clients can pass the `llm_model` argument. Some clients report an exact model, others a model family. Missing, blank, and `unknown` values are omitted, and reasoning effort isn't captured. + +Both sources are unverified client input. Use them to compare tool quality, latency, and errors by model, not for billing or security decisions. To turn model capture off, see the configuration on your [language's installation page](/docs/mcp-analytics/installation.md). + +## Exception properties + +Present on `$exception` events emitted alongside any failed tool call. The SDK reuses `@posthog/core`'s error-tracking parser, so these are the same `$exception_list` properties every other PostHog SDK emits – they slot straight into [Error tracking](/docs/error-tracking.md). Set `enableExceptionAutocapture: false` (default `true`) to stop a failed tool call from emitting the `$exception` sibling. + +| Wire key | Source | +| --- | --- | +| `$exception_list` | Array of structured exceptions. Each has `type`, `value` (the message), `mechanism`, and a `stacktrace` with parsed `frames` (`filename`, `function`, `lineno`, `colno`, `in_app`). An `Error.cause` chain appears as additional entries. | +| `$exception_level` | Severity, always `"error"`. | + +Plus `$session_id`, `$mcp_conversation_id`, `$mcp_resource_name`, `$mcp_tool_name`, `$mcp_tool_description` and `$mcp_tool_category` (tool calls only), `$mcp_server_*`, `$mcp_client_*` (including `$mcp_client_user_agent` and `$mcp_vendor_client`), `$mcp_protocol_version`, and the model properties when captured. + +In Go, the `$exception` has `type`, `value`, and `mechanism` but no stack trace, and no user agent, vendor client, or model properties. + +**Symbolicating minified MCP servers** + +Upload source maps with the [PostHog CLI](/docs/error-tracking/upload-source-maps.md) to symbolicate stack frames from bundled or minified servers. This follows the standard backend SDK process. The MCP SDK does not yet apply optional Node frame modifiers for source-context lines or project-relative paths. + +## Person properties (`$set`) + +Set on `$identify` events when `identify()` returns a user. + +| Key | Source | +| --- | --- | +| (any) | Keys of the identity's `properties` are written to `$set` (e.g. return `properties: { name, email }` to set a person's name and email) | + +The SDK sends `$set` to update the person profile. PostHog does not retain `$set` on the stored event. Query the resulting values as [person properties](/docs/product-analytics/person-properties.md) rather than filtering events by `$set`. + +In Go, `$set` rides on `$mcp_tool_call`, `$mcp_unknown_tool`, and `$mcp_input_required`, not on a `$identify` event. It needs an explicit `DistinctID`. The SDK drops it without one, or if the event is too large. + +## Groups (`$groups`) + +If `identify()` returns a `groups` field (a `Record` of groupType -> groupKey), the SDK stamps it onto every event as `$groups`. You never hand-write `$groups` yourself. See [Identifying users](/docs/mcp-analytics/identifying-users.md). + +## Person profiles for anonymous sessions + +Events for sessions with no resolved identity are sent with `$process_person_profile: false`, so anonymous MCP sessions do not each create a person profile. Once `identify()` resolves an identity for the session, person processing stays on and the events attribute to that user. + +## Constants exported from the package + +For product code that queries against the SDK's contract, the package exports: + +- `POSTHOG_MCP_ANALYTICS_SOURCE` – the constant `"posthog_mcp_analytics"` (matches `$mcp_source`) +- `PostHogMCPAnalyticsEvent` – enum of canonical event names +- `PostHogMCPAnalyticsProperty` – enum of canonical property names + +Use them instead of hard-coding strings so renames stay typesafe: + +TypeScript + +```typescript +import { PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty } from "@posthog/mcp"; + +const event = PostHogMCPAnalyticsEvent.ToolCall; // "$mcp_tool_call" +const key = PostHogMCPAnalyticsProperty.ToolName; // "$mcp_tool_name" +``` + +### Still have questions? + +Ask PostHog AI + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/identifying-users.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/identifying-users.md new file mode 100644 index 000000000..3744b3cd9 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/identifying-users.md @@ -0,0 +1,156 @@ +> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt + +# Identifying users + +By default, the SDK attributes MCP events to a generated session ID (`ses_…`). On `2025-11-25`, this normally follows the protocol session. On `2026-07-28`, [conversation IDs](/docs/mcp-analytics/conversation-id.md) are on by default. Calls share a session only when the agent echoes the handle. The SDK does not know the person behind the session. + +Use `identify` to associate calls with a person. + +## How attribution works + +For each event, the SDK picks `distinct_id` in this order: + +1. The distinct ID returned by your `identify` callback, if it returned an identity. +2. The MCP session id (`ses_…`). +3. The literal string `"anonymous"`. + +Before `identify` returns a user, events use the session ID. Later events use the user ID. See [Identity merges](#identity-merges) for how PostHog associates earlier anonymous events. + +## Anonymous sessions and person profiles + +Events for sessions with **no** resolved identity are sent with `$process_person_profile: false`. This keeps anonymous MCP sessions from each creating a person profile (which would inflate your person count and billing). Once `identify` resolves an identity for a session, person processing stays on and the events create/update that user's profile as normal. + +## Configure `identify` + +`identify` (`WithIdentity` in Go) is a callback that returns an identity or nothing. It runs on each request. Except in Go, the SDK caches identities per session to avoid duplicate `$identify` events. It still calls the callback on every request. Go has no cache, so the resolver runs once for each captured event. + +### TypeScript + +```typescript +import { instrument, getRequestHeaders } from "@posthog/mcp" + +instrument(server, posthog, { + identify: async (request, extra) => { + const token = getRequestHeaders(extra)?.["authorization"] + if (!token) return null + const user = await resolveUserFromToken(token) + if (!user) return null + return { + distinctId: user.id, // becomes distinct_id + properties: { name: user.name, plan: user.plan }, // written to $set + groups: { organization: user.orgId }, // becomes $groups on every event + } + }, +}) +``` + +### Python + +```python +from posthog.mcp import instrument, get_request_headers +from posthog.mcp.types import MCPAnalyticsOptions, UserIdentity + +async def identify(request, extra): + token = (get_request_headers(extra) or {}).get("authorization") + user = await resolve_user_from_token(token) if token else None + if user is None: + return None + return UserIdentity( + distinct_id=user.id, + properties={"name": user.name, "plan": user.plan}, + groups={"organization": user.org_id}, + ) + +instrument(server, posthog, MCPAnalyticsOptions(identify=identify)) +``` + +### Go + +```go +posthogmcpsdk.Instrument(server, posthogmcp.New(client), + posthogmcpsdk.WithIdentity(func(ctx context.Context, req *mcp.CallToolRequest) (posthogmcpsdk.Identity, error) { + if req.Extra == nil || req.Extra.TokenInfo == nil { + return posthogmcpsdk.Identity{}, nil + } + user, err := lookupUser(ctx, req.Extra.TokenInfo.UserID) + if err != nil { + return posthogmcpsdk.Identity{}, err + } + return posthogmcpsdk.Identity{ + DistinctID: user.ID, + SetProperties: posthog.NewProperties().Set("plan", user.Plan), + Groups: posthog.NewGroups().Set("organization", user.OrgID), + }, nil + }), +) +``` + +### Ruby + +```ruby +PostHog::MCP.instrument( + server, posthog, + identify: lambda do |_request, extra| + user = resolve_user(extra["headers"]["authorization"]) + user && { distinct_id: user.id, properties: { plan: user.plan }, groups: { organization: user.org_id } } + end +) +``` + +In TypeScript, read headers with `getRequestHeaders`. The two MCP SDK majors store them in different locations, and reading `extra` directly can return `undefined` and cause anonymous attribution. See [reading request headers](/docs/mcp-analytics/installation/typescript.md#read-request-headers-on-both-sdk-majors). Python has the same helper, `get_request_headers`. In Go, go-sdk gives you `req.Extra.Header` and `req.Extra.TokenInfo`. + +An identity has three fields, named in each language's style: + +- The distinct ID becomes the event's `distinct_id`. +- Person properties are written to `$set`, such as name, email, or plan. `$set` updates the person profile but isn't kept on the stored event, so query these as [person properties](/docs/product-analytics/person-properties.md). +- Groups, a map of group type to group key, are added to every event as `$groups`. + +When the callback returns an identity, the SDK: + +1. Uses the distinct ID as the event's `distinct_id` for that session. +2. Emits a `$identify` event the first time it sees the identity, or when the identity changes for that session. The Go SDK doesn't emit `$identify`. +3. Adds `$groups` to later events. +4. Caches the identity per session, so an unchanged identity doesn't send another `$identify`. The Go SDK has no cache. + +## Identity merges + +An MCP session can emit events before authentication completes. For example, `$mcp_initialize` may occur before you identify the user. These events use the session ID. + +When the SDK emits `$identify`, it sets `$anon_distinct_id` to the prior session ID so PostHog can merge the anonymous events. Later events use the distinct ID. The Go SDK sends no `$identify`, so it never merges anonymous events. Events with no resolved identity stay on the `ses_` distinct ID, without a person profile. + +For stateless servers that recover a session from a token, the SDK suppresses the first `$identify` after `initialize` to avoid duplicates across instances. If identity only becomes available later, those earlier anonymous events may remain unmerged. Resolve identity during `initialize` when possible. + +PostHog's other server SDKs use the same identity merge model. Your project's person profile settings also apply. + +## When *not* to call identify + +- **Internal tools without per-user auth.** If your MCP server doesn't authenticate end users (e.g. a single-tenant internal server behind a VPN), leave `identify` unset. Session-scoped attribution is fine. +- **Bots and crawlers.** Returning a junk identity for unauthenticated traffic dilutes your person count. Return `null` for traffic you can't identify – those events stay session-scoped. + +## Querying by identified user + +Once identification is wired up, anything that filters on `person.properties.*` or groups by `distinct_id` works as expected: + +SQL + +[Run in PostHog](https://us.posthog.com/sql?open_query=SELECT%0A++person.properties.plan+AS+plan%2C%0A++properties.%24mcp_tool_name+AS+tool%2C%0A++count%28%29+AS+calls%0AFROM+events%0AWHERE+event+%3D+'%24mcp_tool_call'%0A++AND+timestamp+%3E+now%28%29+-+INTERVAL+30+DAY%0AGROUP+BY+plan%2C+tool%0AORDER+BY+calls+DESC) + +```sql +SELECT + person.properties.plan AS plan, + properties.$mcp_tool_name AS tool, + count() AS calls +FROM events +WHERE event = '$mcp_tool_call' + AND timestamp > now() - INTERVAL 30 DAY +GROUP BY plan, tool +ORDER BY calls DESC +``` + +### Still have questions? + +Ask PostHog AI + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/installation.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/installation.md new file mode 100644 index 000000000..631ce9230 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/installation.md @@ -0,0 +1,58 @@ +> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt + +# Install MCP Analytics + +MCP Analytics captures how agents use your MCP server. Add the SDK for your server's language, and every tool call becomes a `$mcp_tool_call` event in PostHog. + +## Install with the wizard + +The wizard detects your server, installs the SDK, and adds the instrumentation. It supports TypeScript and Python servers, and [LLM coding agents](/blog/envoy-wizard-llm-agent.md) such as Cursor: + +`npx @posthog/wizard mcp-analytics` + +## Install by hand + +Choose your server's language: + +- [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/nodejs.svg)TypeScript](/docs/mcp-analytics/installation/typescript.md) + +- [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/python.svg)Python](/docs/mcp-analytics/installation/python.md) + +- [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/go.svg)Go](/docs/mcp-analytics/installation/go.md) + +- [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/ruby.svg)Ruby](/docs/mcp-analytics/installation/ruby.md) + +Each page has a Markdown version for coding agents. Add `.md` to the URL, such as [`/docs/mcp-analytics/installation/python.md`](/docs/mcp-analytics/installation/python.md). + +## What each SDK captures + +Every SDK sends the core events, `$mcp_tool_call` for each tool call and `$exception` for each failed call, so your insights and dashboards work across languages. The SDKs differ in which other events and features they implement: + +| Feature | TypeScript | Python | Go | Ruby | +| --- | --- | --- | --- | --- | +| Tool calls and failures (`$mcp_tool_call`, `$exception`) | Yes | Yes | Yes | Yes | +| Tool listings, handshakes, and resource reads | Yes | Yes | No | Yes | +| Unknown-tool calls (`$mcp_unknown_tool`) | No | No | Yes | No | +| `input_required` rounds (`$mcp_input_required`) | No | No | Yes | No | +| [Agent intent](/docs/mcp-analytics/intent.md) (`context` argument) | Yes | Yes | Yes | Yes | +| Intent fallback callback | Yes | Yes | No | Yes | +| [Model capture](/docs/mcp-analytics/events.md#model-capture) | Yes | Yes | Yes | Yes | +| [Conversation IDs](/docs/mcp-analytics/conversation-id.md) | Yes | Yes | Yes | Yes | +| [Identifying users](/docs/mcp-analytics/identifying-users.md) | Yes | Yes | Yes | Yes | +| [Missing capabilities](/docs/mcp-analytics/missing-capability.md) (`get_more_tools`) | Yes | Yes | No | Yes | +| Stateless session token | Yes | Yes | No | Yes | +| Custom dispatchers | Yes | Yes | Yes | Yes | +| Wizard | Yes | Yes | No | No | +| Support | Beta | Beta | Beta | Experimental | + +The Go SDK sends no `$identify` event. + +All SDKs remove credentials and binary content from captured payloads. See [Privacy](/docs/mcp-analytics/privacy.md). + +### Still have questions? + +Ask PostHog AI + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/intent.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/intent.md new file mode 100644 index 000000000..b4ca337ee --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/intent.md @@ -0,0 +1,204 @@ +> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt + +# Capturing agent intent + +Intent explains why an agent called a tool. Use it to understand the goals behind tool usage. + +The SDK captures intent as a single property – `$mcp_intent` – that can come from one of two sources: + +1. **A `context` argument** the agent passes on every tool call. Captured with `$mcp_intent_source = "context_parameter"`. +2. **A fallback callback** you supply on `instrument()`. Captured with `$mcp_intent_source = "inferred"`. + +Explicit context always wins. If the agent passes a non-empty `context`, the fallback is not invoked. + +## The `context` argument + +Intent capture is on by default. The SDK adds a `context` string to compatible tool schemas and removes it before your handler runs when it can confirm it injected the field. An application-owned `context` argument is preserved. + +Every SDK adds the `context` argument by default. TypeScript, Go, and Ruby advertise it as required. Python makes it optional on raw low-level servers and standalone FastMCP. Calls can omit it without failing validation. + +What the agent sees in the schema: + +JSON + +```json +{ + "type": "object", + "properties": { + "context": { + "type": "string", + "description": "Why are you calling this tool? Briefly describe the user's goal." + }, + "...": "your real tool arguments" + }, + "required": ["context", "..."] +} +``` + +Your handler receives only your own arguments. The SDK removes `context` before the handler runs. + +PostHog captures this value as `$mcp_intent`: + +``` +"Finding the last 10 pageviews for user alice@example.com to triage a drop in conversion" +``` + +### Customize the prompt + +If you want to nudge the agent toward a specific style of context (use case, user goal, ticket id, etc.), pass an object: + +### TypeScript + +```typescript +instrument(server, posthog, { + context: { + description: "Describe the user's underlying goal in one sentence, not the tool you're calling.", + }, +}) +``` + +### Python + +```python +from posthog.mcp.types import MCPAnalyticsContextOptions, MCPAnalyticsOptions + +instrument(server, posthog, MCPAnalyticsOptions( + context=MCPAnalyticsContextOptions( + description="Describe the user's underlying goal in one sentence, not the tool you're calling.", + ), +)) +``` + +### Ruby + +```ruby +PostHog::MCP.instrument( + server, posthog, + context: { description: "Describe the user's underlying goal in one sentence, not the tool you're calling." } +) +``` + +The Go SDK uses a fixed prompt. + +### Disabling the injected argument + +Turn off the injected argument with `context: false` in TypeScript and Ruby, `MCPAnalyticsOptions(context=False)` in Python, or `posthogmcpsdk.WithContextParameter(false)` in Go. Use an intent fallback if you still want to capture intent. The Go SDK has no fallback, so with `WithContextParameter(false)` it captures no intent, not even a tool's own `context` argument. Model capture and conversation IDs have separate options. [Disable those options](/docs/mcp-analytics/events.md#model-capture) to stop their schema changes. + +## The intent fallback callback + +A client can omit the SDK-injected `context` argument. Without a fallback, the event has no `$mcp_intent`. + +The SDK calls the fallback (`intentFallback` in TypeScript, `intent_fallback` in Python and Ruby) when the agent provides no context. The Go SDK doesn't have a fallback yet. It captures a non-empty result as `$mcp_intent` with `$mcp_intent_source = "inferred"`. + +The SDK does no inference of its own. It doesn't call an LLM. It doesn't inspect your tool arguments. It doesn't cache results. Whatever logic you want goes in your callback. + +### Deterministic, per-tool + +Use a synchronous callback when you can derive intent from the tool name and arguments: + +### TypeScript + +```typescript +instrument(server, posthog, { + intentFallback: (request) => { + const tool = request.params?.name + const args = request.params?.arguments ?? {} + if (tool === "search_events") return `Searching events for "${args.query}"` + return tool ? `Invoking ${tool}` : null + }, +}) +``` + +### Python + +```python +from posthog.mcp.types import MCPAnalyticsOptions + +def intent_fallback(request, extra): + params = request.get("params") or {} + tool = params.get("name") + args = params.get("arguments") or {} + if tool == "search_events": + return f'Searching events for "{args.get("query")}"' + return f"Invoking {tool}" if tool else None + +instrument(server, posthog, MCPAnalyticsOptions(intent_fallback=intent_fallback)) +``` + +### Using transport metadata + +`extra` carries MCP transport details – useful when the agent's user-agent or auth context hints at intent: + +TypeScript + +```typescript +import { getRequestHeaders } from "@posthog/mcp" + +intentFallback: (request, extra) => { + const ua = getRequestHeaders(extra)?.["user-agent"] + return `${ua ?? "unknown client"} invoked ${request.params?.name}` +} +``` + +In TypeScript, `getRequestHeaders` reads headers on both MCP SDK majors – see [MCP SDK v2](/docs/mcp-analytics/installation/typescript.md#read-request-headers-on-both-sdk-majors). + +### LLM-derived intent + +An LLM call in `intentFallback` adds latency to each tool call that lacks context. Cache results where possible. Handle failures in the callback: + +TypeScript + +```typescript +intentFallback: async (request) => { + try { + return await summariseIntent(request.params) + } catch { + return null // the SDK swallows null gracefully + } +} +``` + +## Filtering on intent source + +`$mcp_intent_source` is set to `"context_parameter"` or `"inferred"` only when an intent was captured. If neither a `context` argument nor a fallback result was available, both `$mcp_intent` and `$mcp_intent_source` are absent on the event. + +If you want to know what fraction of your traffic is contextualized: + +SQL + +[Run in PostHog](https://us.posthog.com/sql?open_query=SELECT%0A++properties.%24mcp_intent_source+AS+source%2C%0A++count%28%29+AS+calls%0AFROM+events%0AWHERE+event+%3D+'%24mcp_tool_call'%0A++AND+timestamp+%3E+now%28%29+-+INTERVAL+7+DAY%0AGROUP+BY+source%0AORDER+BY+calls+DESC) + +```sql +SELECT + properties.$mcp_intent_source AS source, + count() AS calls +FROM events +WHERE event = '$mcp_tool_call' + AND timestamp > now() - INTERVAL 7 DAY +GROUP BY source +ORDER BY calls DESC +``` + +A high share of `inferred` means most clients do not supply context. Review `context.description` or improve `intentFallback`. + +## Gotchas + +**\`get\_more\_tools\` reports its source as \`context\_parameter\`** + +The virtual `get_more_tools` tool always reports `$mcp_intent_source = "context_parameter"`, even though the SDK is what defined the schema. Defensible – the agent did type a string – but filter it out of source-attribution queries if the number matters. + +**The schema \`required\` field isn't enforced** + +Omitting the SDK-injected `context` argument doesn't fail validation. Your tool's own required arguments still apply. Use `intentFallback` to capture intent when the agent omits context. + +**Skip \`intentFallback\` for tight internal servers** + +You do not need a fallback if your internal client always supplies `context`. Add one if clients can omit this argument. + +### Still have questions? + +Ask PostHog AI + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/sdk-v2.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/sdk-v2.md new file mode 100644 index 000000000..11e0af8f3 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/sdk-v2.md @@ -0,0 +1,58 @@ +> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt + +# MCP SDK v2 + +The `2026-07-28` MCP revision removes the `initialize` handshake and protocol sessions. The TypeScript SDK serves it on MCP SDK v2, and the Go SDK on go-sdk v1.8.0 or later. The Python and Ruby SDKs serve it too. This page covers what that revision changes for your analytics. + +To set up a server on either revision, see the installation page for [TypeScript](/docs/mcp-analytics/installation/typescript.md), [Python](/docs/mcp-analytics/installation/python.md), [Go](/docs/mcp-analytics/installation/go.md), or [Ruby](/docs/mcp-analytics/installation/ruby.md). + +## Sessions on `2026-07-28` + +That revision removed the `initialize` handshake and the `Mcp-Session-Id` header, so the [stateless session token](/docs/mcp-analytics/installation/typescript.md#stateless-and-multi-pod-servers) doesn't apply. Use a conversation handle to correlate requests: + +- **[Conversation IDs](/docs/mcp-analytics/conversation-id.md)** – enabled by default. The SDK injects a `conversation_id` parameter and returns a handle in eligible tool results. Calls share a `$session_id` when the agent echoes that handle. Clients that ignore it can still produce a separate session per request. +- **[`identify`](/docs/mcp-analytics/identifying-users.md)** – attributes calls to a person via `distinct_id`. Use it for user-level grouping. It does not provide a `$session_id`. + +The protocol revision belongs to each request. A v2 server also serves `2025-11-25` traffic, which most clients still negotiate. + +**Missing client name on 2025-11-25 traffic?** + +On `2025-11-25`, the client sends its name and version only at `initialize`. For servers that create an instance per request, the SDK uses a session token. The transport must write response headers after the handler runs to send this token. + +`@rekog/mcp-nest` supports this with `enableJsonResponse: true`. The legacy path in `createMcpHandler` does not. On that path, expect `$mcp_client_name` and `$mcp_client_version` to be absent. `$mcp_protocol_version` remains available. + +## Capture model identity on both revisions + +Every SDK captures model identity on `2025-11-25` and `2026-07-28`. Recognized client metadata takes priority over the agent's self-reported `llm_model` argument. `$mcp_llm_model_source` records `"client_metadata"` or `"self_reported"`. + +Both sources are unverified. See [model capture](/docs/mcp-analytics/events.md#model-capture) for how the SDK reads it. + +## MCP Apps + +`@posthog/mcp` preserves MCP App tool metadata, `ui://` resources, structured tool output, result metadata, HTML, and content security policy metadata on both supported revisions. On the tested high-level `McpServer` path, injected `context` and `llm_model` arguments don't reach the App handler. + +The SDK captures App tool calls with intent, self-reported model, and protocol version. Resource listing and read requests emit `$mcp_resources_list` and `$mcp_resource_read` on both server paths. Resource payloads pass through unchanged. The SDK never captures a resource read body. + +## Not instrumented yet + +These gaps apply to the TypeScript and Python SDKs alike. For Go, see the note after the table. + +| `2026-07-28` feature | What you get today | +| --- | --- | +| **Tasks** (`io.modelcontextprotocol/tasks`) | A tool returning a task handle records an instant success, so task-based tools look fast and always-succeeding. | +| **Multi round-trip** (`resultType: "input_required"`) | Each round counts as its own `$mcp_tool_call`, inflating call counts and durations. | +| `server/discover` | Not captured – no session-start event on this revision. | +| `Mcp-Method` / `Mcp-Name` headers | Not read. | +| `clientCapabilities` in `_meta` | Not captured. `clientInfo` and protocol version are. | + +The Go SDK handles multi round-trip differently. It sends each `input_required` round as `$mcp_input_required`, and the retry that completes the call is the `$mcp_tool_call`. A round never carries a conversation handle. Rounds need go-sdk v1.8.0 or later, and the adapter needs v1.6.1 or later. The Go SDK doesn't handle tasks. + +Task-based tools and multi-round-trip tools can produce misleading counts and durations. Check these limitations before using their dashboard metrics. + +### Still have questions? + +Ask PostHog AI + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/start-here.md b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/start-here.md new file mode 100644 index 000000000..2bb7e5f12 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.claude/skills/mcp-analytics/references/start-here.md @@ -0,0 +1,377 @@ +> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt + +# Getting started with MCP Analytics + +**MCP Analytics is in beta** + +The TypeScript package `@posthog/mcp` is pre-1.0. The Python integration is in beta, and the Ruby integration is experimental. We're building them in public, so event shapes and options may still change. Pin a specific version. + +## Add MCP Analytics to your server + +MCP Analytics shows how agents use your server. Wrap your server once to capture: + +- 🛠️ Every tool call (parameters, response, duration, errors) +- 🎯 Agent intent – the *why* behind each call, not just the *what* +- 🤖 The model from client metadata or the agent's self-report +- 🧭 Tool and resource discovery, plus resource reads without their bodies +- 🪪 The MCP client name and version +- 🧵 Sessions across calls when the client supplies correlation data +- 🚧 Capabilities the agent wished existed (opt-in) + +Install the SDK for your server's language: + +### TypeScript + +```bash +npm install @posthog/mcp posthog-node +``` + +### Python + +```bash +pip install posthog +``` + +### Go + +```bash +go get github.com/posthog/posthog-go/posthogmcpsdk +``` + +### Ruby + +```bash +bundle add posthog-ruby +``` + +Set `POSTHOG_PROJECT_TOKEN` in your environment. Wrap your existing server once, before it accepts requests, and send queued events when the process stops: + +### TypeScript + +```typescript +import { PostHog } from "posthog-node" +import { instrument } from "@posthog/mcp" + +const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, { + host: "https://us.i.posthog.com", // or https://eu.i.posthog.com +}) + +instrument(server, posthog) + +process.on("SIGTERM", async () => { + await posthog.shutdown() + process.exit(0) +}) +``` + +### Python + +```python +import os +from posthog import Posthog +from posthog.mcp import instrument + +posthog = Posthog( + os.environ["POSTHOG_PROJECT_TOKEN"], + host="https://us.i.posthog.com", # or https://eu.i.posthog.com +) + +analytics = instrument(server, posthog) + +# when the process stops: +await analytics.flush() +posthog.shutdown() +``` + +### Go + +```go +client, err := posthog.NewWithConfig(os.Getenv("POSTHOG_PROJECT_TOKEN"), posthog.Config{ + Endpoint: "https://us.i.posthog.com", // or https://eu.i.posthog.com +}) +if err != nil { + log.Fatal(err) +} +defer client.Close() + +posthogmcpsdk.Instrument(server, posthogmcp.New(client), + posthogmcpsdk.WithServerInfo("my-mcp-server", "1.0.0"), +) +``` + +### Ruby + +```ruby +require "posthog/mcp" + +posthog = PostHog::Client.new( + api_key: ENV.fetch("POSTHOG_PROJECT_TOKEN"), + host: "https://us.i.posthog.com" # or https://eu.i.posthog.com +) + +PostHog::MCP.instrument(server, posthog) + +at_exit { posthog.shutdown } +``` + +Every SDK has the same defaults. Intent, model capture, conversation IDs, and exception events are on. Missing-capability reports are opt-in. The Ruby SDK is [experimental](/docs/mcp-analytics/installation/ruby.md). + +For TypeScript and Python servers, the wizard does the setup for you: + +`npx @posthog/wizard mcp-analytics` + +[ + +Full installation guide + +](/docs/mcp-analytics/installation.md) + +## See your first events + +Run your MCP server. Connect an agent, such as Claude Desktop, Cursor, Codex, or your own client. PostHog receives `$mcp_tool_call` and `$mcp_tools_list` events when the agent calls tools and requests their listing. Clients on `2025-11-25` also produce `$mcp_initialize`. The handshake-free `2026-07-28` revision has no initialize event. The Go SDK sends `$mcp_tool_call`, `$exception`, `$mcp_unknown_tool`, and `$mcp_input_required`. It sends neither `$mcp_tools_list` nor `$mcp_initialize`. + +Open the [activity feed](https://app.posthog.com/activity/explore) in your project. Filter for `event = $mcp_tool_call`. Each row represents a tool invocation and includes `$mcp_tool_name`, `$mcp_parameters`, `$mcp_response`, `$mcp_duration_ms`, and `$mcp_is_error`. + +![PostHog activity feed filtered to $mcp_tool_call events, with tool name, client, error state, and duration columns](https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/mcp_activity_feed_light_197cb57f3c.png) + +[ + +See every event the SDK emits + +](/docs/mcp-analytics/events.md) + +## Ship safely + +The SDK sanitizes each event and truncates it to fit ingestion limits. It removes media payloads and masks known credential patterns, sensitive keys, and credentials inside URLs. + +To inspect, change, or drop events before they're sent, add a before-send hook. Return the event to send it, or nothing to drop it: + +### TypeScript + +```typescript +instrument(server, posthog, { + beforeSend: (event) => { + delete event.properties.$mcp_response // keep tool results out of PostHog + return event + }, +}) +``` + +### Python + +```python +from posthog.mcp.types import MCPAnalyticsOptions + +def before_send(event): + event["properties"].pop("$mcp_response", None) # keep tool results out of PostHog + return event + +instrument(server, posthog, MCPAnalyticsOptions(before_send=before_send)) +``` + +### Go + +```go +posthogmcpsdk.Instrument(server, posthogmcp.New(client), + posthogmcpsdk.WithCaptureResponses(false), // keep tool results out of PostHog +) +``` + +### Ruby + +```ruby +PostHog::MCP.instrument( + server, posthog, + before_send: lambda do |event| + event["properties"].delete("$mcp_response") # keep tool results out of PostHog + event + end +) +``` + +In Go, `WithCaptureResponses(false)` still sends a failed call's error text as `$mcp_error_message` and in `$exception`. A full before-send hook is the `BeforeSend` field of your `posthog.Config`. See the [Go example](/docs/mcp-analytics/privacy.md#3-your-before-send-hook-optional). + +[ + +Privacy & redaction + +](/docs/mcp-analytics/privacy.md) + +## Compare tool quality by model + +[Model capture](/docs/mcp-analytics/events.md#model-capture) is on by default. Check `$mcp_tool_call` events for `$mcp_llm_model`. The source, `$mcp_llm_model_source`, is `"client_metadata"` or `"self_reported"`. + +Use this unverified client input to compare quality, latency, and errors across models, not for billing or security decisions. Some clients report an exact model, others a model family. Missing, blank, and `unknown` values are omitted. + +## Capture what the agent was trying to do + +**Intent** is the user goal that led the agent to call a tool. The SDK adds a `context` argument to compatible tool schemas and captures it as `$mcp_intent`. It removes the argument before your handler runs. + +You can change the prompt the agent sees, and supply a fallback for agents that skip the argument. The Go SDK has a fixed prompt and no fallback. + +[ + +Learn about intent capture + +](/docs/mcp-analytics/intent.md) + +## Build your first dashboard + +MCP events work with PostHog insights, dashboards, alerts, and SQL. The [MCP Analytics view](/docs/mcp-analytics.md) provides built-in views during the beta. Start with these four queries: + +- ### Top tools per server + + Which tools do agents call most often? + +- ### Error rate per tool + + Which tools fail most often? Use `$exception` events to investigate errors. + +- ### Intent samples by source + + How much of your traffic supplies explicit context, and how much uses the intent fallback? + +- ### Advertised tools that never get called + + Join `$mcp_tools_list` with `$mcp_tool_call` to find tools that agents never call. The Go SDK sends no `$mcp_tools_list`, so this query returns nothing for Go servers. + +The tool quality tab shows error rates and latency percentiles for each tool. Select a tool to inspect its calls: + +![MCP Analytics tool quality tab showing calls and errors, success rate, latency percentiles, and a per-tool table](https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/mcp_tool_quality_light_f91f27f6e1.png) + +[ + +Copy-paste queries + +](/docs/mcp-analytics/queries.md) + +## Identify the user behind the agent + +By default, each event uses an SDK-generated session ID. Add an identify callback to associate calls with users, person properties, and groups. Return the user from your own auth data, such as the OAuth subject: + +### TypeScript + +```typescript +import { instrument, getRequestHeaders } from "@posthog/mcp" + +instrument(server, posthog, { + identify: async (request, extra) => { + const user = await resolveUser(getRequestHeaders(extra)?.["authorization"]) + return user ? { distinctId: user.id, properties: { plan: user.plan } } : null + }, +}) +``` + +### Python + +```python +from posthog.mcp import get_request_headers +from posthog.mcp.types import MCPAnalyticsOptions, UserIdentity + +async def identify(request, extra): + user = await resolve_user((get_request_headers(extra) or {}).get("authorization")) + return UserIdentity(distinct_id=user.id, properties={"plan": user.plan}) if user else None + +instrument(server, posthog, MCPAnalyticsOptions(identify=identify)) +``` + +### Go + +```go +posthogmcpsdk.Instrument(server, posthogmcp.New(client), + posthogmcpsdk.WithIdentity(func(ctx context.Context, req *mcp.CallToolRequest) (posthogmcpsdk.Identity, error) { + if req.Extra == nil || req.Extra.TokenInfo == nil { + return posthogmcpsdk.Identity{}, nil + } + return posthogmcpsdk.Identity{DistinctID: req.Extra.TokenInfo.UserID}, nil + }), +) +``` + +### Ruby + +```ruby +PostHog::MCP.instrument( + server, posthog, + identify: ->(_request, extra) { + user = resolve_user(extra["headers"]["authorization"]) + user && { distinct_id: user.id, properties: { plan: user.plan } } + } +) +``` + +[ + +Identify users + +](/docs/mcp-analytics/identifying-users.md) + +## Find capability gaps + +Turn on missing-capability reports to add the `get_more_tools` virtual tool. Agents call it to report requests your server cannot satisfy: + +### TypeScript + +```typescript +instrument(server, posthog, { reportMissing: true }) +``` + +### Python + +```python +instrument(server, posthog, MCPAnalyticsOptions(report_missing=True)) +``` + +### Ruby + +```ruby +PostHog::MCP.instrument(server, posthog, report_missing: true) +``` + +### Go + +```go +posthogmcpsdk.Instrument(server, posthogmcp.New(client), + posthogmcpsdk.WithMissingCapabilityTool("get_more_tools"), +) +``` + +Use these reports to prioritize capabilities: + +SQL + +[Run in PostHog](https://us.posthog.com/sql?open_query=SELECT%0A++properties.%24mcp_intent+++++++AS+unmet_request%2C%0A++properties.%24mcp_client_name++AS+client%2C%0A++count%28%29++++++++++++++++++++++AS+times_asked%0AFROM+events%0AWHERE+event+%3D+'%24mcp_missing_capability'%0A++AND+timestamp+%3E+now%28%29+-+INTERVAL+30+DAY%0AGROUP+BY+unmet_request%2C+client%0AORDER+BY+times_asked+DESC) + +```sql +SELECT + properties.$mcp_intent AS unmet_request, + properties.$mcp_client_name AS client, + count() AS times_asked +FROM events +WHERE event = '$mcp_missing_capability' + AND timestamp > now() - INTERVAL 30 DAY +GROUP BY unmet_request, client +ORDER BY times_asked DESC +``` + +[ + +Track missing capabilities + +](/docs/mcp-analytics/missing-capability.md) + +1/8 + +[**Add MCP Analytics to your server** ***Required***](#quest-item-add-mcp-analytics-to-your-server)[**See your first events** ***Required***](#quest-item-see-your-first-events)[**Ship safely** ***Required***](#quest-item-ship-safely)[**Compare tool quality by model** ***Recommended***](#quest-item-compare-tool-quality-by-model)[**Capture what the agent was trying to do** ***Recommended***](#quest-item-capture-what-the-agent-was-trying-to-do)[**Build your first dashboard** ***Recommended***](#quest-item-build-your-first-dashboard)[**Identify the user behind the agent** ***Recommended***](#quest-item-identify-the-user-behind-the-agent)[**Find capability gaps** ***Recommended***](#quest-item-find-capability-gaps) + +**Add MCP Analytics to your server** + +***Required*** + +### Still have questions? + +Ask PostHog AI + +### Was this page useful? + +HelpfulCould be better \ No newline at end of file diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/.gitignore b/apps/mcp-analytics/typescript-sdk/stdio-server/.gitignore new file mode 100644 index 000000000..4c49bd78f --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/.gitignore @@ -0,0 +1 @@ +.env diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/package-lock.json b/apps/mcp-analytics/typescript-sdk/stdio-server/package-lock.json new file mode 100644 index 000000000..f0a5eaa88 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/package-lock.json @@ -0,0 +1,1801 @@ +{ + "name": "wb-mcp-stdio-server", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "wb-mcp-stdio-server", + "version": "0.0.0", + "dependencies": { + "@modelcontextprotocol/sdk": "^1.12.0", + "@posthog/mcp": "0.22.2", + "posthog-node": "^5.55.0", + "zod": "^3.23.8" + }, + "devDependencies": { + "tsx": "^4.19.2", + "typescript": "^5.6.3" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz", + "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz", + "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz", + "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz", + "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz", + "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz", + "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz", + "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz", + "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz", + "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz", + "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz", + "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz", + "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz", + "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz", + "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz", + "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz", + "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz", + "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz", + "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz", + "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz", + "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz", + "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz", + "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz", + "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz", + "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz", + "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz", + "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@hono/node-server": { + "version": "2.1.4", + "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.4.tgz", + "integrity": "sha512-2g1qeHl4BduwDn6L8nkAvDrPUWPMlkQ//a5NhP/zIyaXKMjZNRV+cG9Csu+BiJFf6+68pqzjf4Hi5sJGKHuS1g==", + "license": "MIT", + "engines": { + "node": ">=20" + }, + "peerDependencies": { + "hono": "^4 || ^5.0.0-0" + } + }, + "node_modules/@modelcontextprotocol/sdk": { + "version": "1.32.1", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.32.1.tgz", + "integrity": "sha512-2DdE+SJDtzLEEWzY1ZjY7Q+VcPhcV1KisD3zI4u0XZyktsjHum1mwbMI+JaulUBi2OZk+KJAi2uPXzxichPkdw==", + "license": "MIT", + "dependencies": { + "@hono/node-server": "^1.19.9 || ^2.0.5", + "ajv": "^8.17.1", + "ajv-formats": "^3.0.1", + "content-type": "^1.0.5", + "cors": "^2.8.5", + "cross-spawn": "^7.0.5", + "eventsource": "^3.0.2", + "eventsource-parser": "^3.0.0", + "express": "^5.2.1", + "express-rate-limit": "^8.2.1", + "hono": "^4.11.4", + "jose": "^6.1.3", + "json-schema-typed": "^8.0.2", + "pkce-challenge": "^5.0.0", + "raw-body": "^3.0.0", + "zod": "^3.25 || ^4.0", + "zod-to-json-schema": "^3.25.1" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@cfworker/json-schema": "^4.1.1", + "zod": "^3.25 || ^4.0" + }, + "peerDependenciesMeta": { + "@cfworker/json-schema": { + "optional": true + }, + "zod": { + "optional": false + } + } + }, + "node_modules/@posthog/core": { + "version": "1.57.2", + "resolved": "https://registry.npmjs.org/@posthog/core/-/core-1.57.2.tgz", + "integrity": "sha512-dfxeSjUvR+j4M7odvyf/KVdcKTZZ87u/l9swJtDt9vFkI2km3RhEveOkIHtFcZEQ1cllx7YaKJfdw6c8zfIEvg==", + "license": "MIT", + "dependencies": { + "@posthog/types": "^1.415.1" + } + }, + "node_modules/@posthog/mcp": { + "version": "0.22.2", + "resolved": "https://registry.npmjs.org/@posthog/mcp/-/mcp-0.22.2.tgz", + "integrity": "sha512-mTG9qU03vVD0SPtf2hl+SStEVVSRRnYWNvbHb9wOqkOSLk/jjMEkmeTDkh6QRUifv0LgHg2C/syNiX501mAyEQ==", + "license": "MIT", + "dependencies": { + "@posthog/core": "^1.57.2" + }, + "engines": { + "node": "^20.20.0 || >=22.22.0" + }, + "peerDependencies": { + "@modelcontextprotocol/sdk": ">=1.26.0", + "@modelcontextprotocol/server": ">=2.0.0", + "posthog-node": "^5.0.0" + }, + "peerDependenciesMeta": { + "@modelcontextprotocol/sdk": { + "optional": true + }, + "@modelcontextprotocol/server": { + "optional": true + } + } + }, + "node_modules/@posthog/types": { + "version": "1.415.1", + "resolved": "https://registry.npmjs.org/@posthog/types/-/types-1.415.1.tgz", + "integrity": "sha512-7Qs2wcqipl8KcFpIkIKE1Wcj1djX4dEB3cfq907HrNpKK7/xKh3U4N4bkOD6h9+8j3SxWWrj9JNpE8CZXsE35w==", + "license": "MIT" + }, + "node_modules/accepts": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz", + "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==", + "license": "MIT", + "dependencies": { + "mime-types": "^3.0.0", + "negotiator": "^1.0.0" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/ajv": { + "version": "8.20.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz", + "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==", + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/ajv-formats": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz", + "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==", + "license": "MIT", + "dependencies": { + "ajv": "^8.0.0" + }, + "peerDependencies": { + "ajv": "^8.0.0" + }, + "peerDependenciesMeta": { + "ajv": { + "optional": true + } + } + }, + "node_modules/body-parser": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.3.0.tgz", + "integrity": "sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==", + "license": "MIT", + "dependencies": { + "bytes": "^3.1.2", + "content-type": "^2.0.0", + "debug": "^4.4.3", + "http-errors": "^2.0.1", + "iconv-lite": "^0.7.2", + "on-finished": "^2.4.1", + "qs": "^6.15.2", + "raw-body": "^3.0.2", + "type-is": "^2.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/body-parser/node_modules/content-type": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz", + "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/bytes": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", + "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/call-bind-apply-helpers": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz", + "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/call-bound": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz", + "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "get-intrinsic": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/content-disposition": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.1.0.tgz", + "integrity": "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/content-type": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz", + "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie": { + "version": "0.7.2", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz", + "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie-signature": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz", + "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==", + "license": "MIT", + "engines": { + "node": ">=6.6.0" + } + }, + "node_modules/cors": { + "version": "2.8.6", + "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz", + "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==", + "license": "MIT", + "dependencies": { + "object-assign": "^4", + "vary": "^1" + }, + "engines": { + "node": ">= 0.10" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/depd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", + "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/dunder-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz", + "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.1", + "es-errors": "^1.3.0", + "gopd": "^1.2.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/ee-first": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", + "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==", + "license": "MIT" + }, + "node_modules/encodeurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz", + "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/es-define-property": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz", + "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-errors": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz", + "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-object-atoms": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.2.tgz", + "integrity": "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/esbuild": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz", + "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.2", + "@esbuild/android-arm": "0.28.2", + "@esbuild/android-arm64": "0.28.2", + "@esbuild/android-x64": "0.28.2", + "@esbuild/darwin-arm64": "0.28.2", + "@esbuild/darwin-x64": "0.28.2", + "@esbuild/freebsd-arm64": "0.28.2", + "@esbuild/freebsd-x64": "0.28.2", + "@esbuild/linux-arm": "0.28.2", + "@esbuild/linux-arm64": "0.28.2", + "@esbuild/linux-ia32": "0.28.2", + "@esbuild/linux-loong64": "0.28.2", + "@esbuild/linux-mips64el": "0.28.2", + "@esbuild/linux-ppc64": "0.28.2", + "@esbuild/linux-riscv64": "0.28.2", + "@esbuild/linux-s390x": "0.28.2", + "@esbuild/linux-x64": "0.28.2", + "@esbuild/netbsd-arm64": "0.28.2", + "@esbuild/netbsd-x64": "0.28.2", + "@esbuild/openbsd-arm64": "0.28.2", + "@esbuild/openbsd-x64": "0.28.2", + "@esbuild/openharmony-arm64": "0.28.2", + "@esbuild/sunos-x64": "0.28.2", + "@esbuild/win32-arm64": "0.28.2", + "@esbuild/win32-ia32": "0.28.2", + "@esbuild/win32-x64": "0.28.2" + } + }, + "node_modules/escape-html": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", + "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==", + "license": "MIT" + }, + "node_modules/etag": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz", + "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/eventsource": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz", + "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==", + "license": "MIT", + "dependencies": { + "eventsource-parser": "^3.0.1" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/eventsource-parser": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.1.1.tgz", + "integrity": "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ==", + "license": "MIT", + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/express": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz", + "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==", + "license": "MIT", + "dependencies": { + "accepts": "^2.0.0", + "body-parser": "^2.2.1", + "content-disposition": "^1.0.0", + "content-type": "^1.0.5", + "cookie": "^0.7.1", + "cookie-signature": "^1.2.1", + "debug": "^4.4.0", + "depd": "^2.0.0", + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "etag": "^1.8.1", + "finalhandler": "^2.1.0", + "fresh": "^2.0.0", + "http-errors": "^2.0.0", + "merge-descriptors": "^2.0.0", + "mime-types": "^3.0.0", + "on-finished": "^2.4.1", + "once": "^1.4.0", + "parseurl": "^1.3.3", + "proxy-addr": "^2.0.7", + "qs": "^6.14.0", + "range-parser": "^1.2.1", + "router": "^2.2.0", + "send": "^1.1.0", + "serve-static": "^2.2.0", + "statuses": "^2.0.1", + "type-is": "^2.0.1", + "vary": "^1.1.2" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/express-rate-limit": { + "version": "8.7.1", + "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.7.1.tgz", + "integrity": "sha512-2FXbqkygil3mZiXzEtM0IjE/UBmBNot0J1GEVrJT4JbrvwOSoEtqtO+wHbiMQELWe1eNvHoYRg2dkjOid+6JkA==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.3", + "ip-address": "^10.2.0" + }, + "engines": { + "node": ">= 16" + }, + "funding": { + "url": "https://github.com/sponsors/express-rate-limit" + }, + "peerDependencies": { + "express": ">= 4.11" + } + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "license": "MIT" + }, + "node_modules/fast-uri": { + "version": "3.1.8", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.8.tgz", + "integrity": "sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ], + "license": "BSD-3-Clause" + }, + "node_modules/finalhandler": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz", + "integrity": "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.0", + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "on-finished": "^2.4.1", + "parseurl": "^1.3.3", + "statuses": "^2.0.1" + }, + "engines": { + "node": ">= 18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/forwarded": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz", + "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/fresh": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/fresh/-/fresh-2.0.0.tgz", + "integrity": "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/function-bind": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", + "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-intrinsic": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz", + "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "es-define-property": "^1.0.1", + "es-errors": "^1.3.0", + "es-object-atoms": "^1.1.1", + "function-bind": "^1.1.2", + "get-proto": "^1.0.1", + "gopd": "^1.2.0", + "has-symbols": "^1.1.0", + "hasown": "^2.0.2", + "math-intrinsics": "^1.1.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz", + "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==", + "license": "MIT", + "dependencies": { + "dunder-proto": "^1.0.1", + "es-object-atoms": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/gopd": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz", + "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-symbols": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz", + "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/hasown": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz", + "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==", + "license": "MIT", + "dependencies": { + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/hono": { + "version": "4.13.13", + "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.13.tgz", + "integrity": "sha512-CQ46U0ZkAGmbT/4UxdzzGJpacP2IeKgY4a5/tOI9AABbpOMfK739wfDXmv1usCk+3RkKj1hQy4/fjhiwa2xlrA==", + "license": "MIT", + "engines": { + "node": ">=16.9.0" + } + }, + "node_modules/http-errors": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz", + "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==", + "license": "MIT", + "dependencies": { + "depd": "~2.0.0", + "inherits": "~2.0.4", + "setprototypeof": "~1.2.0", + "statuses": "~2.0.2", + "toidentifier": "~1.0.1" + }, + "engines": { + "node": ">= 0.8" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/iconv-lite": { + "version": "0.7.3", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.3.tgz", + "integrity": "sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ==", + "license": "MIT", + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3.0.0" + }, + "engines": { + "node": ">=0.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "license": "ISC" + }, + "node_modules/ip-address": { + "version": "10.7.3", + "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.3.tgz", + "integrity": "sha512-A1kdq/tSb5QjvKvAMgIoEvDBIgL7qaqVP/jkvSwYYRZ9iEzvPpopxp2wQfu3SuZRHtpHNxMn8Fs0bS+gf5Xmwg==", + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, + "node_modules/ipaddr.js": { + "version": "1.9.1", + "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", + "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==", + "license": "MIT", + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/is-promise": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz", + "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==", + "license": "MIT" + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "license": "ISC" + }, + "node_modules/jose": { + "version": "6.2.12", + "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.12.tgz", + "integrity": "sha512-9NiFmJEex0sy2Dk58j2UGBSHgUs2ypF9eZSu4L6vjOX3Dp96Sw1F3uL+H+D1sx02jZZdzUT0HgvCy59CuvXcWw==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/panva" + } + }, + "node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", + "license": "MIT" + }, + "node_modules/json-schema-typed": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz", + "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==", + "license": "BSD-2-Clause" + }, + "node_modules/math-intrinsics": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz", + "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/media-typer": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.1.tgz", + "integrity": "sha512-yz3xRaG20c6/BOzvYoDaGtPmGscs7YivItZEEqe6GbwNfHuxu9YNmvnEkMzKldAGY4/80pRcQRZSEnhquk9XuQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/merge-descriptors": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-2.0.0.tgz", + "integrity": "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/mime-db": { + "version": "1.54.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz", + "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime-types": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz", + "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==", + "license": "MIT", + "dependencies": { + "mime-db": "^1.54.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT" + }, + "node_modules/negotiator": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.1.0.tgz", + "integrity": "sha512-NMPBRMJgiQHjbd8phG3Vebdx4kZ1H121rbl5IkMqeOsahptB9BKo/d7oJ3zTXqTgagn2bWlNSXkh0QUGM31RYg==", + "license": "MIT", + "dependencies": { + "content-type": "^2.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/negotiator/node_modules/content-type": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz", + "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/object-inspect": { + "version": "1.13.4", + "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz", + "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/on-finished": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz", + "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==", + "license": "MIT", + "dependencies": { + "ee-first": "1.1.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", + "license": "ISC", + "dependencies": { + "wrappy": "1" + } + }, + "node_modules/parseurl": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", + "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-to-regexp": { + "version": "8.4.2", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz", + "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/pkce-challenge": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz", + "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==", + "license": "MIT", + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/posthog-node": { + "version": "5.55.0", + "resolved": "https://registry.npmjs.org/posthog-node/-/posthog-node-5.55.0.tgz", + "integrity": "sha512-8dFtlDTqs0CKGZ8t4mUnk4NdShAgzru3B9D0MfM/NTBzlRyAjctivzWINLtMLRQxYjvgBohxy7RTwiQf4mPycQ==", + "license": "MIT", + "dependencies": { + "@posthog/core": "^1.55.2" + }, + "engines": { + "node": "^20.20.0 || >=22.22.0" + }, + "peerDependencies": { + "rxjs": "^7.0.0" + }, + "peerDependenciesMeta": { + "rxjs": { + "optional": true + } + } + }, + "node_modules/proxy-addr": { + "version": "2.0.8", + "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.8.tgz", + "integrity": "sha512-5nnx0yGyVUcY6t9RnWcARWtwT9F1D8O9rt08htPvnd49W1IgZtmLkhu9WfMzQj1cFxjHIO6connUNVW5k7AVyQ==", + "license": "MIT", + "dependencies": { + "forwarded": "0.2.0", + "ipaddr.js": "1.9.1" + }, + "engines": { + "node": ">= 0.10" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/qs": { + "version": "6.16.0", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.16.0.tgz", + "integrity": "sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==", + "license": "BSD-3-Clause", + "dependencies": { + "es-define-property": "^1.0.1", + "side-channel": "^1.1.1" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/range-parser": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.3.0.tgz", + "integrity": "sha512-hek2mFQpPuI4E1BBKrSto+BU3e3x4xuarsbiwr3+lf7p44juvFMV0XFWQAP3xUyqXA4RrXLIoaSUGbSt056ZMw==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/raw-body": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz", + "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==", + "license": "MIT", + "dependencies": { + "bytes": "~3.1.2", + "http-errors": "~2.0.1", + "iconv-lite": "~0.7.0", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/router": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz", + "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.0", + "depd": "^2.0.0", + "is-promise": "^4.0.0", + "parseurl": "^1.3.3", + "path-to-regexp": "^8.0.0" + }, + "engines": { + "node": ">= 18" + } + }, + "node_modules/safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "license": "MIT" + }, + "node_modules/send": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz", + "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.3", + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "etag": "^1.8.1", + "fresh": "^2.0.0", + "http-errors": "^2.0.1", + "mime-types": "^3.0.2", + "ms": "^2.1.3", + "on-finished": "^2.4.1", + "range-parser": "^1.2.1", + "statuses": "^2.0.2" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/serve-static": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.1.tgz", + "integrity": "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==", + "license": "MIT", + "dependencies": { + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "parseurl": "^1.3.3", + "send": "^1.2.0" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/setprototypeof": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", + "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", + "license": "ISC" + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/side-channel": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz", + "integrity": "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.4", + "side-channel-list": "^1.0.1", + "side-channel-map": "^1.0.1", + "side-channel-weakmap": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-list": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz", + "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.4" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-map": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz", + "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-weakmap": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz", + "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3", + "side-channel-map": "^1.0.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/statuses": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz", + "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/toidentifier": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", + "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", + "license": "MIT", + "engines": { + "node": ">=0.6" + } + }, + "node_modules/tsx": { + "version": "4.23.15", + "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.15.tgz", + "integrity": "sha512-Yiex1Ovn8z2xPpOWckIiysV1SSyRMY9BkLF++q0yKiDxCqRhosKfMg3janKkiLBwZ5c/YryloKwGZcrEmtwxKw==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "~0.28.0" + }, + "bin": { + "tsx": "dist/cli.mjs" + }, + "engines": { + "node": ">=18.0.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + } + }, + "node_modules/type-is": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.1.0.tgz", + "integrity": "sha512-faYHw0anBbc/kWF3zFTEnxSFOAGUX9GFbOBthvDdLsIlEoWOFOtS0zgCiQYwIskL9iGXZL3kAXD8OoZ4GmMATA==", + "license": "MIT", + "dependencies": { + "content-type": "^2.0.0", + "media-typer": "^1.1.0", + "mime-types": "^3.0.0" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/type-is/node_modules/content-type": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz", + "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/unpipe": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", + "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/vary": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", + "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==", + "license": "ISC" + }, + "node_modules/zod": { + "version": "3.25.76", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", + "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/zod-to-json-schema": { + "version": "3.25.2", + "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz", + "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==", + "license": "ISC", + "peerDependencies": { + "zod": "^3.25.28 || ^4" + } + } + } +} diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/package.json b/apps/mcp-analytics/typescript-sdk/stdio-server/package.json index ab5d00d9a..db5d595b3 100644 --- a/apps/mcp-analytics/typescript-sdk/stdio-server/package.json +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/package.json @@ -10,6 +10,8 @@ }, "dependencies": { "@modelcontextprotocol/sdk": "^1.12.0", + "@posthog/mcp": "0.22.2", + "posthog-node": "^5.55.0", "zod": "^3.23.8" }, "devDependencies": { diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/posthog-mcp-analytics-report.md b/apps/mcp-analytics/typescript-sdk/stdio-server/posthog-mcp-analytics-report.md new file mode 100644 index 000000000..b70dada71 --- /dev/null +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/posthog-mcp-analytics-report.md @@ -0,0 +1,27 @@ +# PostHog MCP Analytics Setup Report + +## Changes made + +- Detected a TypeScript STDIO MCP server using the official `@modelcontextprotocol/sdk` v1 and selected instrumentation Path A. +- Installed `@posthog/mcp` pinned to `0.22.2` (pre-1.0 beta) and `posthog-node`. +- Created one module-scope PostHog client using `POSTHOG_PROJECT_TOKEN` and `POSTHOG_HOST` from the environment. +- Wrapped the existing `McpServer` immediately after construction with `instrument(server, posthog, { captureModel: true })`. +- Added graceful PostHog shutdown on `SIGTERM`. Existing tools and their handlers were left unchanged. +- Configured the supplied project token and US Cloud host in `.env`. +- Verified the integration with `npm run build`; TypeScript compilation passes. + +Once the server handles MCP requests, PostHog will receive events including `$mcp_tools_list`, `$mcp_initialize`, `$mcp_tool_call`, and `$exception` for failed calls. + +## Files modified or created + +- `src/index.ts` +- `package.json` +- `package-lock.json` (created) +- `.env` (created) +- `posthog-mcp-analytics-report.md` (created) + +## Manual next steps + +1. Ensure `POSTHOG_PROJECT_TOKEN` and `POSTHOG_HOST` are supplied by the deployment environment; do not commit `.env`. +2. Restart the MCP server and invoke a tool to begin sending `$mcp_*` events. +3. Review MCP analytics in PostHog using the [MCP analytics dashboard and event reference](https://posthog.com/docs/mcp-analytics). diff --git a/apps/mcp-analytics/typescript-sdk/stdio-server/src/index.ts b/apps/mcp-analytics/typescript-sdk/stdio-server/src/index.ts index c5efc7f6a..9c73095a4 100644 --- a/apps/mcp-analytics/typescript-sdk/stdio-server/src/index.ts +++ b/apps/mcp-analytics/typescript-sdk/stdio-server/src/index.ts @@ -1,10 +1,23 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js' +import { instrument } from '@posthog/mcp' +import { PostHog } from 'posthog-node' import { z } from 'zod' +function requireEnv(name: 'POSTHOG_PROJECT_TOKEN' | 'POSTHOG_HOST'): string { + const value = process.env[name] + if (!value) throw new Error(`${name} is required`) + return value +} + +const posthog = new PostHog(requireEnv('POSTHOG_PROJECT_TOKEN'), { + host: requireEnv('POSTHOG_HOST'), +}) + // A minimal, PostHog-less MCP server. The `wizard mcp-analytics` flow should // detect the McpServer object below and wrap it with `instrument(server, posthog)`. const server = new McpServer({ name: 'workbench-stdio-server', version: '1.0.0' }) +instrument(server, posthog, { captureModel: true }) server.tool( 'echo', @@ -26,6 +39,11 @@ async function main(): Promise { // STDIO transport: never write to stdout (it is the protocol channel). } +process.on('SIGTERM', async () => { + await posthog.shutdown() + process.exit(0) +}) + main().catch((err) => { process.stderr.write(`fatal: ${String(err)}\n`) process.exit(1)