spring-mcp-server

🚀 Spring Boot MCP Server - Complete Guide

A Model Context Protocol (MCP) server for AI-powered Spring Boot code generation using DeepSeek v3 via Ollama.

📋 Table of Contents

• Overview
• Prerequisites
• Quick Start
• Project Structure
• Available Tools
• Configuration
• Adding New Tools
• VS Code Integration
• Troubleshooting
• Version Details
• Important Commands
• Advanced Usage
• FAQ

---

Overview

This MCP server enables AI assistants (like Claude via Continue/Cline) to generate Spring Boot code directly into your project. It uses:

• MCP SDK v1.25.1 - Model Context Protocol for AI tool integration
• Ollama - Local LLM runtime
• DeepSeek R1/Coder - AI model for code generation
• Node.js - Server runtime

What It Does

✅ Generate REST controllers with complete CRUD operations
✅ Create service interfaces and implementations
✅ Generate JPA entities with proper annotations
✅ Create Spring Data repositories
✅ Verify project structure
✅ All code follows Spring Boot best practices

---

Prerequisites

Required Software

Software	Version	Installation
Node.js	≥ 18.0.0	Download
npm	≥ 9.0.0	(Comes with Node.js)
Ollama	Latest	Download
VS Code	Latest	Download
Continue Extension	Latest	Install from VS Code marketplace

Verify Prerequisites

# Check Node.js version (should be >= 18)
node --version

# Check npm version
npm --version

# Check Ollama installation
ollama --version

# Check Ollama is running
curl http://localhost:11434/api/tags

---

Quick Start

1. Install Ollama and Download Model

# Install Ollama (if not already installed)
# macOS/Linux:
curl -fsSL https://ollama.com/install.sh | sh

# Download DeepSeek model (choose one):

# Option A: DeepSeek R1 (recommended, ~10GB)
ollama pull deepseek-r1:latest

# Option B: DeepSeek Coder (smaller, ~4GB)
ollama pull deepseek-coder:6.7b

# Option C: CodeLlama (smallest, ~3GB, for testing)
ollama pull codellama:7b

# Verify model is installed
ollama list

2. Start Ollama Server

# Start Ollama (keep this running)
ollama serve

# Or run in background
nohup ollama serve > /dev/null 2>&1 &

3. Set Up MCP Server

# Clone or create project directory
mkdir -p ~/projects/spring-mcp-server
cd ~/projects/spring-mcp-server

# Create project structure
mkdir -p config utils tools

# Create package.json
cat > package.json << 'EOF'
{
  "name": "springboot-mcp-server",
  "version": "1.0.0",
  "description": "MCP Server for Spring Boot code generation",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "node test-sdk.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.25.1",
    "node-fetch": "^3.3.2"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}
EOF

# Install dependencies
npm install

4. Create Configuration Files

Copy the following files from the artifacts:

• config/constants.js - Configuration
• utils/ollama.js - Ollama integration
• utils/file-utils.js - File operations
• utils/validators.js - Input validation
• tools/controller-tools.js - Controller generation
• tools/service-tools.js - Service generation
• tools/entity-tools.js - Entity generation
• tools/repository-tools.js - Repository generation
• tools/project-tools.js - Project utilities
• tools/index.js - Tool registry
• index.js - Main entry point

5. Set Up Spring Boot Project

# Create Spring Boot project directory
mkdir -p ~/projects/spring-boot-project

# Create basic structure
cd ~/projects/spring-boot-project
mkdir -p src/main/java/com/example/demo
mkdir -p src/main/resources
mkdir -p src/test/java

# Set environment variable
export SPRING_PROJECT_PATH=~/projects/spring-boot-project

6. Test MCP Server

cd ~/projects/spring-mcp-server

# Test server starts
node index.js

# Expected output:
# Spring Boot MCP Server running on stdio
# SDK Version: 1.25.1
# Tools available: 5

