mcpcat/AGENTS.md

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

# Repository Guidelines

## Project Structure & Module Organization
- `src/` holds the TypeScript source; shared utilities live in `src/modules/`, and compatibility fixtures sit in `src/tests/`.
- `docs/` contains published documentation assets; avoid editing generated files under `docs/static/`.
- `dist/` and `coverage/` are build artifacts; regenerate them locally but do not commit unless release tooling requires it.
- Root configs (`tsconfig.json`, `eslint.config.js`, `vitest.config.ts`, `tsup.config.ts`) define the build, lint, and test toolchain—reuse their defaults when adding modules.

## Build, Test, and Development Commands
- `pnpm install` installs dependencies (pnpm 10+ is expected).
- `pnpm dev` runs `tsup --watch` to rebuild the SDK as you edit.
- `pnpm build` bundles the library to `dist/` via tsup; run before publishing or snapshot testing.
- `pnpm test` executes the Vitest suite; add `--run` or a path for focused runs, e.g. `pnpm test src/tests/mcp-version-compatibility.test.ts`.
- `pnpm test:compatibility` runs the MCP version compatibility regression test.
- `pnpm lint` and `pnpm typecheck` enforce ESLint + TypeScript invariants.
- `pnpm run prepublishOnly` chains build, test, lint, and typecheck for a final validation pass.

## Coding Style & Naming Conventions
- Use TypeScript with ECMAScript modules and 2-space indentation; prefer named exports from module files.
- Keep filenames kebab- or lowerCamel-case (`tools.ts`, `context-parameters.ts`); align new files with their neighbors.
- Follow ESLint + Prettier defaults (`pnpm lint --fix`), and rely on lint-staged to format staged files.
- Document complex flows with concise JSDoc blocks; avoid console logging—use `writeToLog` utilities instead.

## Testing Guidelines
- Vitest is the unit/integration framework; place specs beside implementation or under `src/tests/` with a `.test.ts` suffix.
- Maintain coverage by extending existing suites; `pnpm test -- --coverage` produces V8 coverage reports in `coverage/`.
- Test doubles should reuse helpers in `src/tests/fixtures` when available before creating new ones.

## Commit & Pull Request Guidelines
- Commits follow Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`); scope optional but encouraged (e.g. `feat(session): add persistence hooks`).
- PRs target `main` with a clear summary, motivation, and validation notes (tests run, screenshots for telemetry dashboards when relevant).
- Link GitHub issues or discussions when applicable and call out any schema or API changes for downstream SDK users.
- Verify CI-critical commands locally (`pnpm build`, `pnpm test`, `pnpm lint`, `pnpm typecheck`) before requesting review.

## Security & Configuration Tips
- Do not hardcode MCPCat project IDs, API keys, or exporter credentials; source them from environment variables when demonstrating usage.
- Log output defaults to `~/mcpcat.log`; ensure sensitive data is redacted via the provided `redactSensitiveInformation` hook in examples.