fix critical label issues: validation, listing, and visibility

## critical fixes

### 1. fix pydantic field warning
- remove invalid `Field(default=None)` from settings.py
- change to `tangled_pds_url: str | None = None`

### 2. add loud label validation
- new `_validate_labels()` helper checks labels against repo's subscribed definitions
- raises `ValueError` with available labels list when invalid labels provided
- prevents silent failures when creating/updating issues

### 3. include labels in list_repo_issues
- add `labels: list[str]` field to `IssueInfo` model
- fetch and correlate label ops with issues
- return label names (not URIs) for better UX

### 4. add list_repo_labels tool
- new tool to query available labels for a repository
- extracts label names from repo's subscribed label definitions
- helps users discover which labels they can use

## changes

- src/tangled_mcp/settings.py: fix pydantic warning
- src/tangled_mcp/_tangled/_issues.py: add validation, label fetching, new tool
- src/tangled_mcp/types/_issues.py: add labels field to IssueInfo
- src/tangled_mcp/server.py: expose list_repo_labels tool
- src/tangled_mcp/_tangled/__init__.py: export list_repo_labels
- tests/test_server.py: update tool count (5 -> 6)
- README.md: document new tool

all 17 tests passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

README.md

···
 - `update_repo_issue(repo, issue_id, title, body, labels)` - update an issue's title, body, and/or labels
 - `delete_repo_issue(repo, issue_id)` - delete an issue
 - `list_repo_issues(repo, limit, cursor)` - list issues for a repository
+- `list_repo_labels(repo)` - list available labels for a repository
 
 ## development
 

src/tangled_mcp/_tangled/__init__.py

···
     create_issue,
     delete_issue,
     list_repo_issues,
+    list_repo_labels,
     update_issue,
 )
 
···
     "update_issue",
     "delete_issue",
     "list_repo_issues",
+    "list_repo_labels",
     "resolve_repo_identifier",
 ]

src/tangled_mcp/_tangled/_issues.py

···
 
     # filter issues by repo
     issues = []
+    issue_uris = []
     for record in response.records:
         if (
             repo := getattr(record.value, "repo", None)
         ) is not None and repo == repo_at_uri:
+            issue_uris.append(record.uri)
             issues.append(
                 {
                     "uri": record.uri,
···
                     "title": getattr(record.value, "title", ""),
                     "body": getattr(record.value, "body", None),
                     "createdAt": getattr(record.value, "createdAt", ""),
+                    "labels": [],  # will be populated below
                 }
             )
 
+    # fetch label ops and correlate with issues
+    if issue_uris:
+        label_ops = client.com.atproto.repo.list_records(
+            models.ComAtprotoRepoListRecords.Params(
+                repo=client.me.did,
+                collection="sh.tangled.label.op",
+                limit=100,
+            )
+        )
+
+        # build map of issue_uri -> current label URIs
+        issue_labels_map: dict[str, set[str]] = {uri: set() for uri in issue_uris}
+        for op_record in label_ops.records:
+            if hasattr(op_record.value, "subject") and op_record.value.subject in issue_labels_map:
+                subject_uri = op_record.value.subject
+                if hasattr(op_record.value, "add"):
+                    for operand in op_record.value.add:
+                        if hasattr(operand, "key"):
+                            issue_labels_map[subject_uri].add(operand.key)
+                if hasattr(op_record.value, "delete"):
+                    for operand in op_record.value.delete:
+                        if hasattr(operand, "key"):
+                            issue_labels_map[subject_uri].discard(operand.key)
+
+        # extract label names from URIs and add to issues
+        for issue in issues:
+            label_uris = issue_labels_map.get(issue["uri"], set())
+            issue["labels"] = [uri.split("/")[-1] for uri in label_uris]
+
     return {"issues": issues, "cursor": response.cursor}
 
 