# Press Ctrl+C to stop

7. Configure VS Code

Create/edit VS Code settings:

# Open VS Code settings
code ~/Library/Application\ Support/Code/User/settings.json

Add MCP server configuration:

{
  "continue.mcpServers": {
    "springboot-codegen": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "/absolute/path/to/spring-mcp-server",
      "env": {
        "SPRING_PROJECT_PATH": "/absolute/path/to/spring-boot-project"
      }
    }
  }
}

Important: Use absolute paths, not relative paths!

8. Test in VS Code

1. Restart VS Code completely (Quit and reopen)
2. Open Continue extension (click Cline/Continue icon)
3. Type: List available MCP tools
4. Should see: create_rest_controller, create_service, create_entity, create_repository, verify_project_structure
5. Test generation: Create a User entity with fields: name:String, email:String, age:Integer

---

Project Structure

spring-mcp-server/
├── package.json              # Project configuration
├── index.js                  # Main entry point
├── config/
│   └── constants.js         # Configuration constants
├── utils/
│   ├── ollama.js            # Ollama API integration
│   ├── file-utils.js        # File operations
│   └── validators.js        # Input validation
└── tools/
    ├── index.js             # Tool registry
    ├── controller-tools.js  # REST controller generation
    ├── service-tools.js     # Service generation
    ├── entity-tools.js      # Entity generation
    ├── repository-tools.js  # Repository generation
    └── project-tools.js     # Project utilities

spring-boot-project/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/
    │   │   └── com/example/demo/
    │   │       ├── DemoApplication.java
    │   │       ├── controller/
    │   │       ├── service/
    │   │       ├── entity/
    │   │       └── repository/
    │   └── resources/
    │       └── application.properties
    └── test/
        └── java/

---

Available Tools

1. create_rest_controller

Generate a Spring Boot REST controller with CRUD operations.

Parameters:

• entityName (required) - Entity name (e.g., "User")
• fields (required) - Fields with types (e.g., "name:String,email:String,age:Integer")
• packageName - Base package (default: "com.example.demo")
• controllerName - Controller class name
• basePath - API base path (default: "/api/{entity}s")
• endpoints - Which endpoints to generate (default: "getAll,getById,create,update,delete")
• serviceClass - Service to inject
• includeValidation - Add @Valid annotations (default: true)
• includeSecurity - Add security annotations (default: false)
• includeExceptionHandling - Add error handling (default: true)

Example:

Create a REST controller for User entity with fields: name:String, email:String, age:Integer

2. create_service

Generate service interface and implementation.

Parameters:

• serviceName (required) - Service name (must end with "Service")
• implName - Implementation name (default: "{serviceName}Impl")
• servicePackage - Interface package (default: "com.example.demo.service")
• implPackage - Implementation package (default: "{servicePackage}.impl")
• injectionStyle - Injection type: constructor/field/setter (default: "constructor")
• transactional - Enable @Transactional (default: true)
• repositoryInterface - Repository to inject
• methods - JSON array of method definitions
• Plus many more configuration options (see service-tools.js)

Example:

Create a UserService with repository: UserRepository

3. create_entity

Generate JPA entity class.

Parameters:

• entityName (required) - Entity name
• fields (required) - Entity fields
• packageName - Base package
• tableName - Database table name
• includeAuditFields - Add created/updated fields (default: true)
• useLombok - Use Lombok annotations (default: true)
• includeValidation - Add validation annotations (default: true)

Example:

Create a Product entity with fields: sku:String, name:String, price:Double, inStock:Boolean

4. create_repository

Generate Spring Data repository interface.

Parameters:

• entityName (required) - Entity name
• packageName - Base package
• idType - ID field type (default: "Long")
• includeCustomQueries - Add custom query methods (default: true)
• extendJpaRepository - Extend JpaRepository vs CrudRepository (default: true)

Example:

Create a UserRepository with custom queries

