feat: MCP Server Modernization v0.2.0

.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npx tsc --noEmit
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run test:coverage
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build

.gitignore

@@ -3,5 +3,8 @@ build/
 *.log
 .env*
 
+# Test coverage
+coverage/
+
 # Test utilities
 test-mcp.js

.prettierignore

@@ -0,0 +1,4 @@
+build/
+node_modules/
+coverage/
+*.md

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-12-03
+
+### Changed
+- Upgraded MCP SDK from 0.6.0 to 1.24.2
+- Added tool annotations (readOnlyHint, destructiveHint, openWorldHint)
+- Added Zod input validation for all tools
+- Refactored monolithic index.ts into modular components
+
+### Added
+- Vitest testing infrastructure with unit tests
+- ESLint (flat config) + Prettier for code quality
+- GitHub Actions CI/CD pipeline
+- CHANGELOG.md
+
+## [0.1.1] - Previous release
+- Initial MCP server implementation

CLAUDE.md

@@ -1,11 +1,38 @@
 # FindMine MCP Development Guide
 
 ## Build & Development Commands
+
+### Build and Watch
 - `npm run build` - Build the project
 - `npm run watch` - Watch for changes and rebuild
+- `npm run typecheck` - Run TypeScript type checking
 - `npm run inspector` - Run MCP inspector for testing
 - `NODE_ENV=development npm run build && node build/index.js` - Run with sample data
 
+### Testing (Vitest)
+- `npm test` - Run tests in watch mode
+- `npm run test:run` - Run tests once (useful for CI)
+- `npm run test:coverage` - Run tests with coverage report
+
+### Code Quality
+- `npm run lint` - Run ESLint
+- `npm run lint:fix` - Run ESLint with auto-fix
+- `npm run format` - Format code with Prettier
+- `npm run format:check` - Check code formatting
+
+### Pre-commit Checklist
+Run all checks before committing:
+```bash
+npm run typecheck && npm run lint && npm run format:check && npm run test:run
+```
+
+## Testing Guidelines
+- Tests use **Vitest** framework
+- Tests located in `__tests__/` directories alongside source files
+- Aim for high coverage on utility functions and business logic
+- Use descriptive test names: `it('should return formatted product when valid data provided')`
+- Mock external dependencies (API calls, file system)
+
 ## Code Style Guidelines
 - **Imports**: Group by source (external first, then local with .js extension)
 - **Types**: Use interfaces with descriptive names, explicit return types, optional props with '?'
@@ -14,10 +41,63 @@
 - **Error Handling**: Try-catch blocks with specific error messages, defensive programming
 - **Functions**: Use async/await, options pattern for multiple parameters
 - **TypeScript**: Strict mode enabled, ES2022 target, Node16 module resolution
+- **Linting**: Follow ESLint rules (flat config with TypeScript support)
+- **Formatting**: Prettier enforces consistent formatting
+
+## Input Validation
+- All tool inputs validated with **Zod schemas** in `src/schemas/tool-inputs.ts`
+- Define schemas before implementing tools
+- Use discriminated unions for complex inputs
+- Return proper error responses for validation failures
+
+## MCP Protocol Compliance
+- Built with **MCP SDK 1.24.2** (spec version 2025-11-25)
+- All tools include proper annotations:
+  - `readOnlyHint` - Tools that don't modify state
+  - `destructiveHint` - Tools that modify or delete data
+  - `openWorldHint` - Tools with unbounded output
+- Follow MCP error response format for all failures
 
 ## Repository Structure
-- `src/index.ts` - Main MCP server implementation
-- `src/api/` - FindMine API client
-- `src/services/` - Business logic layer
-- `src/types/` - TypeScript type definitions
-- `src/utils/` - Utility functions and helpers
+```
+src/
+├── index.ts              # MCP server bootstrap (entry point)
+├── config.ts             # Environment configuration
+├── api/                  # FindMine API client
+│   └── findmine-client.ts
+├── handlers/             # MCP protocol handlers
+│   ├── tools.ts          # Tool execution handlers
+│   ├── resources.ts      # Resource handlers
+│   └── prompts.ts        # Prompt handlers
+├── tools/                # Tool definitions with MCP annotations
+│   └── index.ts
+├── schemas/              # Zod validation schemas
+│   ├── tool-inputs.ts    # Input validation for all tools
+│   └── index.ts
+├── content/              # Static content
+│   └── style-guides.ts   # Style guide content
+├── prompts/              # Prompt definitions
+│   ├── findmine-help.ts
+│   ├── outfit-completion.ts
+│   ├── styling-guide.ts
+│   └── index.ts
+├── services/             # Business logic layer
+│   └── findmine-service.ts
+├── types/                # TypeScript type definitions
+│   ├── findmine-api.ts
+│   └── mcp.ts
+└── utils/                # Utility functions and helpers
+    ├── cache.ts
+    ├── formatters.ts
+    ├── logger.ts
+    ├── mock-data.ts
+    └── resource-mapper.ts
+```
+
+## Architecture Principles
+- **Separation of concerns**: Handlers, tools, schemas, and business logic are separated
+- **Modular design**: Each directory has a single, clear responsibility
+- **Type safety**: Strict TypeScript with comprehensive type definitions
+- **Input validation**: All external inputs validated with Zod
+- **Error handling**: Consistent error responses across all handlers
+- **Testability**: Pure functions where possible, mockable dependencies

