Tiger pg-aiguide — MCP Server Code Style Guide

Build, Test & Run Commands

• Build: ./bun run build - Compiles TypeScript to JavaScript
• Watch mode: ./bun run watch http - Watches for changes and rebuilds automatically
• Run server: ./bun run start stdio - Starts the MCP server using stdio transport
• Checks: ./check - All-in-one command to lint and test. Run before every commit. Covers TypeScript (biome, tsc, tests) and Python (ruff format + ruff check in ingest/). Python checks are skipped with a warning if uv is missing.

Code Style Guidelines

• Use ES modules with .js extension in import paths
• Strictly type all functions and variables with TypeScript
• Follow zod schema patterns for tool input validation
• Use .nullable() instead of .optional() for optional MCP tool parameters (required for gpt-5 compatibility)
• Prefer async/await over callbacks and Promise chains
• Place all imports at top of file, grouped by external then internal
• Use descriptive variable names that clearly indicate purpose
• Implement proper cleanup for timers and resources in server shutdown
• Follow camelCase for variables/functions, PascalCase for types/classes, UPPER_CASE for constants
• Handle errors with try/catch blocks and provide clear error messages
• Use consistent indentation (2 spaces) and trailing commas in multi-line objects

Python (ingest/)

• Formatted and linted by ruff; config lives in ingest/pyproject.toml
• Never commit generated artifacts (pycache/, *.pyc, .venv/, .ruff_cache/)
• Add dev-only tooling to the dev dependency group, not dependencies
• Commit the regenerated uv.lock whenever dependencies change; CI runs uv lock --check
• Chain re-raised exceptions with raise ... from e to preserve the original traceback

Releasing

• Release with ./bun release from a clean main; don't create tags or releases in the GitHub UI. See DEVELOPMENT.md.
• The script bumps the version in package.json, .claude-plugin/marketplace.json, and .cursor-plugin/plugin.json, commits release: vX.Y.Z, tags, and pushes. The tag push triggers .github/workflows/publish.yml.
• The push to main requires bypassing the pull-request rule. Without that access the tag pushes but the commit is rejected, leaving main behind the released version.