5. verify_project_structure

Verify Spring Boot project structure.

Example:

Verify the project structure

---

Configuration

Environment Variables

Set these before running the MCP server:

# Spring Boot project path (required)
export SPRING_PROJECT_PATH=/path/to/spring-boot-project

# Ollama configuration (optional)
export OLLAMA_URL=http://localhost:11434/api/generate
export OLLAMA_MODEL=deepseek-r1:latest

Config File: config/constants.js

export const CONFIG = {
  // Ollama settings
  OLLAMA_URL: process.env.OLLAMA_URL || "http://localhost:11434/api/generate",
  MODEL_NAME: process.env.OLLAMA_MODEL || "deepseek-r1:latest",
  
  // Fallback models (tried in order if primary fails)
  FALLBACK_MODELS: [
    "deepseek-r1:latest",
    "deepseek-coder-v2:16b",
    "deepseek-coder:6.7b",
    "llama3:8b",
    "codellama:7b"
  ],
  
  // Project path
  SPRING_PROJECT_PATH: process.env.SPRING_PROJECT_PATH || "./spring-boot-project",
  
  // Generation settings
  TEMPERATURE: 0.2,
  TOP_P: 0.9,
};

---

Adding New Tools

Follow these steps to add a new code generation tool.

Step 1: Create Tool Module

Create tools/your-tool.js:

/**
 * Your tool description
 */

import { callDeepSeek, extractJavaCode } from "../utils/ollama.js";
import { safeWriteFile, verifyJavaFile } from "../utils/file-utils.js";
import { validateClassName, validatePackageName } from "../utils/validators.js";

export async function createYourThing(args) {
  // 1. Extract parameters with defaults
  const {
    requiredParam,
    optionalParam = "default_value",
  } = args;

  // 2. Validate required parameters
  if (!requiredParam) {
    throw new Error("requiredParam is required");
  }

  // 3. Validate formats
  validateClassName(requiredParam);

  // 4. Build AI prompt
  const prompt = `Generate [WHAT YOU WANT] with:
  - Parameter: ${requiredParam}
  - Other: ${optionalParam}
  
  Requirements:
  - [List requirements]
  
  Return ONLY the Java code.`;

  // 5. Generate code
  const code = await callDeepSeek(prompt);
  const cleanCode = extractJavaCode(code);

  // 6. Save file
  const filePath = await safeWriteFile(
    `subdirectory/ClassName.java`,
    cleanCode,
    packageName
  );

  // 7. Verify
  const verification = await verifyJavaFile(filePath);

  // 8. Return response
  return {
    content: [
      {
        type: "text",
        text: `✅ Created successfully!\n\n` +
              `📁 File: ${filePath}\n\n` +
              `📝 Code:\n\`\`\`java\n${cleanCode}\n\`\`\`\n\n` +
              `${verification}`,
      },
    ],
  };
}

Step 2: Add Tool Schema

Edit tools/index.js and add to TOOL_SCHEMAS:

export const TOOL_SCHEMAS = {
  // ... existing tools ...
  
  your_tool_name: {
    name: "your_tool_name",
    description: "What this tool does",
    inputSchema: {
      type: "object",
      properties: {
        requiredParam: {
          type: "string",
          description: "What this parameter does",
        },
        optionalParam: {
          type: "string",
          description: "Optional parameter",
          default: "default_value",
        },
      },
      required: ["requiredParam"],
    },
  },
};

Step 3: Register Handler

Edit index.js and add:

// Import your tool
import { createYourThing } from "./tools/your-tool.js";

// Add to switch statement
switch (name) {
  case "your_tool_name":
    return await createYourThing(args);
  // ... other cases ...
}

Step 4: Test

# Restart server
node index.js

# Restart VS Code

# Test in Continue
"List available MCP tools"
# Should show your new tool

"Use your_tool_name with requiredParam: TestValue"

---

VS Code Integration

