mcpcat/AGENTS.md

Analytics tool for MCP (Model Context Protocol) servers - tracks tool usage patterns and provides insights

# Repository Guidelines

## Project Structure & Module Organization
- Source lives in `src/`; feature modules under `src/modules/`.
- Tests and integration shims in `src/tests/` (fixtures in `src/tests/fixtures/`).
- Docs in `docs/`; files under `docs/static/` are generated (inspect, don’t edit).
- Build output in `dist/`; coverage reports in `coverage/` — both untracked, regenerate locally.
- Shared config at the root: `tsconfig.json`, `eslint.config.js`, `vitest.config.ts`, `tsup.config.ts`.

## Build, Test, and Development Commands
- `pnpm install` (pnpm 10+) — sync dependencies.
- `pnpm dev` — watch-mode rebuild via tsup.
- `pnpm build` — emit production bundles to `dist/`.
- `pnpm test` — run Vitest; scope with `pnpm test src/tests/mcp-version-compatibility.test.ts` or add `--run`.
- `pnpm test:compatibility` — guard MCP protocol regressions.
- `pnpm lint`, `pnpm typecheck` — linting and type safety checks.
- `pnpm run prepublishOnly` — aggregated gate before publishing.

## Coding Style & Naming Conventions
- TypeScript with ES modules; 2-space indentation.
- Prefer named exports; use default exports only for legacy wrappers.
- Filenames: kebab- or lowerCamel-case (e.g., `context-parameters.ts`).
- ESLint + Prettier enforce formatting; run `pnpm lint --fix` or rely on lint-staged.
- Keep JSDoc concise for non-obvious flows.
- Route logging through `writeToLog` to use redaction hooks.

## Testing Guidelines
- Framework: Vitest. Place tests beside code or under `src/tests/` with a `.test.ts` suffix.
- Reuse fixtures in `src/tests/fixtures/` before adding new stubs.
- Coverage: `pnpm test -- --coverage` (V8 reports in `coverage/`).
- Update compatibility matrices in `src/tests/mcp-version-compatibility.test.ts` when transport behavior shifts.

## Commit & Pull Request Guidelines
- Conventional Commits (e.g., `feat(session): add persistence hooks`, `fix: handle retry backoff`).
- PRs target `main`. Include motivation, implementation notes, and validation (`pnpm build`, `pnpm test`, `pnpm lint`, `pnpm typecheck`).
- Link issues/discussions; call out schema or API changes for SDK consumers.
- Include screenshots or logs for telemetry-facing updates when relevant.

## Security & Configuration Tips
- Never hardcode MCPCat project IDs, API keys, or exporter credentials—use env vars in examples.
- Default logging writes to `~/mcpcat.log`; call `redactSensitiveInformation` before persisting payloads.
- Scrub secrets from docs and test fixtures.