Skip to content

Commit 28a15b8

Browse files
johnswordsjohnswords
authored
Merge pull request #6 from findmine/mcp-server-audit
feat: MCP Server Modernization v0.2.0
2 parents 92f88db + 37563d5 commit 28a15b8

35 files changed

+7037
-1824
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
lint:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: '20'
21+
cache: 'npm'
22+
- run: npm ci
23+
- run: npm run lint
24+
25+
typecheck:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- uses: actions/checkout@v4
29+
- uses: actions/setup-node@v4
30+
with:
31+
node-version: '20'
32+
cache: 'npm'
33+
- run: npm ci
34+
- run: npx tsc --noEmit
35+
36+
test:
37+
runs-on: ubuntu-latest
38+
steps:
39+
- uses: actions/checkout@v4
40+
- uses: actions/setup-node@v4
41+
with:
42+
node-version: '20'
43+
cache: 'npm'
44+
- run: npm ci
45+
- run: npm run test:coverage
46+
47+
build:
48+
runs-on: ubuntu-latest
49+
needs: [lint, typecheck, test]
50+
steps:
51+
- uses: actions/checkout@v4
52+
- uses: actions/setup-node@v4
53+
with:
54+
node-version: '20'
55+
cache: 'npm'
56+
- run: npm ci
57+
- run: npm run build

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,8 @@ build/
33
*.log
44
.env*
55

6+
# Test coverage
7+
coverage/
8+
69
# Test utilities
710
test-mcp.js

‎.prettierignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
build/
2+
node_modules/
3+
coverage/
4+
*.md

‎.prettierrc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"semi": true,
3+
"singleQuote": true,
4+
"tabWidth": 2,
5+
"trailingComma": "es5",
6+
"printWidth": 100
7+
}

‎CHANGELOG.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.2.0] - 2025-12-03
9+
10+
### Changed
11+
- Upgraded MCP SDK from 0.6.0 to 1.24.2
12+
- Added tool annotations (readOnlyHint, destructiveHint, openWorldHint)
13+
- Added Zod input validation for all tools
14+
- Refactored monolithic index.ts into modular components
15+
16+
### Added
17+
- Vitest testing infrastructure with unit tests
18+
- ESLint (flat config) + Prettier for code quality
19+
- GitHub Actions CI/CD pipeline
20+
- CHANGELOG.md
21+
22+
## [0.1.1] - Previous release
23+
- Initial MCP server implementation

‎CLAUDE.md‎

Lines changed: 85 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,38 @@
11
# FindMine MCP Development Guide
22

33
## Build & Development Commands
4+
5+
### Build and Watch
46
- `npm run build` - Build the project
57
- `npm run watch` - Watch for changes and rebuild
8+
- `npm run typecheck` - Run TypeScript type checking
69
- `npm run inspector` - Run MCP inspector for testing
710
- `NODE_ENV=development npm run build && node build/index.js` - Run with sample data
811

12+
### Testing (Vitest)
13+
- `npm test` - Run tests in watch mode
14+
- `npm run test:run` - Run tests once (useful for CI)
15+
- `npm run test:coverage` - Run tests with coverage report
16+
17+
### Code Quality
18+
- `npm run lint` - Run ESLint
19+
- `npm run lint:fix` - Run ESLint with auto-fix
20+
- `npm run format` - Format code with Prettier
21+
- `npm run format:check` - Check code formatting
22+
23+
### Pre-commit Checklist
24+
Run all checks before committing:
25+
```bash
26+
npm run typecheck && npm run lint && npm run format:check && npm run test:run
27+
```
28+
29+
## Testing Guidelines
30+
- Tests use **Vitest** framework
31+
- Tests located in `__tests__/` directories alongside source files
32+
- Aim for high coverage on utility functions and business logic
33+
- Use descriptive test names: `it('should return formatted product when valid data provided')`
34+
- Mock external dependencies (API calls, file system)
35+
936
## Code Style Guidelines
1037
- **Imports**: Group by source (external first, then local with .js extension)
1138
- **Types**: Use interfaces with descriptive names, explicit return types, optional props with '?'
@@ -14,10 +41,63 @@
1441
- **Error Handling**: Try-catch blocks with specific error messages, defensive programming
1542
- **Functions**: Use async/await, options pattern for multiple parameters
1643
- **TypeScript**: Strict mode enabled, ES2022 target, Node16 module resolution
44+
- **Linting**: Follow ESLint rules (flat config with TypeScript support)
45+
- **Formatting**: Prettier enforces consistent formatting
46+
47+
## Input Validation
48+
- All tool inputs validated with **Zod schemas** in `src/schemas/tool-inputs.ts`
49+
- Define schemas before implementing tools
50+
- Use discriminated unions for complex inputs
51+
- Return proper error responses for validation failures
52+
53+
## MCP Protocol Compliance
54+
- Built with **MCP SDK 1.24.2** (spec version 2025-11-25)
55+
- All tools include proper annotations:
56+
- `readOnlyHint` - Tools that don't modify state
57+
- `destructiveHint` - Tools that modify or delete data
58+
- `openWorldHint` - Tools with unbounded output
59+
- Follow MCP error response format for all failures
1760

