diff --git a/.github/PULL_REQUEST_TEMPLATE/mcpcat.md b/.github/PULL_REQUEST_TEMPLATE/mcpcat.md new file mode 100644 index 0000000..d3c1a4f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/mcpcat.md @@ -0,0 +1,44 @@ +# Add optional MCPcat analytics scaffolding (`--with-mcpcat`) to generated MCP servers + +> **TL;DR**: This PR adds an **opt-in** flag to scaffold privacy-safe analytics wiring for MCPcat in projects generated by `openapi-mcp-generator`. + +## Summary +This PR introduces a `--with-mcpcat` CLI flag that scaffolds: +- A tiny analytics shim to emit initialize/tool-call events. +- A default **local redaction** helper to scrub sensitive data before export. +- Minimal config via environment variables. +No behavior changes unless the flag and env vars are set. + +## Motivation +- Make freshly generated MCP servers **observable in minutes**. +- Encourage **privacy-by-default** analytics patterns. +- Reduce copy/paste wiring; standardize event shape (operationId, path, duration, status). + +## Changes +### CLI +- `generate` accepts `--with-mcpcat` (default: off). + +### Template files (added conditionally) +- `src/analytics/mcpcat.ts` – lazy import + safe no-op if SDK absent. +- `src/analytics/redact.ts` – OpenAPI-aware heuristics (e.g., `*token*`, `password`, `apiKey`, `authorization`, `email`). +- `src/analytics/config.ts` – reads env: + - `MCPCAT_ENABLED=true|false` (default `false`) + - `MCPCAT_PROJECT_ID=` + - `MCPCAT_ENDPOINT=` + - `MCPCAT_SAMPLE_RATE=1.0` (0–1) + +### Server wiring +- Hooks server `.initialize` and each tool invocation to record: + - `operationId`, HTTP `method`, `path` + - redacted `args` + - `outcome` (`ok`/`error`) + truncated error message + - `duration_ms` + +### Docs +- Adds a “Enable analytics (MCPcat)” section to generated README with privacy notes and quickstart. + +## Implementation Notes +- **Compile-time optional**: no imports unless flag is used. +- **Runtime safe**: try/catch around SDK import → graceful no-op if not installed. +- **Transport-agnostic**: compatible with stdio, SSE/web, and StreamableHTTP templates. +- **Edge-friendly**: avoids Node-only APIs in scaffolding to support edge runtimes (e.g., Workers).