Scratchpad MCP

# Repository Guidelines ## Project Structure & Module Organization - `src/`: TypeScript source. Entry: `src/server.ts`; helpers in `src/server-helpers.ts`; modules in `src/tools/` and `src/database/`. - `tests/`: Vitest specs (`*.test.ts`). - `scripts/`: Utilities and `serve-workflow/` web viewer. - `dist/`: Build output (generated by `tsup`). Do not edit. - `extensions/` + `dict` (symlink): Optional Chinese tokenization assets. ## Build, Test, and Development Commands - `npm run dev`: Watch build with tsup for rapid iteration. - `npm run build`: Produce ESM bundle in `dist/`. - `npm test` / `npm run test:watch`: Run Vitest once / in watch mode. - `npm run typecheck`: Strict TypeScript type checks (`tsc --noEmit`). - `npm run lint` / `npm run lint:fix`: ESLint validate / autofix. - `npm run format`: Prettier format `src/**/*.ts`. - `npm run serve` / `npm run serve:dev`: Launch workflow web viewer. ## Coding Style & Naming Conventions - TypeScript strict mode; no `any`, explicit return types, prefer `const`. - Formatting: Prettier (2 spaces, single quotes, semicolons, LF, width 100). - Linting: ESLint with `@typescript-eslint` rules enforced in CI/local. - File names: prefer kebab-case (`server-helpers.ts`, `tools/search.ts`). Some database classes use `PascalCase` files (e.g., `ScratchpadDatabase.ts`). - Exports: favor named exports; functions/vars use lowerCamelCase; types/interfaces PascalCase. ## Testing Guidelines - Framework: Vitest (`tests/**/*.test.ts`). Example: `tests/extraction.test.ts`. - Coverage: v8 provider with text/json/html reporters. Keep or improve coverage for touched files. - Write deterministic, unit-level tests near affected modules; avoid I/O in pure unit tests. - Run locally: `npm test`; for TDD use `npm run test:watch`. ## Commit & Pull Request Guidelines - Commits follow Conventional Commits (e.g., `feat(core): ...`, `fix(database): ...`, `docs: ...`). - Scope changes logically; keep messages imperative and concise. - PRs must include: clear description, linked issues, test coverage for changes, and docs updates (README/AGENTS.md) when behavior or commands change. - For web viewer changes, add before/after screenshots when feasible. ## Security & Configuration Tips - Node 18+ required. Do not run `dist/server.js` directly; always start via `./start-mcp.sh` (ensures correct paths and tokenizer loading). - Env vars: `OPENAI_API_KEY` for AI analysis; `SCRATCHPAD_DB_PATH` to override DB path. - Database files are in repo root by default (e.g., `scratchpad.v6.db`). Avoid committing private DBs.