JSON Skeleton MCP Server

Instructions

Implementation Reference

• src/json_skeleton/skeleton_generator.py:149-181 (handler)

  Core handler that loads the JSON file from disk, generates the skeleton recursively, and returns a result dictionary with file metadata and the skeleton.

  def process_file(self, file_path: str, max_length: int = None, type_only: bool = False) -> Dict[str, Any]:
      """Process a JSON file and return skeleton."""
      # Update max_length if provided
      if max_length is not None:
          self.max_value_length = max_length
      
      # Set type_only mode
      self.type_only_mode = type_only
      
      path = Path(file_path)
      
      if not path.exists():
          raise FileNotFoundError(f"File not found: {file_path}")
      
      if not path.is_file():
          raise ValueError(f"Path is not a file: {file_path}")
      
      try:
          with open(path, 'r', encoding='utf-8') as f:
              data = json.load(f)
      except json.JSONDecodeError as e:
          raise ValueError(f"Invalid JSON file: {e}")
      except Exception as e:
          raise Exception(f"Error reading file: {e}")
      
      skeleton = self.create_skeleton(data)
      
      return {
          "file_path": str(path.absolute()),
          "file_size": path.stat().st_size,
          "skeleton": skeleton
      }

• src/json_skeleton/server.py:30-49 (schema)

  Input schema defining parameters: file_path (required), optional max_length and type_only.

  inputSchema={
      "type": "object",
      "properties": {
          "file_path": {
              "type": "string",
              "description": "Path to the JSON file to process"
          },
          "max_length": {
              "type": "integer",
              "description": "Maximum length for string values (default: 200)",
              "default": 200
          },
          "type_only": {
              "type": "boolean",
              "description": "Return only value types instead of values. Most compact output. (default: false)",
              "default": False
          }
      },
      "required": ["file_path"]
  }

• src/json_skeleton/server.py:23-51 (registration)

  Registers the 'json_skeleton' tool in the MCP server with name, description, and input schema.

  @server.list_tools()
  async def list_tools() -> list[Tool]:
      """List available tools."""
      return [
          Tool(
              name="json_skeleton",
              description="Create a lightweight JSON skeleton that preserves structure with truncated values and deduplicated arrays. Useful when encountering 'File content exceeds maximum allowed size' errors with large JSON files.",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "file_path": {
                          "type": "string",
                          "description": "Path to the JSON file to process"
                      },
                      "max_length": {
                          "type": "integer",
                          "description": "Maximum length for string values (default: 200)",
                          "default": 200
                      },
                      "type_only": {
                          "type": "boolean",
                          "description": "Return only value types instead of values. Most compact output. (default: false)",
                          "default": False
                      }
                  },
                  "required": ["file_path"]
              }
          )
      ]

• src/json_skeleton/server.py:54-83 (handler)

  MCP server handler for tool calls; specifically handles 'json_skeleton' by invoking SkeletonGenerator.process_file and returning formatted skeleton as TextContent.

  @server.call_tool()
  async def call_tool(name: str, arguments: Dict[str, Any]) -> list[TextContent]:
      """Handle tool calls."""
      try:
          if name == "json_skeleton":
              file_path = arguments.get("file_path")
              if not file_path:
                  return [TextContent(type="text", text="Error: file_path is required")]
              
              max_length = arguments.get("max_length", 200)
              type_only = arguments.get("type_only", False)
              result = skeleton_generator.process_file(file_path, max_length=max_length, type_only=type_only)
              
              # Format the output - just the skeleton
              output = json.dumps(result['skeleton'], indent=2, ensure_ascii=False)
              
              return [TextContent(type="text", text=output)]
          
          else:
              return [TextContent(type="text", text=f"Error: Unknown tool '{name}'")]
      
      except FileNotFoundError as e:
          return [TextContent(type="text", text=f"Error: {str(e)}")]
      except ValueError as e:
          return [TextContent(type="text", text=f"Error: {str(e)}")]
      except Exception as e:
          # Log error to stderr for debugging
          import sys
          print(f"Error processing file: {str(e)}", file=sys.stderr)
          return [TextContent(type="text", text=f"Error: Failed to process file - {str(e)}")]

• src/json_skeleton/skeleton_generator.py:17-23 (helper)

  Delegates to recursive _process_value for generating the skeleton from JSON data.

  def create_skeleton(self, data: Any) -> Any:
      """
      Create a lightweight skeleton with:
      - Truncated string values (configurable max length)
      - Deduplicated array items (keeping unique DTOs)
      """
      return self._process_value(data)