Continue Extension Setup

1. Install Continue

   • Open VS Code
   • Go to Extensions (Cmd+Shift+X)
   • Search for "Continue"
   • Install

2. Configure MCP Server

   Open settings: Cmd+Shift+P → "Preferences: Open User Settings (JSON)"

   Add:

   {
     "continue.mcpServers": {
       "springboot-codegen": {
         "command": "node",
         "args": ["index.js"],
         "cwd": "/Users/yourname/projects/spring-mcp-server",
         "env": {
           "SPRING_PROJECT_PATH": "/Users/yourname/projects/spring-boot-project"
         }
       }
     }
   }
   

3. Restart VS Code

   • Quit completely (Cmd+Q)
   • Reopen VS Code

4. Test Connection

   • Open Continue panel
   • Type: "What MCP tools are available?"
   • Should list all 5 tools

Alternative: Cline Extension

If using Cline instead of Continue:

Create: ~/.config/cline/settings.json

{
  "mcpServers": {
    "springboot-codegen": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "/absolute/path/to/spring-mcp-server",
      "env": {
        "SPRING_PROJECT_PATH": "/absolute/path/to/spring-boot-project"
      }
    }
  }
}

---

Troubleshooting

Issue: "Command not found, transports removed"

Cause: Wrong SDK version or import paths

Fix:

# Check SDK version
npm list @modelcontextprotocol/sdk

# Should be 1.25.1 or similar

# If wrong version:
rm -rf node_modules package-lock.json
npm install

Issue: "Ollama API error: Not Found"

Cause: Ollama not running or model not installed

Fix:

# 1. Check Ollama is running
curl http://localhost:11434/api/tags

# 2. Start Ollama if needed
ollama serve

# 3. Check installed models
ollama list

# 4. Install model if missing
ollama pull deepseek-r1:latest

# 5. Test model
curl http://localhost:11434/api/generate -d '{
  "model": "deepseek-r1:latest",
  "prompt": "test",
  "stream": false
}'

Issue: "Cannot find module"

Cause: Missing dependencies or wrong file structure

Fix:

# Reinstall dependencies
npm install

# Check file structure
ls -la config/ utils/ tools/

# Ensure all files exist:
# - config/constants.js
# - utils/ollama.js
# - utils/file-utils.js
# - utils/validators.js
# - tools/*.js
# - index.js

Issue: "Path traversal blocked"

Cause: File trying to be written outside project

Fix:

# Check SPRING_PROJECT_PATH is set correctly
echo $SPRING_PROJECT_PATH

# Should be absolute path to your Spring Boot project
export SPRING_PROJECT_PATH=/full/path/to/spring-boot-project

Issue: MCP Tools Not Showing in VS Code

Cause: VS Code didn't reload MCP server config

Fix:

1. Completely quit VS Code (Cmd+Q on Mac)
2. Verify MCP server starts: node index.js
3. Check VS Code settings have correct paths
4. Reopen VS Code
5. Check Continue logs: View → Output → Select "Continue"

Issue: "File already exists"

Cause: Tool doesn't overwrite files for safety

Fix:

# Either delete existing file manually
rm path/to/ExistingFile.java

# Or rename the entity/controller in your request
"Create a User2Controller instead"

Diagnostic Commands

# Check everything is working
cd ~/projects/spring-mcp-server

# 1. Node version
node --version  # Should be >= 18

# 2. Dependencies installed
npm list

# 3. Ollama running
curl http://localhost:11434/api/tags

# 4. Model installed
ollama list | grep deepseek

# 5. MCP server starts
node index.js  # Should show "running on stdio"

# 6. Test imports
node -e "import('@modelcontextprotocol/sdk/server/index.js').then(() => console.log('OK'))"

---

Version Details

Software Versions

