MCP Servers

Discover Awesome MCP Servers

Extend your agent with 12,344 capabilities via MCP servers.

All12,344

ModelContextProtocol (MCP) Java SDK v0.8.0 Specification

Okay, here's a breakdown of instructions for an AI on how to create a Java-based MCP (Minecraft Coder Pack) server and client. This is a complex task, so the instructions are broken down into manageable steps. The AI will need to understand Java, networking concepts (sockets, TCP), and the basics of Minecraft's internal structure (though we'll abstract away the really complex parts). **High-Level Goal:** The AI should create a simple Java application consisting of two parts: 1. **MCP Server:** A server application that listens for connections from MCP clients. It will receive commands from the client, process them (in a very basic way), and send responses back. For simplicity, the server will primarily focus on handling commands related to Minecraft block and item IDs. 2. **MCP Client:** A client application that connects to the MCP server, sends commands (e.g., "get block ID for dirt", "get item name for 260"), and displays the server's responses. **Phase 1: Project Setup and Basic Networking (Foundation)** 1. **Project Creation:** * Create a new Java project in a suitable IDE (IntelliJ IDEA, Eclipse, etc.). * Create two main packages: `server` and `client`. * Within each package, create a main class: `server.MCPServer` and `client.MCPClient`. 2. **Basic Server Socket Setup (server.MCPServer):** * **Import necessary classes:** `java.net.ServerSocket`, `java.net.Socket`, `java.io.BufferedReader`, `java.io.PrintWriter`, `java.io.InputStreamReader`. * **Create a `ServerSocket`:** The server should listen on a specific port (e.g., 12345). Handle `IOException` appropriately (try-catch). * **Accept Connections:** Use `serverSocket.accept()` to listen for incoming client connections. This will return a `Socket` object representing the connection to the client. * **Input/Output Streams:** For each connected client: * Create a `BufferedReader` to read data from the client (using `InputStreamReader` wrapped around the `Socket`'s input stream). * Create a `PrintWriter` to send data back to the client (using the `Socket`'s output stream). Set `autoFlush` to `true` for immediate sending. * **Basic Echo:** For now, the server should simply read a line of text from the client and send it back (echo). This verifies basic connectivity. * **Multi-threading (Important):** The server needs to handle multiple clients concurrently. Create a new `Thread` for each client connection. The `Runnable` for the thread should contain the input/output stream handling and the echo logic. This prevents one client from blocking the entire server. * **Error Handling:** Implement `try-catch` blocks to handle potential `IOExceptions` during socket operations. Log errors to the console. * **Resource Cleanup:** Ensure that sockets, input streams, and output streams are closed properly in a `finally` block to prevent resource leaks. 3. **Basic Client Socket Setup (client.MCPClient):** * **Import necessary classes:** `java.net.Socket`, `java.io.BufferedReader`, `java.io.PrintWriter`, `java.io.InputStreamReader`. * **Create a `Socket`:** Connect to the server's IP address and port (e.g., "localhost", 12345). Handle `IOException`. * **Input/Output Streams:** Similar to the server, create a `BufferedReader` and `PrintWriter` for communication. * **Send a Message:** Send a simple message to the server (e.g., "Hello from the client!"). * **Receive Response:** Read the server's response and print it to the console. * **Resource Cleanup:** Close the socket, input stream, and output stream in a `finally` block. 4. **Testing:** * Run the server. * Run the client. * Verify that the client connects to the server, sends a message, and receives the echoed response. **Phase 2: Command Handling and Data (Core Functionality)** 1. **Command Protocol:** * Define a simple command protocol. Commands will be strings. Examples: * `GET_BLOCK_ID <block_name>` (e.g., `GET_BLOCK_ID dirt`) * `GET_ITEM_NAME <item_id>` (e.g., `GET_ITEM_NAME 260`) * `LIST_BLOCKS` (Lists all known blocks) * `LIST_ITEMS` (Lists all known items) * `EXIT` (Client disconnects) 2. **Server-Side Command Parsing (server.MCPServer):** * In the server's client-handling thread, read the command from the client. * Use `String.split()` or regular expressions to parse the command and its arguments. * Implement a `switch` statement or `if-else` chain to handle different commands. 3. **Data Storage (Server-Side):** * Create a simple data structure to store block and item information. A `HashMap` is suitable: * `HashMap<String, Integer> blockNameToId`: Maps block names (String) to IDs (Integer). * `HashMap<Integer, String> itemIdToName`: Maps item IDs (Integer) to names (String). * **Populate with Sample Data:** Add a few entries to the `HashMap`s for testing. Example: * `blockNameToId.put("dirt", 3);` * `blockNameToId.put("stone", 1);` * `itemIdToName.put(260, "apple");` * `itemIdToName.put(276, "diamond_sword");` 4. **Command Implementation (Server-Side):** * **`GET_BLOCK_ID <block_name>`:** * Look up the block name in `blockNameToId`. * If found, send the ID back to the client. * If not found, send an error message (e.g., "Block not found"). * **`GET_ITEM_NAME <item_id>`:** * Parse the item ID as an integer. * Look up the ID in `itemIdToName`. * If found, send the name back to the client. * If not found, send an error message (e.g., "Item not found"). * **`LIST_BLOCKS`:** * Iterate through the `blockNameToId` map and send each block name and ID to the client, separated by a delimiter (e.g., "dirt:3\nstone:1\n"). * **`LIST_ITEMS`:** * Iterate through the `itemIdToName` map and send each item ID and name to the client, separated by a delimiter (e.g., "260:apple\n276:diamond_sword\n"). * **`EXIT`:** * Close the client socket and terminate the client-handling thread. Send a confirmation message to the client before closing. 5. **Client-Side Command Input and Output (client.MCPClient):** * Prompt the user to enter a command. * Send the command to the server. * Read the server's response and display it to the user. * Implement a loop that continues until the user enters the `EXIT` command. 6. **Testing:** * Run the server. * Run the client. * Test each command to ensure it works correctly. Test error cases (e.g., requesting a non-existent block). **Phase 3: Refinement and Error Handling (Polishing)** 1. **Error Handling:** * **Server-Side:** Add more robust error handling to the server. Catch potential `NumberFormatExceptions` when parsing item IDs. Log errors to a file or the console. Send informative error messages to the client. * **Client-Side:** Handle potential `IOExceptions` when reading from or writing to the socket. Display user-friendly error messages. 2. **Input Validation:** * **Server-Side:** Validate the input from the client to prevent potential security vulnerabilities (e.g., prevent command injection). Sanitize input before using it in lookups. * **Client-Side:** Provide basic input validation to the user (e.g., ensure that the item ID is a number). 3. **Code Style and Readability:** * Use meaningful variable names. * Add comments to explain the code. * Format the code consistently. * Break down long methods into smaller, more manageable methods. 4. **Configuration:** * Allow the server port to be configured via a command-line argument or a configuration file. * Allow the client to specify the server IP address and port via command-line arguments. 5. **Logging:** * Implement basic logging to record server activity and errors. Use a logging framework like `java.util.logging` or Log4j. **Example Code Snippets (Illustrative - Not Complete):** **Server (Simplified):** ```java // Inside the client-handling thread's Runnable String command = reader.readLine(); if (command != null) { String[] parts = command.split(" "); String action = parts[0]; switch (action) { case "GET_BLOCK_ID": if (parts.length > 1) { String blockName = parts[1]; Integer blockId = blockNameToId.get(blockName); if (blockId != null) { writer.println("Block ID: " + blockId); } else { writer.println("Block not found."); } } else { writer.println("Invalid command format."); } break; case "EXIT": writer.println("Goodbye!"); socket.close(); return; // Exit the thread's run() method default: writer.println("Unknown command."); } } ``` **Client (Simplified):** ```java Scanner scanner = new Scanner(System.in); String command; while (true) { System.out.print("Enter command: "); command = scanner.nextLine(); writer.println(command); writer.flush(); // Ensure the command is sent immediately String response = reader.readLine(); System.out.println("Server response: " + response); if (command.equals("EXIT")) { break; } } ``` **Important Considerations for the AI:** * **Security:** This is a simplified example. In a real-world application, security would be a major concern. The AI should be aware of potential vulnerabilities (e.g., command injection, denial-of-service attacks) and take steps to mitigate them. However, for this exercise, focus on the core functionality first. * **Scalability:** This example is not designed for high scalability. For a large number of clients, more advanced techniques (e.g., asynchronous I/O, thread pools) would be necessary. * **Minecraft Data:** The AI will need access to a data source for Minecraft block and item IDs. This could be a simple text file, a JSON file, or a database. For this exercise, a hardcoded `HashMap` is sufficient for testing. The AI should be able to load data from a file if instructed. * **Error Handling:** Robust error handling is crucial. The AI should anticipate potential errors and handle them gracefully. * **Modularity:** The AI should strive to create modular code that is easy to understand and maintain. **AI Task Breakdown:** The AI should perform the following tasks: 1. **Code Generation:** Generate the Java code for the server and client applications, following the instructions above. 2. **Data Population:** Populate the `HashMap`s with sample Minecraft block and item data. 3. **Testing:** Provide instructions on how to test the application. 4. **Documentation:** Generate basic documentation for the code. This is a substantial project. Start with Phase 1 and get the basic networking working before moving on to Phase 2 and Phase 3. Good luck!