fix(tools): Fix serialization for Claude Code passing unexpected serialized inputs

Issue: APPAI-89

Author: timothedelion

packages/developer_mcp_server/src/developer_mcp_server/register_tools.py

@@ -1,4 +1,5 @@
 from fastmcp import FastMCP
+from gg_api_core.schema_utils import compress_pydantic_model_schema
 from gg_api_core.tools.find_current_source_id import find_current_source_id
 from gg_api_core.tools.generate_honey_token import generate_honeytoken
 from gg_api_core.tools.list_honey_tokens import list_honeytokens
@@ -45,15 +46,19 @@
 
 
 def register_developer_tools(mcp: FastMCP):
-    mcp.tool(
+    # Register tools with Pydantic model parameters and compress their schemas
+    # to work around Claude Code bug that serializes params as JSON strings
+
+    remediate_tool = mcp.tool(
         remediate_secret_incidents,
         description="Find and fix secrets in the current repository using exact match locations (file paths, line numbers, character indices). "
         "This tool leverages the occurrences API to provide precise remediation instructions without needing to search for secrets in files. "
         "By default, this only shows incidents assigned to the current user. Pass mine=False to get all incidents related to this repo.",
         required_scopes=["incidents:read", "sources:read"],
     )
+    remediate_tool.parameters = compress_pydantic_model_schema(remediate_tool.parameters)
 
-    mcp.tool(
+    scan_tool = mcp.tool(
         scan_secrets,
         description="""
         Scan multiple content items for secrets and policy breaks.
@@ -65,23 +70,27 @@ def register_developer_tools(mcp: FastMCP):
         """,
         required_scopes=["scan"],
     )
+    scan_tool.parameters = compress_pydantic_model_schema(scan_tool.parameters)
 
-    mcp.tool(
+    list_incidents_tool = mcp.tool(
         list_repo_incidents,
         description="List secret incidents or occurrences related to a specific repository, and assigned to the current user."
         "By default, this tool only shows incidents assigned to the current user. "
         "Only pass mine=False to get all incidents related to this repo if the user explicitly asks for all incidents even the ones not assigned to him.",
         required_scopes=["incidents:read", "sources:read"],
     )
+    list_incidents_tool.parameters = compress_pydantic_model_schema(list_incidents_tool.parameters)
 
-    mcp.tool(
+    list_occurrences_tool = mcp.tool(
         list_repo_occurrences,
         description="List secret occurrences for a specific repository with exact match locations. "
         "Returns detailed occurrence data including file paths, line numbers, and character indices where secrets were detected. "
         "Use this tool when you need to locate and remediate secrets in the codebase with precise file locations.",
         required_scopes=["incidents:read"],
     )
+    list_occurrences_tool.parameters = compress_pydantic_model_schema(list_occurrences_tool.parameters)
 
+    # find_current_source_id doesn't use a Pydantic model parameter, so no compression needed
     mcp.tool(
         find_current_source_id,
         description="Find the GitGuardian source_id for a repository. "
@@ -91,20 +100,23 @@ def register_developer_tools(mcp: FastMCP):
         required_scopes=["sources:read"],
     )
 
-    mcp.tool(
+    generate_token_tool = mcp.tool(
         generate_honeytoken,
         description="Generate an AWS GitGuardian honeytoken and get injection recommendations",
         required_scopes=["honeytokens:write"],
     )
+    generate_token_tool.parameters = compress_pydantic_model_schema(generate_token_tool.parameters)
 
-    mcp.tool(
+    list_tokens_tool = mcp.tool(
         list_honeytokens,
         description="List honeytokens from the GitGuardian dashboard with filtering options",
         required_scopes=["honeytokens:read"],
     )
+    list_tokens_tool.parameters = compress_pydantic_model_schema(list_tokens_tool.parameters)
 
-    mcp.tool(
+    list_users_tool = mcp.tool(
         list_users,
         description="List users on the workspace/account",
         required_scopes=["members:read"],
     )
+    list_users_tool.parameters = compress_pydantic_model_schema(list_users_tool.parameters)

packages/gg_api_core/pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
     "python-dotenv>=1.0.0",
     "pydantic-settings>=2.0.0",
     "jinja2>=3.1.0",
+    "jsonref>=1.1.0",
 ]
 license = {text = "MIT"}
 

packages/gg_api_core/src/gg_api_core/schema_utils.py

@@ -0,0 +1,66 @@
+"""Utility functions for MCP tool schema manipulation."""
+
+import json
+import logging
+
+import jsonref
+
+logger = logging.getLogger(__name__)
+
+
+def compress_pydantic_model_schema(tool_parameters: dict) -> dict:
+    """
+    Compress a tool schema by flattening nested Pydantic model parameters.
+
+    When FastMCP tools use a single Pydantic model as a parameter (e.g., `params: MyParamsModel`),
+    the generated schema nests all the model's fields under that parameter name. This creates
+    an extra level of nesting that some MCP clients (like Claude Code) handle incorrectly.
+
+    This function flattens the schema by:
+    1. Resolving all JSON references
+    2. Extracting the properties from the nested model
+    3. Promoting them to top-level parameters
+
+    Example:
+        Before compression:
+        {
+            "type": "object",
+            "properties": {
+                "params": {
+                    "type": "object",
+                    "properties": {
+                        "source_id": {"type": "integer"},
+                        "get_all": {"type": "boolean"}
+                    }
+                }
+            }
+        }
+
+        After compression:
+        {
+            "type": "object",
+            "properties": {
+                "source_id": {"type": "integer"},
+                "get_all": {"type": "boolean"}
+            }
+        }
+
+    Args:
+        tool_parameters: The tool's parameters schema (from tool.parameters)
+
+    Returns:
+        Compressed schema with flattened parameters
+    """
+    try:
+        # Resolve all JSON references
+        resolved = jsonref.replace_refs(tool_parameters)
+
+        # Convert back to plain dict (jsonref returns a special JsonRef object)
+        compressed = json.loads(jsonref.dumps(resolved))
+
+        logger.debug(f"Compressed tool schema: {json.dumps(compressed, indent=2)}")
+        return compressed
+    except Exception as e:
+        logger.exception(f"Failed to compress schema: {str(e)}")
+        # Return original schema if compression fails
+        return tool_parameters

packages/secops_mcp_server/src/secops_mcp_server/server.py

@@ -7,6 +7,7 @@
 from developer_mcp_server.register_tools import register_developer_tools
 from fastmcp.exceptions import ToolError
 from gg_api_core.mcp_server import get_mcp_server
+from gg_api_core.schema_utils import compress_pydantic_model_schema
 from gg_api_core.scopes import set_secops_scopes
 from gg_api_core.tools.assign_incident import assign_incident
 from gg_api_core.tools.create_code_fix_request import create_code_fix_request
@@ -149,59 +150,70 @@ async def get_current_token_info() -> dict[str, Any]:
         raise ToolError(f"Error: {str(e)}")
 
 
-mcp.tool(
+# Register SecOps tools with schema compression for Pydantic model parameters
+
+update_tags_tool = mcp.tool(
     update_or_create_incident_custom_tags,
     description="Update or create custom tags for a secret incident",
     required_scopes=["incidents:write", "custom_tags:write"],
 )
+update_tags_tool.parameters = compress_pydantic_model_schema(update_tags_tool.parameters)
 
-mcp.tool(
+update_status_tool = mcp.tool(
     update_incident_status,
     description="Update a secret incident with status",
     required_scopes=["incidents:write"],
 )
+update_status_tool.parameters = compress_pydantic_model_schema(update_status_tool.parameters)
 
-mcp.tool(
+read_tags_tool = mcp.tool(
     read_custom_tags,
     description="Read custom tags from the GitGuardian dashboard.",
     required_scopes=["custom_tags:read"],
 )
+read_tags_tool.parameters = compress_pydantic_model_schema(read_tags_tool.parameters)
 
-mcp.tool(
+write_tags_tool = mcp.tool(
     write_custom_tags,
     description="Create or delete custom tags in the GitGuardian dashboard.",
     required_scopes=["custom_tags:write"],
 )
+write_tags_tool.parameters = compress_pydantic_model_schema(write_tags_tool.parameters)
 
-mcp.tool(
+manage_incident_tool = mcp.tool(
     manage_private_incident,
     description="Manage a secret incident (assign, unassign, resolve, ignore, reopen)",
     required_scopes=["incidents:write"],
 )
+manage_incident_tool.parameters = compress_pydantic_model_schema(manage_incident_tool.parameters)
 
-mcp.tool(
+list_users_tool = mcp.tool(
     list_users,
     description="List users on the workspace/account",
     required_scopes=["members:read"],
 )
+list_users_tool.parameters = compress_pydantic_model_schema(list_users_tool.parameters)
 
-mcp.tool(
+revoke_secret_tool = mcp.tool(
     revoke_secret,
     description="Revoke a secret by its ID through the GitGuardian API",
     required_scopes=["write:secret"],
 )
+revoke_secret_tool.parameters = compress_pydantic_model_schema(revoke_secret_tool.parameters)
 
-mcp.tool(
+assign_incident_tool = mcp.tool(
     assign_incident,
     description="Assign a secret incident to a specific member or to the current user",
     required_scopes=["incidents:write"],
 )
+assign_incident_tool.parameters = compress_pydantic_model_schema(assign_incident_tool.parameters)
 
-mcp.tool(
+create_fix_tool = mcp.tool(
     create_code_fix_request,
     description="Create code fix requests for multiple secret incidents with their locations. This will generate pull requests to automatically remediate the detected secrets.",
     required_scopes=["incidents:write"],
 )
+create_fix_tool.parameters = compress_pydantic_model_schema(create_fix_tool.parameters)
 
 # Register common tools for user information and token management
 try: