{"id":31287718,"url":"https://github.com/generalsparsh/mcp-spring-boot-client_v2","last_synced_at":"2026-04-29T22:38:04.530Z","repository":{"id":315803575,"uuid":"1060879811","full_name":"GeneralSparsh/mcp-spring-boot-client_v2","owner":"GeneralSparsh","description":"Spring Boot MCP client with REST endpoints to connect servers, list tools, and call JSON‑RPC methods.  Java MCP client: discover tools, read resources, and invoke tools over HTTP with a clean REST API.  Production‑ready MCP client in Spring Boot (HTTP + JSON‑RPC) with tool discovery and invocation.","archived":false,"fork":false,"pushed_at":"2025-09-20T19:37:25.000Z","size":26755,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-20T21:22:40.741Z","etag":null,"topics":["java","maven","mcp","model-context-protocol","rest-api","spring-boot","testing","webflux"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GeneralSparsh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-20T19:27:12.000Z","updated_at":"2025-09-20T19:37:29.000Z","dependencies_parsed_at":"2025-09-20T21:22:44.606Z","dependency_job_id":"75488c39-1f98-4e59-86d4-33428f9a6a85","html_url":"https://github.com/GeneralSparsh/mcp-spring-boot-client_v2","commit_stats":null,"previous_names":["generalsparsh/mcp-spring-boot-client_v2"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/GeneralSparsh/mcp-spring-boot-client_v2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeneralSparsh%2Fmcp-spring-boot-client_v2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeneralSparsh%2Fmcp-spring-boot-client_v2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeneralSparsh%2Fmcp-spring-boot-client_v2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeneralSparsh%2Fmcp-spring-boot-client_v2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GeneralSparsh","download_url":"https://codeload.github.com/GeneralSparsh/mcp-spring-boot-client_v2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeneralSparsh%2Fmcp-spring-boot-client_v2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276737524,"owners_count":25695700,"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","status":"online","status_checked_at":"2025-09-24T02:00:09.776Z","response_time":97,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","maven","mcp","model-context-protocol","rest-api","spring-boot","testing","webflux"],"created_at":"2025-09-24T11:04:23.590Z","updated_at":"2025-09-24T11:05:07.331Z","avatar_url":"https://github.com/GeneralSparsh.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Spring Boot Client\n\nA comprehensive Model Context Protocol (MCP) client implementation using Spring Boot and Maven.\n\n## Overview\n\nThis project demonstrates the ability to ingest MCP server URLs and call any API exposed by those servers using the Model Context Protocol. The implementation is designed to be generic and work with any MCP-compliant server.\n\n## Features\n\n- **Dynamic MCP Server Connection**: Connect to any MCP server by providing its URL\n- **Generic API Calling**: Call any tool or API exposed by connected MCP servers\n- **Multiple Transport Support**: HTTP and STDIO transport mechanisms\n- **RESTful API**: Complete REST API for external integration\n- **Comprehensive Testing**: Unit tests covering all major functionality\n- **Asynchronous Operations**: Non-blocking operations for better performance\n- **Configuration Management**: Flexible configuration for multiple servers\n- **Error Handling**: Robust error handling and logging\n\n## Architecture\n\nThe project follows a layered architecture:\n\n```\n├── Controller Layer (REST API)\n├── Service Layer (Business Logic)\n├── Model Layer (Data Transfer Objects)\n├── Configuration Layer (Application Settings)\n└── Transport Layer (MCP Communication)\n```\n\n## Project Structure\n\n```\nmcp-spring-boot-client/\n├── src/\n│   ├── main/\n│   │   ├── java/com/interview/mcp/\n│   │   │   ├── config/\n│   │   │   │   └── McpServerProperties.java\n│   │   │   ├── controller/\n│   │   │   │   └── McpClientController.java\n|   |   |   ├──schema/\n│   │   │   │   ├── McpSchema.java\n│   │   │   ├── model/\n│   │   │   │   ├── McpApiCallResult.java\n│   │   │   │   ├── McpConnectionResult.java\n│   │   │   │   ├── McpServerInfo.java\n│   │   │   │   └── McpToolInfo.java\n│   │   │   ├── service/\n│   │   │   │   ├── HttpMcpServerConnection.java\n│   │   │   │   ├── McpClientService.java\n│   │   │   │   └── McpServerConnection.java\n│   │   │   └── McpClientApplication.java\n│   │   └── resources/\n│   │       └── application.yml\n│   └── test/\n│       └── java/com/interview/mcp/\n│           ├── McpClientControllerTest.java\n│           └── McpClientServiceTest.java\n├── pom.xml\n└── README.md\n```\n\n## Key Components\n\n### 1. McpClientService\nThe core service that manages MCP server connections and operations:\n- Connects to MCP servers using HTTP or STDIO transport\n- Discovers available tools and resources\n- Executes tool calls and API requests\n- Manages multiple server connections concurrently\n\n### 2. McpClientController\nREST API controller providing endpoints for:\n- `/api/mcp/connect` - Connect to new MCP servers\n- `/api/mcp/servers` - List connected servers\n- `/api/mcp/tools` - List available tools\n- `/api/mcp/tools/call` - Call specific tools\n- `/api/mcp/call` - Make generic API calls\n\n### 3. HttpMcpServerConnection\nHTTP transport implementation following MCP specification:\n- JSON-RPC 2.0 message format\n- Tool discovery and execution\n- Resource management\n- Error handling and logging\n\n## Getting Started\n\n### Prerequisites\n- Java 17 or higher\n- Maven 3.8+\n- An MCP-compliant server to connect to\n\n### Build and Run\n\n1. **Clone and build the project:**\n   ```bash\n   mvn clean package\n   ```\n\n2. **Run the application:**\n   ```bash\n   java -jar target/mcp-spring-boot-client-1.0.0.jar\n   ```\n\n3. **Access the application:**\n   - Base URL: http://localhost:8080\n   - Health check: http://localhost:8080/api/mcp/health\n\n### Configuration\n\nConfigure MCP servers in `application.yml`:\n\n```yaml\nmcp:\n  servers:\n    - name: \"example-server\"\n      url: \"http://localhost:3000\"\n      transport: HTTP\n```\n\n## API Usage Examples\n\n### 1. Connect to MCP Server\n```bash\ncurl -X POST http://localhost:8080/api/mcp/connect \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"serverUrl\": \"http://localhost:3000\",\n    \"serverName\": \"my-server\"\n  }'\n```\n\n### 2. List Available Tools\n```bash\ncurl http://localhost:8080/api/mcp/tools\n```\n\n### 3. Call a Tool\n```bash\ncurl -X POST http://localhost:8080/api/mcp/tools/call \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"serverName\": \"my-server\",\n    \"toolName\": \"calculator\",\n    \"parameters\": {\n      \"operation\": \"add\",\n      \"a\": 5,\n      \"b\": 3\n    }\n  }'\n```\n\n### 4. Make Generic API Call\n```bash\ncurl -X POST http://localhost:8080/api/mcp/call \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"serverUrl\": \"http://localhost:3000\",\n    \"method\": \"GET\",\n    \"endpoint\": \"/api/data\"\n  }'\n```\n\n## Testing\n\nRun unit tests:\n```bash\nmvn test\n```\n\nThe test suite includes:\n- Service layer tests for MCP operations\n- Controller tests for REST API endpoints\n- Integration tests for end-to-end scenarios\n\n## Model Context Protocol Compliance\n\nThis implementation follows the MCP specification:\n- JSON-RPC 2.0 message format\n- Standard MCP methods (initialize, tools/list, tools/call, etc.)\n- Proper error handling and status codes\n- Support for both HTTP and STDIO transports\n\n## Design Principles\n\n- **Generic Implementation**: Works with any MCP-compliant server\n- **Scalable Architecture**: Supports multiple concurrent server connections\n- **Extensible Design**: Easy to add new transport mechanisms\n- **Production Ready**: Comprehensive error handling and logging\n- **Testable Code**: High test coverage with unit and integration tests\n\n## Future Enhancements\n\n- WebSocket transport support\n- Server-sent events for real-time updates\n- Connection pooling and load balancing\n- Advanced authentication mechanisms\n- Monitoring and metrics integration\n\n## Author\n\nSparsh Sahu\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeneralsparsh%2Fmcp-spring-boot-client_v2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeneralsparsh%2Fmcp-spring-boot-client_v2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeneralsparsh%2Fmcp-spring-boot-client_v2/lists"}