Component	Version	Notes
Node.js	≥ 18.0.0	ES modules required
npm	≥ 9.0.0	Package management
@modelcontextprotocol/sdk	1.25.1	MCP protocol
node-fetch	3.3.2	HTTP requests
Ollama	Latest	LLM runtime

Ollama Models

Model	Size	Speed	Quality	Recommended For
deepseek-r1:latest	~10GB	Slow	Excellent	Production
deepseek-coder-v2:16b	~10GB	Medium	Excellent	Production
deepseek-coder:6.7b	~4GB	Fast	Good	Development
codellama:7b	~3GB	Fast	Good	Testing
llama3:8b	~4GB	Fast	Fair	Testing

Compatibility

OS	Node 18	Node 20	Node 22
macOS	✅	✅	✅
Linux	✅	✅	✅
Windows	✅	✅	⚠️ (WSL recommended)

VS Code Extensions

Extension	Version	Purpose
Continue	Latest	MCP client
Cline	Latest	Alternative MCP client

---

Important Commands

Daily Usage

# Start Ollama (keep running in background)
ollama serve

# Start MCP server (for testing)
cd ~/projects/spring-mcp-server
node index.js

# Check logs
tail -f ~/.ollama/logs/server.log

Ollama Commands

# List installed models
ollama list

# Pull a model
ollama pull deepseek-r1:latest

# Remove a model
ollama rm deepseek-r1:latest

# Check Ollama version
ollama --version

# Test model directly
ollama run deepseek-r1:latest "Write hello world in Java"

# Check running models
ollama ps

npm Commands

# Install dependencies
npm install

# Install specific version
npm install @modelcontextprotocol/sdk@1.25.1

# Clean install
rm -rf node_modules package-lock.json && npm install

# Check for updates
npm outdated

# Update dependencies
npm update

# Audit security
npm audit

# Fix vulnerabilities
npm audit fix

Development Commands

# Test server manually
node index.js

# Test specific tool
node -e "import('./tools/controller-tools.js').then(m => console.log(m))"

# Check imports
node test-sdk.js

# Watch for changes (requires nodemon)
npm install -g nodemon
nodemon index.js

Debugging Commands

# Verbose npm install
npm install --verbose

# Check which node
which node

# Check node modules
ls -la node_modules/@modelcontextprotocol/sdk/

# Test Ollama API
curl -X POST http://localhost:11434/api/generate \
  -d '{"model":"deepseek-r1:latest","prompt":"test","stream":false}'

# Check environment variables
env | grep SPRING
env | grep OLLAMA

# Test file permissions
ls -la config/ utils/ tools/

# Check disk space (for Ollama models)
df -h

Git Commands (Version Control)

# Initialize git (if not done)
cd ~/projects/spring-mcp-server
git init

# Add .gitignore
cat > .gitignore << 'EOF'
node_modules/
package-lock.json
.env
*.log
.DS_Store
EOF

# Commit initial version
git add .
git commit -m "Initial MCP server setup"

# Create backup
git tag -a v1.0.0 -m "Working version"

---

Advanced Usage

Using Different Models

# Set model via environment variable
export OLLAMA_MODEL=deepseek-coder:6.7b
node index.js

# Or edit config/constants.js
MODEL_NAME: "deepseek-coder:6.7b"

Custom Project Structure

// In config/constants.js, customize:
SPRING_PROJECT_PATH: "/path/to/your/project",

// Package structure will follow Spring Boot conventions:
// src/main/java/{packageName}/controller
// src/main/java/{packageName}/service
// src/main/java/{packageName}/entity
// src/main/java/{packageName}/repository

Running Multiple MCP Servers

{
  "continue.mcpServers": {
    "springboot-codegen": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "/path/to/spring-mcp-server",
      "env": { "SPRING_PROJECT_PATH": "/path/to/project1" }
    },
    "springboot-codegen-2": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "/path/to/spring-mcp-server",
      "env": { "SPRING_PROJECT_PATH": "/path/to/project2" }
    }
  }
}