+def list_repo_labels(repo_id: str) -> list[str]:
+    """list available labels for a repository
+
+    Args:
+        repo_id: repository identifier in "did/repo" format
+
+    Returns:
+        list of available label names for the repo
+    """
+    client = _get_authenticated_client()
+
+    if not client.me:
+        raise RuntimeError("client not authenticated")
+
+    # parse repo_id to get owner_did and repo_name
+    if "/" not in repo_id:
+        raise ValueError(f"invalid repo_id format: {repo_id}")
+
+    owner_did, repo_name = repo_id.split("/", 1)
+
+    # get the repo's subscribed label definitions
+    records = client.com.atproto.repo.list_records(
+        models.ComAtprotoRepoListRecords.Params(
+            repo=owner_did,
+            collection="sh.tangled.repo",
+            limit=100,
+        )
+    )
+
+    repo_labels: list[str] = []
+    for record in records.records:
+        if (
+            name := getattr(record.value, "name", None)
+        ) is not None and name == repo_name:
+            if (subscribed_labels := getattr(record.value, "labels", None)) is not None:
+                # extract label names from URIs
+                repo_labels = [uri.split("/")[-1] for uri in subscribed_labels]
+            break
+
+    if not repo_labels and not any(
+        (name := getattr(r.value, "name", None)) and name == repo_name
+        for r in records.records
+    ):
+        raise ValueError(f"repo not found: {repo_id}")
+
+    return repo_labels
+
+
 def _get_current_labels(client, issue_uri: str) -> set[str]:
     """get current labels applied to an issue by examining all label ops"""
     label_ops = client.com.atproto.repo.list_records(
···
     return current_labels
 
 
+def _validate_labels(labels: list[str], repo_labels: list[str]) -> None:
+    """validate that all requested labels exist in the repo's subscribed labels
+
+    Args:
+        labels: list of label names or URIs to validate
+        repo_labels: list of label definition URIs the repo subscribes to
+
+    Raises:
+        ValueError: if any labels are invalid, listing available labels
+    """
+    # extract available label names from repo's subscribed label URIs
+    available_labels = [uri.split("/")[-1] for uri in repo_labels]
+
+    # check each requested label
+    invalid_labels = []
+    for label in labels:
+        if label.startswith("at://"):
+            # if it's a full URI, check if it's in repo_labels
+            if label not in repo_labels:
+                invalid_labels.append(label)
+        else:
+            # if it's a name, check if it matches any available label
+            if not any(
+                label.lower() == available.lower() for available in available_labels
+            ):
+                invalid_labels.append(label)
+
+    # fail loudly if any labels are invalid
+    if invalid_labels:
+        raise ValueError(
+            f"invalid labels: {invalid_labels}\n"
+            f"available labels for this repo: {sorted(available_labels)}"
+        )
+
+
 def _apply_labels(
     client,
     issue_uri: str,
···
         labels: list of label names or URIs to apply
         repo_labels: list of label definition URIs the repo subscribes to
         current_labels: set of currently applied label URIs
+
+    Raises:
+        ValueError: if any labels are invalid (via _validate_labels)
     """
+    # validate labels before attempting to apply
+    _validate_labels(labels, repo_labels)
+
     # resolve label names to URIs
     new_label_uris = set()
     for label in labels:

src/tangled_mcp/server.py

···
     response = _tangled.list_repo_issues(repo_id, limit, cursor)
 
     return ListIssuesResult.from_api_response(response)
+
+
+@tangled_mcp.tool
+def list_repo_labels(
+    repo: Annotated[
+        str,
+        Field(
+            description="repository identifier in 'owner/repo' format (e.g., 'zzstoatzz/tangled-mcp')"
+        ),
+    ],
+) -> list[str]:
+    """list available labels for a repository
+
+    Args:
+        repo: repository identifier in 'owner/repo' format
+
+    Returns:
+        list of available label names for the repository
+    """
+    # resolve owner/repo to (knot, did/repo)
+    _, repo_id = _tangled.resolve_repo_identifier(repo)
+    # list_repo_labels doesn't need knot (queries atproto records, not XRPC)
+    return _tangled.list_repo_labels(repo_id)

src/tangled_mcp/settings.py

···
 
     # optional: specify PDS URL if auto-discovery doesn't work
     # leave empty for auto-discovery from handle
-    tangled_pds_url: str | None = Field(default=None)
+    tangled_pds_url: str | None = None
 
 
 # tangled service constants

src/tangled_mcp/types/_issues.py

···
     title: str
     body: str | None = None
     created_at: str = Field(alias="createdAt")
+    labels: list[str] = []
 
 
 class CreateIssueResult(BaseModel):

tests/test_server.py

···
         async with Client(tangled_mcp) as client:
             tools = await client.list_tools()
 
-            assert len(tools) == 5
+            assert len(tools) == 6
 
             tool_names = {tool.name for tool in tools}
             assert "list_repo_branches" in tool_names
···
             assert "update_repo_issue" in tool_names
             assert "delete_repo_issue" in tool_names
             assert "list_repo_issues" in tool_names
+            assert "list_repo_labels" in tool_names
 
     async def test_list_repo_branches_tool_schema(self):
         """test list_repo_branches tool has correct schema"""