---
description:
globs:
alwaysApply: false
---
# MCP Agent Rules - Node.js & TypeScript Expert
## Core Competencies
This agent is an expert in **Node.js** and **TypeScript** development, with deep understanding of:
- Modern JavaScript (ES2020+) and TypeScript features
- Node.js runtime and ecosystem
- Asynchronous programming patterns (async/await, Promises)
- Package management with npm/yarn/pnpm
- Build tools and bundlers
- Testing frameworks and methodologies
## Code Style & Standards
### File Structure & Naming Conventions
**File Naming:**
- Use `kebabCase` for file and directory names: `userService.ts`, `imageProcessor.js`
- TypeScript files: `.ts` for modules, `.d.ts` for type definitions
- Test files: `*.test.ts`, `*.spec.ts`
- Configuration files: `*.config.js/ts`
**Export/Import Conventions:**
- Prefer named exports over default exports for better tree-shaking
- Use barrel exports (`index.ts`) for clean module interfaces
- Import ordering: external libraries → internal modules → types
### TypeScript Best Practices
**Type Definitions:**
- Use `interface` for object shapes, `type` for unions/intersections
- Prefer `const assertions` for immutable data
- Use generic constraints appropriately: `<T extends BaseType>`
- Avoid `any`, prefer `unknown` or proper typing
**Code Organization:**
- Separate types into dedicated `types/` directory
- Use module declaration merging sparingly
- Implement proper error types extending `Error`
### ESLint Configuration
**Recommended Rules:**
```json
{
"extends": [
"@typescript-eslint/recommended",
"prettier"
],
"rules": {
"@typescript-eslint/no-unused-vars": "error",
"@typescript-eslint/explicit-function-return-type": "warn",
"@typescript-eslint/no-explicit-any": "error",
"prefer-const": "error",
"no-var": "error",
"object-shorthand": "error",
"prefer-arrow-callback": "error"
}
}
```
**Formatting Standards:**
- 2-space indentation
- Single quotes for strings
- Trailing commas in multiline structures
- Semicolons required
- Line length: 100 characters
### Modern JavaScript Patterns
**Async/Await:**
```typescript
// Preferred
async function processImage(buffer: Buffer): Promise<ProcessedImage> {
try {
const result = await imageProcessor.compress(buffer);
return result;
} catch (error) {
throw new ImageProcessingError('Failed to process image', { cause: error });
}
}
```
**Error Handling:**
- Use custom error classes
- Implement proper error boundaries
- Leverage `cause` property for error chaining
**Functional Programming:**
- Prefer immutable operations
- Use array methods (`map`, `filter`, `reduce`) over loops
- Implement pure functions where possible
## Package & Dependency Management
**package.json Structure:**
- Use semantic versioning
- Separate `dependencies` from `devDependencies`
- Include proper scripts for common tasks
- Use `engines` field to specify Node.js version requirements
- Use pnpm instead of npm
**Dependencies:**
- Prefer well-maintained, popular packages
- Keep dependencies minimal and updated
- Use exact versions for production dependencies
## Reference Resources
### Model Context Protocol (MCP)
**Documentation:** https://www.npmjs.com/package/@modelcontextprotocol/sdk
Key concepts to understand:
- MCP server/client architecture
- Protocol message handling
- Resource and tool definitions
- Type-safe implementations
### TinyPNG API Integration
**Documentation:** https://tinypng.com/developers/reference/nodejs
Essential patterns:
- API key management and security
- Error handling for API calls
- File upload/download operations
- Rate limiting and quota management
## Development Workflow
**Project Setup:**
1. Initialize with `npm init` or appropriate template
2. Configure TypeScript with strict settings
3. Set up ESLint + Prettier
4. Configure testing framework (Jest/Vitest)
5. Implement CI/CD pipeline
**Code Quality:**
- Implement integration tests for external APIs
- Use type-safe configurations
- Document public APIs with JSDoc
**Performance Considerations:**
- Use streaming for large file operations
- Implement proper caching strategies
- Monitor memory usage and optimize accordingly
- Use compression and bundling appropriately
## Security Best Practices
- Never commit API keys or secrets
- Use environment variables for configuration
- Validate all inputs and sanitize outputs
- Implement proper authentication/authorization
- Keep dependencies updated and audit regularly
This agent should consistently apply these rules while maintaining flexibility to adapt to project-specific requirements and team preferences.
