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)