1861
## Repository Structure
19-
- `src/index.ts` - Main MCP server implementation
20-
- `src/api/` - FindMine API client
21-
- `src/services/` - Business logic layer
22-
- `src/types/` - TypeScript type definitions
23-
- `src/utils/` - Utility functions and helpers
62+
```
63+
src/
64+
├── index.ts # MCP server bootstrap (entry point)
65+
├── config.ts # Environment configuration
66+
├── api/ # FindMine API client
67+
│ └── findmine-client.ts
68+
├── handlers/ # MCP protocol handlers
69+
│ ├── tools.ts # Tool execution handlers
70+
│ ├── resources.ts # Resource handlers
71+
│ └── prompts.ts # Prompt handlers
72+
├── tools/ # Tool definitions with MCP annotations
73+
│ └── index.ts
74+
├── schemas/ # Zod validation schemas
75+
│ ├── tool-inputs.ts # Input validation for all tools
76+
│ └── index.ts
77+
├── content/ # Static content
78+
│ └── style-guides.ts # Style guide content
79+
├── prompts/ # Prompt definitions
80+
│ ├── findmine-help.ts
81+
│ ├── outfit-completion.ts
82+
│ ├── styling-guide.ts
83+
│ └── index.ts
84+
├── services/ # Business logic layer
85+
│ └── findmine-service.ts
86+
├── types/ # TypeScript type definitions
87+
│ ├── findmine-api.ts
88+
│ └── mcp.ts
89+
└── utils/ # Utility functions and helpers
90+
├── cache.ts
91+
├── formatters.ts
92+
├── logger.ts
93+
├── mock-data.ts
94+
└── resource-mapper.ts
95+
```
96+
97+
## Architecture Principles
98+
- **Separation of concerns**: Handlers, tools, schemas, and business logic are separated
99+
- **Modular design**: Each directory has a single, clear responsibility
100+
- **Type safety**: Strict TypeScript with comprehensive type definitions
101+
- **Input validation**: All external inputs validated with Zod
102+
- **Error handling**: Consistent error responses across all handlers
103+
- **Testability**: Pure functions where possible, mockable dependencies

‎README.md‎

Lines changed: 96 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -94,15 +94,58 @@ type %APPDATA%\Claude\claude_desktop_config.json
9494

9595
## Development
9696

97-
### MCP Inspector
97+
### Available Scripts
9898

99-
The MCP Inspector is a development tool for testing your server:
99+
```bash
100+
# Build and watch
101+
npm run build # Build the project
102+
npm run watch # Watch for changes and rebuild
103+
npm run typecheck # Run TypeScript type checking
104+
105+
# Testing
106+
npm test # Run tests in watch mode
107+
npm run test:run # Run tests once
108+
npm run test:coverage # Run tests with coverage report
109+
110+
# Code quality
111+
npm run lint # Run ESLint
112+
npm run lint:fix # Run ESLint with auto-fix
113+
npm run format # Format code with Prettier
114+
npm run format:check # Check code formatting
115+
116+
# Development tools
117+
npm run inspector # Run MCP inspector (http://localhost:5173)
118+
```
119+
120+
### Testing
121+
122+
This project uses Vitest for testing. Tests are located in `__tests__/` directories alongside source files.
100123

101124
```bash
102-
npm run inspector
125+
# Run tests in watch mode
126+
npm test
127+
128+
# Run tests once (useful for CI)
129+
npm run test:run
130+
131+
# Generate coverage report
132+
npm run test:coverage
103133
```
104134

105-
This will open a web interface at http://localhost:5173 where you can interact with your server.
135+
### Code Quality
136+
137+
Before committing code:
138+
139+
```bash
140+
# Run all checks
141+
npm run typecheck && npm run lint && npm run format:check && npm run test:run
142+
```
143+
144+
The project uses:
145+
- **ESLint** for linting with TypeScript support
146+
- **Prettier** for code formatting
147+
- **Vitest** for testing
148+
- **GitHub Actions** for CI/CD
106149

