mcp

This MCP server implements a Spring-based Model Context Protocol (MCP) server with a focus on managing SSE (server-sent events) sessions for model tooling. It supports custom session lifecycle handling, including an elegant session close mechanism (sessionCloseGracefully) that clients can invoke to gracefully release a session on the server. A key design detail is the use of a unique client identifier for each SSE connection (for example, /sse?clientId=xxxx) to help the server manage and potentially overwrite stale sessions when clients restart. The server also provides a configurable session timeout (sessionTimeOutSecond) to control how long inactive sessions are kept, and it includes enhancements to the WebMvcSseServerTransportProvider to ensure robust message delivery and proper session cleanup. To use it, ensure your MCP client can establish an SSE connection with a unique clientId, and invoke the sessionCloseGracefully message when the client is about to shut down or reset.

Typical workflow:

• Start the MCP server in your environment (e.g., via Docker as configured in mcp_config).
• Connect an MCP client to the server's SSE endpoint using a unique clientId parameter.
• Use the client’s MCP session to send and receive messages, including custom messages such as sessionCloseGracefully to gracefully terminate sessions.
• If the client restarts or is replaced, the server can overwrite the previous session by reusing the unique clientId, helping prevent memory leaks and stale sessions on restarts. Consider implementing periodic liveness checks if you have multiple MCP servers behind a load balancer to keep memory usage bounded.

Prerequisites:

• Java runtime (recommended: Java 17+) for building or running a Java-based MCP server.
• Docker installed on the host (if using the provided Docker run configuration).
• Optional: Maven or Gradle if you choose to build from source.

Option A: Run from Docker (recommended for quick start)

1. Ensure Docker is running on your machine.

2. Pull and run the MCP server image using the configuration in mcp_config (adjust image name if needed):

   docker run -i --env SPRING_PROFILES_ACTIVE=prod ajobs-coding-mcp-server

3. Verify the server starts and exposes the configured transport (SSE) endpoints.

Option B: Build from source (Java)

1. Clone/download the repository.

2. Ensure JDK 17+ is installed.

3. Build the project (adjust commands to your build tool if needed):

   mvn clean package

4. Run the built server jar, typically something like:

   java -jar target/mcp-server.jar --spring.config.location=classpath:/application.properties

5. Confirm the server is listening on the configured port and SSE endpoint.

Option C: Configuration before run

• If you use Docker, ensure the image name matches what your environment expects (adjust in mcp_config).
• You may override environment variables in your deployment to set sessionTimeOutSecond or other properties as needed.

Tips and common issues:

• Always provide a unique clientId for each SSE connection to enable proper session management and prevent memory leaks when clients restart.
• Consider enabling sessionTimeOutSecond to automatically purge idle sessions; tune this based on your client behavior.
• Use the sessionCloseGracefully MCP message from the client to gracefully terminate sessions before disconnecting.
• If deploying behind a load balancer with multiple MCP servers, be aware of potential memory usage. Shorter sessionTimeOutSecond and periodic pings can help keep memory bounded.
• If you encounter 404 when the server is restarting, ensure the client implements a retry mechanism that reestablishes the SSE connection with a new sessionId/clientId to bind to the new server instance.
• When modifying server transport behavior (e.g., WebMvcSseServerTransportProvider), tests should cover both fresh connections and reconnections after server restarts to validate session replacement logic.