Soduku Solver MCP Server

Instructions

Implementation Reference

• src/sodukusolver/server.py:207-239 (handler)

  Executes the 'add-sudoku' tool: extracts name and puzzle text from arguments, parses the puzzle using parse_sudoku_text, stores in sudoku_puzzles dict, notifies resource changes, formats and returns the grid.
  elif name == "add-sudoku": puzzle_name = arguments.get("name") puzzle_text = arguments.get("puzzle") if not puzzle_name or not puzzle_text: raise ValueError("Missing name or puzzle") try: # Parse the puzzle grid = parse_sudoku_text(puzzle_text) # Store the puzzle sudoku_puzzles[puzzle_name] = grid # Notify clients that resources have changed await server.request_context.session.send_resource_list_changed() # Return formatted grid formatted_grid = format_sudoku_grid(grid) return [ types.TextContent( type="text", text=f"Added Sudoku puzzle '{puzzle_name}':\n\n{formatted_grid}", ) ] except ValueError as e: return [ types.TextContent( type="text", text=f"Error parsing Sudoku puzzle: {str(e)}", ) ]
• src/sodukusolver/server.py:140-151 (registration)

  Registers the 'add-sudoku' tool in handle_list_tools(), providing name, description, and JSON schema for input validation (name and puzzle required).
  types.Tool( name="add-sudoku", description="Add a new Sudoku puzzle", inputSchema={ "type": "object", "properties": { "name": {"type": "string"}, "puzzle": {"type": "string", "description": "The Sudoku puzzle in text format"}, }, "required": ["name", "puzzle"], }, ),
• src/sodukusolver/server.py:143-150 (schema)

  Defines the input schema for 'add-sudoku' tool: object with 'name' (string) and 'puzzle' (string, described).
  inputSchema={ "type": "object", "properties": { "name": {"type": "string"}, "puzzle": {"type": "string", "description": "The Sudoku puzzle in text format"}, }, "required": ["name", "puzzle"], },
• src/sodukusolver/solver.py:95-173 (helper)

  Helper function to parse Sudoku puzzle text into a 9x9 grid matrix. Handles various text formats, validates dimensions and values (0-9). Used in add-sudoku handler.
  def parse_sudoku_text(text): """ Parse a Sudoku puzzle from text input. The input can be in various formats: - Space or comma-separated values (0 or . for empty cells) - Multiple lines representing rows Args: text: String containing the Sudoku puzzle Returns: list: 9x9 matrix representing the Sudoku puzzle """ # Initialize an empty 9x9 grid grid = [] # Split the input into lines lines = [line.strip() for line in text.strip().split('\n') if line.strip()] # If we have a single line, try to parse it as a flat representation if len(lines) == 1: # Replace common separators with spaces flat = lines[0].replace(',', ' ').replace(';', ' ') # Replace dots with zeros flat = flat.replace('.', '0') # Split by whitespace and filter out empty strings values = [v for v in flat.split() if v] # Check if we have enough values if len(values) != 81: raise ValueError(f"Expected 81 values for a 9x9 Sudoku, got {len(values)}") # Create the 9x9 grid for i in range(9): row = [] for j in range(9): cell = values[i * 9 + j] try: row.append(int(cell)) except ValueError: raise ValueError(f"Invalid Sudoku value: {cell}") grid.append(row) else: # Parse multiple lines for line in lines: if not line.strip(): continue # Replace dots with zeros and remove other common separators line = line.replace('.', '0').replace(',', ' ').replace(';', ' ') # Split and filter values = [v for v in line.split() if v] row = [] for cell in values: try: row.append(int(cell)) except ValueError: raise ValueError(f"Invalid Sudoku value: {cell}") if row: grid.append(row) # Validate the grid dimensions if len(grid) != 9: raise ValueError(f"Expected 9 rows for Sudoku, got {len(grid)}") for i, row in enumerate(grid): if len(row) != 9: raise ValueError(f"Expected 9 columns in row {i}, got {len(row)}") # Validate the values (0-9 only) for i in range(9): for j in range(9): if not 0 <= grid[i][j] <= 9: raise ValueError(f"Invalid value {grid[i][j]} at position ({i}, {j})") return grid
• src/sodukusolver/solver.py:175-203 (helper)

  Helper function to format 9x9 Sudoku grid as a readable string with borders. Used to display the added puzzle in the tool response.
  def format_sudoku_grid(grid): """ Format a Sudoku grid for display. Args: grid: 9x9 Sudoku grid Returns: str: Formatted string representation of the grid """ result = [] horizontal_line = "+-------+-------+-------+" for i in range(9): if i % 3 == 0: result.append(horizontal_line) row = "| " for j in range(9): row += str(grid[i][j]) + " " if (j + 1) % 3 == 0: row += "| " result.append(row) result.append(horizontal_line) return "\n".join(result)