custom

This MCP server implements the Model Context Protocol (MCP) using JSON-RPC 2.0 over a stdio-like transport and runs as a Java Spring Boot application. It exposes a set of core MCP capabilities, including an initialize handshake to negotiate server capabilities, a list of available tools, and a means to execute those tools via tools/call. Typical interactions start with an initialize request, followed by tool discovery (tools/list) and then tool execution (tools/call) where the client asks the server to perform an action (for example, an echo tool). The architecture follows the ECB pattern and uses Java 17 with Spring Boot 3.2.0, Maven, Jackson, and Lombok. When running inside the container, you can connect to the server’s stdio transport and exchange JSON-RPC 2.0 messages that describe requests, responses, and potential errors.

Usage flow (high level):

• Client initializes: the server responds with its capabilities and supported features.
• Client requests the list of available tools: tools/list, server returns tool metadata (name, description, input schema).
• Client instructs the server to execute a tool via tools/call with the tool name and inputs. The server processes the request, performs the action, and returns the result.
• Tools may include simple examples like read_file or echo. Results are returned to the client, which can forward them to the MCP client (e.g., Claude) or to an LLM for further reasoning.

This setup is designed for learning MCP concepts, tool orchestration, and JSON-RPC 2.0 sequencing in a Java environment.

Prerequisites:

• Java 17 (or compatible runtime) installed on the host or available in the container image
• Maven (for building from source) or a prebuilt Docker image
• Docker (if using the provided containerized approach)

Option A — Using Maven (build from source):

1. Ensure Java 17 and Maven are installed
2. Clone the repository and navigate to the project root
3. Build the project: mvn clean install
4. Run the application (jar): java -jar target/custom-mcp-server-1.0-SNAPSHOT.jar

Option B — Using Docker (recommended for MCP experiments):

1. Ensure Docker is installed and running
2. Build the Docker image (if a Dockerfile is provided in the project): docker build -t kayroone-custom-mcp-server:latest .
3. Run the container (interactive stdio-ready mode): docker run -i kayroone-custom-mcp-server:latest

Notes:

• If you build and run locally, you’ll typically interact with the server via its stdio transport using JSON-RPC 2.0 payloads.
• Ensure the network and I/O permissions allow the container or host process to exchange messages as defined by the MCP protocol.

Tips and notes:

• The server uses JSON-RPC 2.0 over a stdio-like transport; ensure your client can serialize and deserialize the standard request/response envelopes.
• Initialize Handshake: the client should start with an initialize request to negotiate capabilities before calling tools/list or tools/call.
• Tools: the server exposes a list of tools with their names and input schemas (e.g., echo, read_file). Use tools/list to discover them and tools/call to execute.
• If you encounter port or I/O blocking issues in Docker, verify that the container is configured to handle stdio-driven communication as expected by the MCP client integration.
• Environment variables like JAVA_OPTS or Spring profiles can be used to customize JVM settings and active configurations in containerized deployments.