Skip to content

feat: MCP Server Modernization v0.2.0#6

Merged
johnswords merged 3 commits intomainfrom
mcp-server-audit
Dec 3, 2025
Merged

feat: MCP Server Modernization v0.2.0#6
johnswords merged 3 commits intomainfrom
mcp-server-audit

Conversation

@johnswords
Copy link
Contributor

Summary

Full modernization of the FindMine MCP server from v0.1.1 to v0.2.0, bringing it up to 2025 standards.

Major Changes

  • SDK Upgrade: MCP SDK 0.6.0 -> 1.24.2 (18 major versions, many improvements)
  • Architecture Refactor: Monolithic index.ts (1509 lines) decomposed into modular components (117 lines)
  • Tool Annotations: Added MCP protocol hints (readOnlyHint, destructiveHint, openWorldHint)
  • Input Validation: Zod schemas for all tool inputs with type-safe parsing

New Infrastructure

  • Testing: Vitest with 45 unit tests covering cache and formatter utilities
  • Code Quality: ESLint (flat config) + Prettier with zero lint errors
  • CI/CD: GitHub Actions pipeline for automated testing on push/PR
  • Documentation: CHANGELOG.md for tracking releases

New Architecture

src/
├── handlers/       # Request routing (resources, prompts, tools)
├── schemas/        # Zod input validation schemas  
├── tools/          # Tool definitions with MCP annotations
├── prompts/        # Prompt templates
├── content/        # Static content (style guides)
├── services/       # Business logic (FindMine API)
├── utils/          # Utilities (cache, formatters, logger)
└── index.ts        # Entry point (117 lines, down from 1509)

Test Plan

  • Build passes (npm run build)
  • Lint passes with 0 errors (npm run lint)
  • All 45 tests pass (npm test)
  • CI pipeline runs on PR
  • Manual testing with MCP inspector (npm run inspector)
  • Verify tool annotations visible to MCP clients

Breaking Changes

Internal architecture completely restructured, but external MCP API unchanged. Existing MCP clients should continue to work without modification.

Related

  • Addresses technical debt from rapid initial development
  • Prepares codebase for future feature additions

- Remove unused FindMineErrorResponse import, add FindMineProduct
- Add proper interfaces for raw API responses (RawLook, RawCompleteTheLookResponse, RawErrorResponse)
- Replace Record<string, any> with object type + explicit entry casting
- Replace non-null assertions (!) with nullish coalescing defaults
- Wrap numbers in String() for template literals
- Add type guards for primitive values before stringification
- Remove unnecessary optional chain on typed value
- Normalize look data with proper RawLook typing instead of any
The "stop living in the SDK dark ages" release.

Major changes:
- Upgrade MCP SDK 0.6.0 -> 1.24.2 (finally in this decade)
- Refactor index.ts from 1509 lines to 117 lines (92% diet success)
- Add tool annotations (readOnlyHint, destructiveHint, openWorldHint)
- Add Zod validation for all tool inputs (trust issues, but make it type-safe)

New infrastructure:
- Vitest testing with 45 unit tests (coverage: cache, formatters)
- ESLint flat config + Prettier (the code now has standards)
- GitHub Actions CI/CD pipeline (automation > manual labor)
- CHANGELOG.md (because memory is fallible)

Architecture:
- src/handlers/ - request routing (resources, prompts, tools)
- src/schemas/ - Zod input validation schemas
- src/tools/ - tool definitions with MCP annotations
- src/prompts/ - prompt templates
- src/content/ - static content (style guides)

Breaking: Internal restructure, external API unchanged.
@findmine findmine deleted a comment from chatgpt-codex-connector bot Dec 3, 2025
- Add complete development scripts documentation
- Document new modular project structure (handlers, tools, schemas)
- Add testing section with Vitest coverage info
- Add code quality section (ESLint, Prettier, pre-commit)
- Document MCP SDK 1.24.2 compliance and tool annotations
- Update CLAUDE.md with testing guidelines and architecture principles
@johnswords johnswords merged commit 28a15b8 into main Dec 3, 2025
6 checks passed
@johnswords johnswords deleted the mcp-server-audit branch December 3, 2025 22:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant