{"id":29492630,"url":"https://github.com/kaifcoder/spring-demo-mcp-server-sse","last_synced_at":"2026-05-19T06:04:45.225Z","repository":{"id":304773562,"uuid":"1019729662","full_name":"kaifcoder/spring-demo-mcp-server-sse","owner":"kaifcoder","description":"A Spring Boot demo project for implementing Server-Sent Events (SSE) with an MCP (Message Control Protocol) server. Explore real-time data streaming and event-driven architecture in Java using this hands-on example.","archived":false,"fork":false,"pushed_at":"2025-07-15T06:09:33.000Z","size":16,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-15T10:00:01.278Z","etag":null,"topics":["java","llm","mcp-server","spring-ai","spring-ai-mcp","spring-boot"],"latest_commit_sha":null,"homepage":"https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaifcoder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-14T19:25:37.000Z","updated_at":"2025-07-15T06:22:00.000Z","dependencies_parsed_at":"2025-07-15T10:00:03.077Z","dependency_job_id":null,"html_url":"https://github.com/kaifcoder/spring-demo-mcp-server-sse","commit_stats":null,"previous_names":["kaifcoder/spring-demo-mcp-server-sse"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kaifcoder/spring-demo-mcp-server-sse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fspring-demo-mcp-server-sse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fspring-demo-mcp-server-sse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fspring-demo-mcp-server-sse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fspring-demo-mcp-server-sse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaifcoder","download_url":"https://codeload.github.com/kaifcoder/spring-demo-mcp-server-sse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaifcoder%2Fspring-demo-mcp-server-sse/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265443230,"owners_count":23766370,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","llm","mcp-server","spring-ai","spring-ai-mcp","spring-boot"],"created_at":"2025-07-15T15:28:02.760Z","updated_at":"2026-05-19T06:04:45.147Z","avatar_url":"https://github.com/kaifcoder.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Spring Boot Example with User Service\n\nThis project demonstrates how to build a simple Spring Boot API and expose it as both REST endpoints and Model Context Protocol (MCP) tools using Spring Boot and Spring AI MCP Server. The app now includes a `UserService` that is exposed as an MCP tool.\n\n---\n\n## Table of Contents\n- [Features](#features)\n- [Requirements](#requirements)\n- [Setup](#setup)\n- [Running the Application](#running-the-application)\n- [REST API Usage](#rest-api-usage)\n- [MCP Server Usage (SSE + JSON-RPC)](#mcp-server-usage-sse--json-rpc)\n- [Testing](#testing)\n- [Development Notes](#development-notes)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## Features\n- UserService tool: get user details by user ID (REST and MCP)\n- REST API endpoint for user details\n- MCP server exposes user service as AI tool (usable by VS Code Copilot, etc.)\n- Full test coverage with integration tests\n\n---\n\n## Requirements\n- Java 17+\n- Maven 3.8+\n- VS Code (optional, for MCP client testing)\n- [REST Client extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) (optional, for `.http` files)\n\n---\n\n## Setup\n1. **Clone the repository:**\n   ```sh\n   git clone \u003cyour-repo-url\u003e\n   cd mcpdemo\n   ```\n2. **Configure Git (optional):**\n   ```sh\n   git config user.name \"\u003cyour-username\u003e\"\n   git config user.email \"\u003cyour-email\u003e\"\n   ```\n3. **Build the project:**\n   ```sh\n   ./mvnw clean install\n   ```\n\n---\n\n## Running the Application\nStart the Spring Boot application:\n```sh\n./mvnw spring-boot:run\n```\nThe server will start on [http://localhost:8080](http://localhost:8080).\n\n---\n\n## REST API Usage\nYou can test the user endpoint using curl, Postman, or the provided `.http` file.\n\n### UserService Example request:\n- **Get user details:**\n  ```http\n  GET http://localhost:8080/api/users/123\n  ```\n  Response:\n  ```json\n  \"User: 123, Name: John Doe\"\n  ```\n\n---\n\n## MCP Server Usage (SSE + JSON-RPC)\nThe MCP server uses Server-Sent Events (SSE) for session-based communication and JSON-RPC over HTTP for sending messages. This allows you to receive asynchronous responses in a browser or SSE client while sending requests via POST.\n\n### 1. Create a session using the SSE endpoint\nOpen your browser and navigate to:\n```\nhttp://localhost:8080/mcp/sse\n```\nA new session will be created and you will receive a response like:\n```\nid:8a09a074-ad2d-434d-a768-8e30f25a186b\nevent:endpoint\ndata:/mcp/messages?sessionId=8a09a074-ad2d-434d-a768-8e30f25a186b\n```\n- The `id` is your session ID.\n- The `data` field gives you the correct messages endpoint for this session.\n\n### 2. Send JSON-RPC messages using the messages endpoint\nUse a tool like Bruno, Postman, or curl to send POST requests to:\n```\nhttp://localhost:8080/mcp/messages?sessionId=\u003cyour-session-id\u003e\n```\nwith a JSON body. For example, to initialize:\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 0,\n  \"method\": \"initialize\",\n  \"params\": {\n    \"protocolVersion\": \"2024-11-05\",\n    \"capabilities\": {},\n    \"clientInfo\": {\n      \"name\": \"warp\",\n      \"version\": \"1.0.0\"\n    }\n  }\n}\n```\n\nThen send:\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"notifications/initialized\"\n}\n```\n\nYou can now send tool/list or tool/invoke requests as shown below. All responses will appear in the browser window (SSE session) you opened in step 1.\n\n#### Example: List available tools\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": \"2\",\n  \"method\": \"tools/list\",\n  \"params\": {}\n}\n```\n\n#### Example: Invoke a tool\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": \"3\",\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"getUserDetailsMcp\",\n    \"arguments\": {\n      \"userId\": \"123\"\n    }\n  }\n}\n```\n\n#### Example response (will appear in SSE session)\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": \"3\",\n  \"result\": \"User: 123, Name: John Doe\"\n}\n```\n\n---\n\n## VS Code Integration\n1. Open VS Code and install an MCP-compatible extension (e.g., Copilot Chat).\n2. Set the MCP server URL to `http://localhost:8080/mcp/sse` in the extension settings.\n3. Use the extension's chat or tool features to call your user tool.\n\n---\n\n## Testing\nRun all tests with:\n```sh\n./mvnw test\n```\nAll endpoints and MCP tools are covered by integration tests.\n\n---\n\n## Development Notes\n- User logic is in `UserService`.\n- REST endpoint is in `UserController`.\n- MCP tool registration is in `McpConfig`.\n- MCP server configuration is in `src/main/resources/application.yaml`.\n\n---\n\n## Troubleshooting\n- **SessionId error:** Always include a `sessionId` in MCP tool/completion requests.\n- **Tool not visible in VS Code:** Ensure the MCP server is running and the extension is pointed to the correct URL.\n- **Port conflicts:** Change the port in `application.yaml` if needed.\n- **Logs:** Enable TRACE logging in `application.yaml` for detailed MCP server logs.\n\n---\n\n## License\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaifcoder%2Fspring-demo-mcp-server-sse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaifcoder%2Fspring-demo-mcp-server-sse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaifcoder%2Fspring-demo-mcp-server-sse/lists"}