45 lines
1.9 KiB
Markdown
45 lines
1.9 KiB
Markdown
# 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=<id>`
|
||
- `MCPCAT_ENDPOINT=<optional override>`
|
||
- `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).
|