Logging and Monitoring

// Add to index.js for detailed logging
setupToolHandlers() {
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    console.error(`[${new Date().toISOString()}] Tool called: ${request.params.name}`);
    console.error(`[${new Date().toISOString()}] Args: ${JSON.stringify(request.params.arguments)}`);
    
    // ... rest of handler
  });
}

Performance Tuning

// In config/constants.js
TEMPERATURE: 0.1,  // Lower = more deterministic
TOP_P: 0.95,       // Higher = more creative

// Use faster models for development
MODEL_NAME: "deepseek-coder:6.7b",  // Faster
// vs
MODEL_NAME: "deepseek-r1:latest",   // Better quality

---

FAQ

Q: Do I need to keep Ollama running?

A: Yes, Ollama must be running for the MCP server to generate code. Start it with ollama serve and keep it running in the background.

Q: Can I use other AI models?

A: Yes! Any model available in Ollama works. Update MODEL_NAME in config/constants.js. Models like CodeLlama, Llama3, or any coding-focused model will work.

Q: Does this work with Maven and Gradle projects?

A: Currently optimized for Maven. Gradle support can be added by creating appropriate tool modules.

Q: Can I modify generated code?

A: Yes! The MCP server generates a starting point. Always review and customize the generated code for your needs.

Q: Is my code sent to external servers?

A: No! Everything runs locally. Ollama runs on your machine, and no code is sent to external APIs.

Q: How much disk space do I need?

A: Depends on model:

• DeepSeek R1: ~10GB
• DeepSeek Coder: ~4GB
• CodeLlama: ~3GB
• Plus ~500MB for Node.js dependencies

Q: Can I use this in production?

A: The MCP server is a development tool. The generated code can be used in production after proper review and testing.

Q: What if I don't have VS Code?

A: You can use the MCP Inspector (npx @modelcontextprotocol/inspector node index.js) or any MCP-compatible client.

Q: Can multiple developers share one MCP server?

A: Each developer should run their own MCP server instance pointing to their local Spring Boot project.

Q: How do I update the MCP server?

A:

# Pull latest changes (if using git)
git pull

# Update dependencies
npm update

# Restart server
node index.js

---

Contributing

Adding New Features

1. Create feature branch
2. Add tool module in tools/
3. Update tools/index.js registry
4. Update index.js handler
5. Test thoroughly
6. Update this README
7. Submit pull request

Reporting Issues

Include:

• Node.js version (node --version)
• npm version (npm --version)
• Ollama version (ollama --version)
• MCP SDK version (npm list @modelcontextprotocol/sdk)
• Error message with full stack trace
• Steps to reproduce

---

License

MIT License - Feel free to use and modify for your projects.

---

Support

• Issues: Check the Troubleshooting section first
• Ollama Docs: https://ollama.com/docs
• MCP Docs: https://modelcontextprotocol.io
• Spring Boot: https://spring.io/projects/spring-boot

---

Credits

Built with:

• Model Context Protocol by Anthropic
• Ollama by Ollama team
• DeepSeek models
• Node.js ecosystem

---

Last Updated: December 2024
Version: 1.0.0
Maintainer: Your Name

---

Quick Reference Card

# Start everything
ollama serve                    # Terminal 1
cd ~/spring-mcp-server && node index.js  # Terminal 2 (for testing)

# Common tasks
ollama list                     # Check models
ollama pull deepseek-r1:latest # Get model
npm install                     # Install deps
node index.js                   # Test server

# In VS Code
"List MCP tools"               # See available tools
"Create User entity..."        # Generate code

# Troubleshoot
curl http://localhost:11434/api/tags  # Check Ollama
npm list @modelcontextprotocol/sdk   # Check SDK
echo $SPRING_PROJECT_PATH            # Check path

---

Ready to generate some code? Start with:

Create a User entity with fields: username:String, email:String, age:Integer

🚀 Happy coding!