spring-demo -sse

This MCP server demonstrates exposing a Spring Boot application as both a REST API and an MCP tool. The UserService is registered as an MCP tool so that clients such as VS Code Copilot can discover and invoke it through the MCP framework using SSE for sessions and JSON-RPC for tool calls. You can also use the REST endpoints to fetch user details, while the MCP interface provides a language-model-friendly way to query the same data via tools like getUserDetailsMcp.

To use the MCP server, first ensure the server is running and accessible at the configured port (default 8080). Create an SSE session by opening the /mcp/sse endpoint, then send JSON-RPC messages to /mcp/messages?sessionId=<your-session-id> to initialize, list tools, and invoke the getUserDetailsMcp tool with appropriate arguments (e.g., a userId). The server will return results asynchronously through the SSE channel as JSON-RPC responses.

Prerequisites:

• Java 17+ with JDK installed
• Maven 3.8+ (wrapper available as mvnw)
• Docker (optional, if using the provided docker-based run command)

1. Clone the repository and navigate to the project directory:

git clone <your-repo-url>
cd mcpdemo

2. Build the project (uses the Maven wrapper):

./mvnw clean install

3. Run the application (local run, via Maven):

./mvnw spring-boot:run

The application starts on http://localhost:8080 by default. If you prefer Docker, you can run the prebuilt image (see mcp_config for the exact image) and expose port 8080 as needed:

docker run -p 8080:8080 kaifcoder/spring-demo-mcp-server-sse

4. Verify REST endpoints (optional):

curl http://localhost:8080/api/users/123

Notes and tips:

• The MCP server exposes the UserService as an MCP tool. Use the SSE endpoint at /mcp/sse to start a session, then send JSON-RPC requests to /mcp/messages?sessionId=<session-id> to initialize, list tools (tools/list), and invoke tools (tools/call).
• Ensure the MCP server port does not conflict with other services. If needed, update application.yaml to change the server.port.
• For debugging MCP messages, enable TRACE logging in application.yaml.
• If you encounter a “Tool not visible” error in your IDE, confirm the server is running and the your client URL matches http://localhost:8080/mcp/sse.
• The REST API and MCP tools operate against the same UserService data source; prefer the MCP tool for integration with LM/AI copilots, and use REST for quick manual checks.