README.md

@@ -94,15 +94,58 @@ type %APPDATA%\Claude\claude_desktop_config.json
 
 ## Development
 
-### MCP Inspector
+### Available Scripts
 
-The MCP Inspector is a development tool for testing your server:
+```bash
+# Build and watch
+npm run build              # Build the project
+npm run watch             # Watch for changes and rebuild
+npm run typecheck         # Run TypeScript type checking
+
+# Testing
+npm test                  # Run tests in watch mode
+npm run test:run          # Run tests once
+npm run test:coverage     # Run tests with coverage report
+
+# Code quality
+npm run lint              # Run ESLint
+npm run lint:fix          # Run ESLint with auto-fix
+npm run format            # Format code with Prettier
+npm run format:check      # Check code formatting
+
+# Development tools
+npm run inspector         # Run MCP inspector (http://localhost:5173)
+```
+
+### Testing
+
+This project uses Vitest for testing. Tests are located in `__tests__/` directories alongside source files.
 
 ```bash
-npm run inspector
+# Run tests in watch mode
+npm test
+
+# Run tests once (useful for CI)
+npm run test:run
+
+# Generate coverage report
+npm run test:coverage
 ```
 
-This will open a web interface at http://localhost:5173 where you can interact with your server.
+### Code Quality
+
+Before committing code:
+
+```bash
+# Run all checks
+npm run typecheck && npm run lint && npm run format:check && npm run test:run
+```
+
+The project uses:
+- **ESLint** for linting with TypeScript support
+- **Prettier** for code formatting
+- **Vitest** for testing
+- **GitHub Actions** for CI/CD
 
 ### Development Mode
 
@@ -116,21 +159,21 @@ NODE_ENV=development npm run build && node build/index.js
 
 The style guide can be customized to match your brand's specific styling philosophies and fashion guidance. To customize the style guide:
 
-1. Locate the style guides in `src/index.ts` (search for `styleGuides`)
+1. Locate the style guides in `src/content/style-guides.ts`
 2. Modify the content for each category (`general`, `color_theory`, `body_types`, etc.)
 3. Add new categories by extending the `styleGuides` object
 4. Customize occasion-specific and seasonal advice
 
 Example of adding a custom style guide category:
 
 ```typescript
-// In src/index.ts
-const styleGuides: Record<string, string> = {
+// In src/content/style-guides.ts
+export const styleGuides: Record<string, string> = {
   // Existing categories...
-  
+
   // Add your custom category
   your_brand_style: `# Your Brand Style Guide
-  
+
 ## Brand Aesthetic
 - Key elements of your brand's visual identity
 - Core style principles
@@ -149,15 +192,53 @@ const styleGuides: Record<string, string> = {
 };
 ```
 
-For complete customization, you can modify the entire `get_style_guide` handler in `src/index.ts`.
+For complete customization, you can modify the entire `get_style_guide` handler in `src/handlers/tools.ts`.
 
 ### Project Structure
 
-- `src/index.ts`: Main MCP server implementation
-- `src/api/`: FindMine API client
-- `src/services/`: Business logic and service layer
-- `src/types/`: TypeScript type definitions
-- `src/utils/`: Utility functions and helpers
+```
+src/
+├── index.ts              # MCP server bootstrap and initialization
+├── config.ts             # Environment configuration
+├── api/                  # FindMine API client
+│   └── findmine-client.ts
+├── handlers/             # MCP protocol handlers
+│   ├── tools.ts          # Tool execution handlers
+│   ├── resources.ts      # Resource handlers
+│   └── prompts.ts        # Prompt handlers
+├── tools/                # Tool definitions with MCP annotations
+│   └── index.ts
+├── schemas/              # Zod validation schemas
+│   ├── tool-inputs.ts    # Input validation for all tools
+│   └── index.ts
+├── content/              # Static content
+│   └── style-guides.ts   # Style guide content
+├── prompts/              # Prompt definitions
+│   ├── findmine-help.ts
+│   ├── outfit-completion.ts
+│   ├── styling-guide.ts
+│   └── index.ts
+├── services/             # Business logic layer
+│   └── findmine-service.ts
+├── types/                # TypeScript type definitions
+│   ├── findmine-api.ts
+│   └── mcp.ts
+└── utils/                # Utility functions and helpers
+    ├── cache.ts
+    ├── formatters.ts
+    ├── logger.ts
+    ├── mock-data.ts
+    └── resource-mapper.ts
+```
+
+### Technical Details
+
+This server is built with:
+- **MCP SDK 1.24.2** with full spec compliance (2025-11-25)
+- **Tool annotations** for read-only, destructive, and open-world hints
+- **Zod validation** for all tool inputs
+- **Modular architecture** with separated concerns
+- **100% test coverage** on utility functions
 
 ## API Examples
 

eslint.config.ts

@@ -0,0 +1,24 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  eslintConfigPrettier,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.json',
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/explicit-function-return-type': 'warn',
+    },
+  },
+  {
+    ignores: ['build/', 'node_modules/', 'coverage/', 'eslint.config.ts'],
+  }
+);