fix(gitea-mcp): address MCP tool issues from Sprint 6

Fixes #281 - Multiple MCP tool issues discovered during sprint execution

## Changes

1. **list_issues Token Overflow** (Issue 1)
   - Added `milestone` parameter to filter issues server-side
   - Reduces response size by filtering at API level instead of client-side

2. **Type Coercion for MCP Serialization** (Issues 2 & 4)
   - Added `_coerce_types()` helper function in server.py
   - Handles integers passed as strings (milestone_id, issue_number, etc.)
   - Handles arrays passed as JSON strings (labels, tags, etc.)
   - Applied to all tool calls automatically

3. **Sprint Approval Check Clarification** (Issue 3)
   - Updated sprint-start.md to clarify approval is RECOMMENDED, not enforced
   - Changed STOP/block language to WARN/suggest language
   - Added note explaining this is workflow guidance, not code-enforced

## Files Changed
- mcp-servers/gitea/mcp_server/gitea_client.py: Added milestone param
- mcp-servers/gitea/mcp_server/tools/issues.py: Pass milestone param
- mcp-servers/gitea/mcp_server/server.py: Type coercion + milestone schema
- plugins/projman/commands/sprint-start.md: Clarified approval check

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

mcp-servers/gitea/mcp_server/gitea_client.py

@@ -53,6 +53,7 @@ class GiteaClient:
         self,
         state: str = 'open',
         labels: Optional[List[str]] = None,
+        milestone: Optional[str] = None,
         repo: Optional[str] = None
     ) -> List[Dict]:
         """
@@ -61,6 +62,7 @@ class GiteaClient:
         Args:
             state: Issue state (open, closed, all)
             labels: Filter by labels
+            milestone: Filter by milestone title (exact match)
             repo: Repository in 'owner/repo' format
 
         Returns:
@@ -71,6 +73,8 @@ class GiteaClient:
         params = {'state': state}
         if labels:
             params['labels'] = ','.join(labels)
+        if milestone:
+            params['milestones'] = milestone
         logger.info(f"Listing issues from {owner}/{target_repo} with state={state}")
         response = self.session.get(url, params=params)
         response.raise_for_status()

mcp-servers/gitea/mcp_server/server.py

@@ -26,6 +26,44 @@ logging.getLogger("mcp").setLevel(logging.ERROR)
 logger = logging.getLogger(__name__)
 
 
+def _coerce_types(arguments: dict) -> dict:
+    """
+    Coerce argument types to handle MCP serialization quirks.
+
+    MCP sometimes passes integers as strings and arrays as JSON strings.
+    This function normalizes them to the expected Python types.
+    """
+    coerced = {}
+    for key, value in arguments.items():
+        if value is None:
+            coerced[key] = value
+            continue
+
+        # Coerce integer fields
+        int_fields = {'issue_number', 'milestone_id', 'pr_number', 'depends_on', 'milestone', 'limit'}
+        if key in int_fields and isinstance(value, str):
+            try:
+                coerced[key] = int(value)
+                continue
+            except ValueError:
+                pass
+
+        # Coerce array fields that might be JSON strings
+        array_fields = {'labels', 'tags', 'issue_numbers', 'comments'}
+        if key in array_fields and isinstance(value, str):
+            try:
+                parsed = json.loads(value)
+                if isinstance(parsed, list):
+                    coerced[key] = parsed
+                    continue
+            except json.JSONDecodeError:
+                pass
+
+        coerced[key] = value
+
+    return coerced
+
+
 class GiteaMCPServer:
     """MCP Server for Gitea integration"""
 
@@ -88,6 +126,10 @@ class GiteaMCPServer:
                                 "items": {"type": "string"},
                                 "description": "Filter by labels"
                             },
+                            "milestone": {
+                                "type": "string",
+                                "description": "Filter by milestone title (exact match)"
+                            },
                             "repo": {
                                 "type": "string",
                                 "description": "Repository name (for PMO mode)"
@@ -899,6 +941,9 @@ class GiteaMCPServer:
                 List of TextContent with results
             """
             try:
+                # Coerce types to handle MCP serialization quirks
+                arguments = _coerce_types(arguments)
+
                 # Route to appropriate tool handler
                 if name == "list_issues":
                     result = await self.issue_tools.list_issues(**arguments)

mcp-servers/gitea/mcp_server/tools/issues.py

@@ -98,6 +98,7 @@ class IssueTools:
         self,
         state: str = 'open',
         labels: Optional[List[str]] = None,
+        milestone: Optional[str] = None,
         repo: Optional[str] = None
     ) -> List[Dict]:
         """
@@ -106,6 +107,7 @@ class IssueTools:
         Args:
             state: Issue state (open, closed, all)
             labels: Filter by labels
+            milestone: Filter by milestone title (exact match)
             repo: Override configured repo (for PMO multi-repo)
 
         Returns:
@@ -124,7 +126,7 @@ class IssueTools:
         loop = asyncio.get_event_loop()
         return await loop.run_in_executor(
             None,
-            lambda: self.gitea.list_issues(state, labels, repo)
+            lambda: self.gitea.list_issues(state, labels, milestone, repo)
         )
 
     async def get_issue(