107150
### Development Mode
108151

@@ -116,21 +159,21 @@ NODE_ENV=development npm run build && node build/index.js
116159

117160
The style guide can be customized to match your brand's specific styling philosophies and fashion guidance. To customize the style guide:
118161

119-
1. Locate the style guides in `src/index.ts` (search for `styleGuides`)
162+
1. Locate the style guides in `src/content/style-guides.ts`
120163
2. Modify the content for each category (`general`, `color_theory`, `body_types`, etc.)
121164
3. Add new categories by extending the `styleGuides` object
122165
4. Customize occasion-specific and seasonal advice
123166

124167
Example of adding a custom style guide category:
125168

126169
```typescript
127-
// In src/index.ts
128-
const styleGuides: Record<string, string> = {
170+
// In src/content/style-guides.ts
171+
export const styleGuides: Record<string, string> = {
129172
// Existing categories...
130-
173+
131174
// Add your custom category
132175
your_brand_style: `# Your Brand Style Guide
133-
176+
134177
## Brand Aesthetic
135178
- Key elements of your brand's visual identity
136179
- Core style principles
@@ -149,15 +192,53 @@ const styleGuides: Record<string, string> = {
149192
};
150193
```
151194

152-
For complete customization, you can modify the entire `get_style_guide` handler in `src/index.ts`.
195+
For complete customization, you can modify the entire `get_style_guide` handler in `src/handlers/tools.ts`.
153196

154197
### Project Structure
155198

156-
- `src/index.ts`: Main MCP server implementation
157-
- `src/api/`: FindMine API client
158-
- `src/services/`: Business logic and service layer
159-
- `src/types/`: TypeScript type definitions
160-
- `src/utils/`: Utility functions and helpers
199+
```
200+
src/
201+
├── index.ts # MCP server bootstrap and initialization
202+
├── config.ts # Environment configuration
203+
├── api/ # FindMine API client
204+
│ └── findmine-client.ts
205+
├── handlers/ # MCP protocol handlers
206+
│ ├── tools.ts # Tool execution handlers
207+
│ ├── resources.ts # Resource handlers
208+
│ └── prompts.ts # Prompt handlers
209+
├── tools/ # Tool definitions with MCP annotations
210+
│ └── index.ts
211+
├── schemas/ # Zod validation schemas
212+
│ ├── tool-inputs.ts # Input validation for all tools
213+
│ └── index.ts
214+
├── content/ # Static content
215+
│ └── style-guides.ts # Style guide content
216+
├── prompts/ # Prompt definitions
217+
│ ├── findmine-help.ts
218+
│ ├── outfit-completion.ts
219+
│ ├── styling-guide.ts
220+
│ └── index.ts
221+
├── services/ # Business logic layer
222+
│ └── findmine-service.ts
223+
├── types/ # TypeScript type definitions
224+
│ ├── findmine-api.ts
225+
│ └── mcp.ts
226+
└── utils/ # Utility functions and helpers
227+
├── cache.ts
228+
├── formatters.ts
229+
├── logger.ts
230+
├── mock-data.ts
231+
└── resource-mapper.ts
232+
```
233+
234+
### Technical Details
235+
236+
This server is built with:
237+
- **MCP SDK 1.24.2** with full spec compliance (2025-11-25)
238+
- **Tool annotations** for read-only, destructive, and open-world hints
239+
- **Zod validation** for all tool inputs
240+
- **Modular architecture** with separated concerns
241+
- **100% test coverage** on utility functions
161242

162243
## API Examples
163244

‎eslint.config.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import eslint from '@eslint/js';
2+
import tseslint from 'typescript-eslint';
3+
import eslintConfigPrettier from 'eslint-config-prettier';
4+
5+
export default tseslint.config(
6+
eslint.configs.recommended,
7+
...tseslint.configs.strictTypeChecked,
8+
eslintConfigPrettier,
9+
{
10+
languageOptions: {
11+
parserOptions: {
12+
project: './tsconfig.json',
13+
tsconfigRootDir: import.meta.dirname,
14+
},
15+
},
16+
rules: {
17+
'@typescript-eslint/no-explicit-any': 'error',
18+
'@typescript-eslint/explicit-function-return-type': 'warn',
19+
},
20+
},
21+
{
22+
ignores: ['build/', 'node_modules/', 'coverage/', 'eslint.config.ts'],
23+
}
24+
);

0 commit comments

Comments
 (0)