Crossword MCP Server

Instructions

Implementation Reference

• src/server.py:205-262 (handler)

  The handler function for the 'register_candidates' MCP tool. It validates the clue_id, filters candidates by length matching the clue, adds new unique ones to the state, and returns lists of registered and rejected candidates.

  @mcp.tool()
  async def register_candidates(
      clue_id: str,
      candidates: list[str],
  ) -> dict[str, list[str]]:
      """指定したカギに対して文字数がマッチする候補語を追加登録する。登録済みと除外された語をまとめて返す。
  
      Args:
          clue_id (str): 登録対象のカギ ID。`setup` で読み込んだカギ定義に存在している
              必要がある。前後の空白は自動で除去される。
          candidates (list[str]): 追加したい候補語のリスト。空文字は許容されない。
              カギの `length` と文字数が一致しない語は登録されず、除外リストに入る。
  
      Returns:
          dict[str, list[str]]: `registered` に登録後の候補語リスト（過去の登録分を含む）、
              `rejected` に長さ不一致で追加できなかった語のリストを格納する辞書。
  
      Notes:
          長さが一致した語のみ状態に追加され、既存の候補リストは保持したまま追記される。
          同じ語が既に登録済みの場合は無視される。
  
      Raises:
          RuntimeError: `setup` をまだ呼び出していない場合。
          ValueError: `clue_id` が空、または候補語が空文字だった場合。
          KeyError: 指定した `clue_id` のカギが存在しない場合。
      """
  
      _ensure_setup()
  
      if not clue_id:
          raise ValueError("clue_id は必須です。")
  
      clue_id = clue_id.strip()
      if clue_id not in state.clues:
          raise KeyError("指定された clue_id のカギが存在しません。")
  
      clue = state.clues[clue_id]
      existing = state.candidates.get(clue_id)
      if existing is None:
          existing = []
  
      rejected: list[str] = []
  
      for candidate in candidates:
          word = candidate.strip()
          if not word:
              raise ValueError("空の候補は登録できません。")
          if len(word) == clue.length:
              if word not in existing:
                  existing.append(word)
          else:
              rejected.append(word)
  
      state.candidates[clue_id] = existing
  
      final_registered = state.candidates.get(clue_id, [])
  
      return {"登録済みの候補語リスト": list(final_registered), "文字数がマッチせず登録されなかった候補語リスト": rejected}

• src/server.py:205-205 (registration)

  The @mcp.tool() decorator registers the register_candidates function as an MCP tool.

  @mcp.tool()

• src/server.py:206-230 (schema)

  Type hints and docstring define the input schema (clue_id: str, candidates: list[str]) and output schema (dict with registered and rejected lists).

  async def register_candidates(
      clue_id: str,
      candidates: list[str],
  ) -> dict[str, list[str]]:
      """指定したカギに対して文字数がマッチする候補語を追加登録する。登録済みと除外された語をまとめて返す。
  
      Args:
          clue_id (str): 登録対象のカギ ID。`setup` で読み込んだカギ定義に存在している
              必要がある。前後の空白は自動で除去される。
          candidates (list[str]): 追加したい候補語のリスト。空文字は許容されない。
              カギの `length` と文字数が一致しない語は登録されず、除外リストに入る。
  
      Returns:
          dict[str, list[str]]: `registered` に登録後の候補語リスト（過去の登録分を含む）、
              `rejected` に長さ不一致で追加できなかった語のリストを格納する辞書。
  
      Notes:
          長さが一致した語のみ状態に追加され、既存の候補リストは保持したまま追記される。
          同じ語が既に登録済みの場合は無視される。
  
      Raises:
          RuntimeError: `setup` をまだ呼び出していない場合。
          ValueError: `clue_id` が空、または候補語が空文字だった場合。
          KeyError: 指定した `clue_id` のカギが存在しない場合。
      """