localutils-mcp-server: Instructions file for Codex

Repo Guidelines for localutils-mcp-server

This project is a TypeScript implementation of an MCP (Model Context Protocol) server that exposes several local utilities. All source lives under src/ and the compiled output is committed in build/.

Development Workflow

• Use pnpm for dependency management. Install dependencies with pnpm install which also sets up the Husky pre-commit hook.
• Build compiled output with pnpm run build. The pre-commit hook automatically runs npm run build to ensure build/ is up to date.
• Run tests with pnpm test. Aim for over 80% coverage as noted in .cursor/rules/testing.mdc.
• Node.js version 16 or higher is required.

Coding Standards

TypeScript style guidelines are defined in .cursor/rules/typescript.mdc and include:

• Use named exports, avoid default exports.
• Order imports as: Node built-ins, external packages, internal modules. Separate groups with blank lines.
• Avoid any; prefer explicit types and interfaces.
• Use PascalCase for classes/interfaces and camelCase for variables/functions. Prefix interfaces with I and type aliases with T.
• Use arrow functions for callbacks, handle errors properly, and prefer async/await.
• Format with two-space indentation, 100 character line length, semicolons, single quotes, and trailing commas in multiline structures.

Documentation standards from .cursor/rules/documentation.mdc require thorough README files, JSDoc comments for public APIs, and Markdown with proper heading hierarchy. Keep comments focused on why and ensure all public functions are documented.

MCP-specific documentation must follow .cursor/rules/mcp-docs.mdc which mandates Mermaid diagrams describing workflows and protocol details. Each MCP implementation under src/mcp/ should include these diagrams and explanations.

Testing guidelines in .cursor/rules/testing.mdc specify placing tests in src/__tests__ with .test.ts suffix, following the Arrange/Act/Assert pattern, and keeping tests independent.