springdocs-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that provides access to Spring Boot and Spring Framework documentation. It's a TypeScript-based tool published as @enokdev/springdocs-mcp on npm, enabling AI assistants to search and retrieve Spring documentation in real-time.

Commands

Building and Running

npm run build         # Compile TypeScript to JavaScript (outputs to build/)
npm start            # Run the compiled server
npm run dev          # Build and start in one command
npm run watch        # Watch mode for development

Testing

npm test             # Build, then run the vitest suite in tests/ (no network; stdio test spawns build/index.js)
./test-enhanced.sh   # Enhanced test suite with multiple tool tests

Publishing and Versioning

npm run version:patch    # Bump patch version and push tags
npm run version:minor    # Bump minor version and push tags
npm run version:major    # Bump major version and push tags
npm run release:dry      # Test publish without actually publishing
npm run release:manual   # Build and publish to npm
npm run release:check    # Check current published version

CI/CD

npm run cicd:setup   # Setup GitHub Actions for auto-release
npm run cicd:check   # Check CI/CD configuration status

Architecture

Core Components

Server Entry Point (src/index.ts):

• SpringBootMCPServerAdvanced class orchestrates the entire MCP server
• Uses MCP SDK's Server class; createServer() builds a fresh Server bound to the shared service singletons (once for stdio, once per request for HTTP). Stdio is the default transport, Streamable HTTP is opt-in
• Handles 17 tools, routed to four collaborators: docsService (8), advancedService (6), initializrService (2) and the shared cache (1)

Services Architecture:

• SpringBootDocsServiceOptimized (src/services/springboot-docs-optimized.ts): the 8 core documentation tools (search_spring_docs, search_spring_projects, get_spring_project, get_all_spring_guides, get_spring_guide, get_spring_reference, search_spring_concepts, get_migration_guide)
• AdvancedFeaturesService (src/services/advanced-features.ts): the 6 advanced tools (search_spring_ecosystem, get_spring_tutorial, compare_spring_versions, get_release_notes, get_spring_best_practices, diagnose_spring_issues)
• InitializrService (src/services/initializr.ts): the 2 Initializr tools (get_spring_initializr, find_spring_dependency)
• spring_cache_stats is answered directly by CacheService.statsReport() from src/index.ts
• CacheService (src/services/cache.ts): In-memory caching with TTL (30min default, 24h for stable content), one instance shared by all services