Crossword MCP Server

Instructions

Implementation Reference

• src/server.py:172-202 (handler)

  The primary handler for the MCP 'setup' tool. Decorated with @mcp.tool() for registration. Parses input grid_text and clue_text using helpers, initializes the global PuzzleState, clears candidates, and returns the loaded grid.

  @mcp.tool()
  async def setup(grid_text: str, clue_text: str) -> list[list[str]]:
      """クロスワードの盤面とカギ定義を読み込み、状態を初期化する。
  
      Args:
          grid_text (str): 行番号つきの盤面テキスト。列・行番号は全角数字で表記し、
              文字が入るマスは "？"、黒マスは "＃" で記述する。各行のマス数が一致している
              必要がある。
          clue_text (str): JSON Lines 形式のカギ定義。各行は `id`/`direction`/`row`/`col`
              /`length`/`clue` を持つ辞書で、`direction` は "across" か "down"。`row` と
              `col` は 1 起点の正整数。
  
      Returns:
          list[list[str]]: 正規化済みセル行列。各要素は "？" または "＃" のシンボル。
  
      Raises:
          ValueError: 盤面の行長不一致・未知のセル記号・カギ定義の欠損や不正値など、
              入力内容が検証に失敗した場合。
  
      Notes:
          この関数を呼び出すと既存の候補リストは破棄され、状態が再初期化される。
      """
  
      grid = _load_grid(grid_text)
      clues = _load_clues(clue_text, grid)
  
      state.grid = grid
      state.clues = clues
      state.candidates.clear()
  
      return grid

• src/server.py:44-73 (helper)

  Helper function called by setup to parse and validate the grid_text into a 2D list of fillable ('?') and block ('#') cells, handling full-width numbers and row consistency.

  def _load_grid(grid_text: str) -> list[list[str]]:
      "グリッド文字列を読み込み、全角表記の入力からセル行列を構築する"
      grid: list[list[str]] = []
  
      for raw_line in grid_text.splitlines():
          if FILLABLE_CELL not in raw_line and BLOCK_CELL not in raw_line:
              continue
  
          normalized_line = raw_line.translate(_FULLWIDTH_DIGIT_TO_ASCII)
          parts = normalized_line.strip().split()
          if not parts:
              continue
  
          if parts[0].isdigit():
              tokens = parts[1:]
          else:
              tokens = parts
  
          if not tokens:
              continue
  
          for token in tokens:
              if token not in {FILLABLE_CELL, BLOCK_CELL}:
                  raise ValueError(f"未知のマス表現を検出しました: {token}")
          if grid and len(tokens) != len(grid[0]):
              raise ValueError("行ごとのマス数が一致しません。入力を確認してください。")
  
          grid.append(tokens)
  
      return grid

• src/server.py:140-162 (helper)

  Helper function called by setup to parse JSON Lines clue_text into a dictionary of validated Clue objects, using _validate_clue_payload for each.

  def _load_clues(clue_text: str, grid: list[list[str]]) -> dict[str, Clue]:
      "JSON Lines 形式のカギ定義を読み込み、検証した Clue オブジェクトへ変換する"
  
      lines = [line.strip() for line in clue_text.splitlines() if line.strip()]
      if not lines:
          raise ValueError("カギ情報が存在しません。")
  
      seen_ids: set[str] = set()
      clues: dict[str, Clue] = {}
  
      for line_no, raw in enumerate(lines, start=1):
          try:
              payload = json.loads(raw)
          except json.JSONDecodeError as exc:
              raise ValueError(f"{line_no} 行目のカギ情報を JSON として読み込めません。") from exc
  
          if not isinstance(payload, dict):
              raise ValueError(f"{line_no} 行目のカギ情報が辞書形式ではありません。")
  
          clue = _validate_clue_payload(payload, grid, seen_ids)
          clues[clue.clue_id] = clue
  
      return clues

• src/server.py:76-137 (helper)

  Helper function used by _load_clues to validate individual clue payloads, compute positions on grid, and create Clue dataclass instances.

  def _validate_clue_payload(
      payload: dict[str, object],
      grid: list[list[str]],
      seen_ids: set[str],
  ) -> Clue:
      "JSON 行から取得したカギ情報を検証し、内部で扱いやすい形へ変換する"
  
      required_keys = ("id", "direction", "row", "col", "length", "clue")
      for key in required_keys:
          if key not in payload:
              raise ValueError(f"カギ情報に {key} がありません。")
  
      clue_id = str(payload["id"]).strip()
      if not clue_id:
          raise ValueError("clue_id が空です。")
      if clue_id in seen_ids:
          raise ValueError(f"clue_id={clue_id} が重複しています。")
  
      direction = str(payload["direction"]).strip().lower()
      if direction not in {"across", "down"}:
          raise ValueError(f"clue_id={clue_id} の direction が不正です: {payload['direction']}")
  
      try:
          row = int(payload["row"])
          col = int(payload["col"])
          length = int(payload["length"])
      except (TypeError, ValueError) as exc:
          raise ValueError(f"clue_id={clue_id} の row/col/length を整数に変換できません。") from exc
  
      if row <= 0 or col <= 0 or length <= 0:
          raise ValueError(f"clue_id={clue_id} の row/col/length が不正です。")
  
      rows = len(grid)
      cols = len(grid[0]) if rows else 0
      start_r = row - 1
      start_c = col - 1
  
      if start_r >= rows or start_c >= cols:
          raise ValueError(f"clue_id={clue_id} の開始位置が盤面外です。")
  
      positions: list[tuple[int, int]] = []
      for offset in range(length):
          r = start_r + (offset if direction == "down" else 0)
          c = start_c + (offset if direction == "across" else 0)
          if r >= rows or c >= cols:
              raise ValueError(f"clue_id={clue_id} の単語が盤面外にはみ出します。")
          if grid[r][c] == BLOCK_CELL:
              raise ValueError(f"clue_id={clue_id} が黒マスを含んでいます。")
          positions.append((r, c))
  
      clue_text = str(payload["clue"]).strip()
      if not clue_text:
          raise ValueError(f"clue_id={clue_id} の clue が空です。")
  
      seen_ids.add(clue_id)
      return Clue(
          clue_id=clue_id,
          direction=direction,
          length=length,
          positions=tuple(positions),
          text=clue_text,
      )

• src/server.py:12-21 (schema)

  Dataclass defining the structure for validated clues, used in PuzzleState by setup.

  @dataclass(frozen=True)
  class Clue:
      "探索ロジックが参照する検証済みのカギ定義"
  
      clue_id: str
      direction: str
      length: int
      positions: tuple[tuple[int, int], ...]
      text: str