MCP Refactoring

Instructions

Implementation Reference

• src/mcp_refactoring/tools/inspect_structure.py:29-106 (handler)

  The main handler function for the `inspect_structure` tool, which orchestrates the language detection, adapter selection, and result formatting.

  async def inspect_structure(params: InspectStructureInput) -> str:
      """Get structural information about code (classes, methods, dependencies).
  
      Inspects a file to return information about its structure including
      classes, methods, fields, and line numbers.
  
      Args:
          params: Input parameters including path and depth
  
      Returns:
          TOON-formatted string with structural information
      """
      # Detect language from path
      language = detect_language(params.path)
      if language is None:
          return encode_toon({
              "status": "error",
              "error": f"Could not detect language from path: {params.path}",
              "hint": "Ensure the path has a recognized file extension (.py, .rb, .java, .go)",
          })
  
      # Get adapter for the language
      adapter = get_adapter(language)
      if adapter is None:
          return encode_toon({
              "status": "error",
              "error": f"No backend available for language: {language}",
              "hint": f"Install the {language} refactoring backend",
          })
  
      # Validate depth parameter
      valid_depths = ["file", "class", "method"]
      if params.depth not in valid_depths:
          return encode_toon({
              "status": "error",
              "error": f"Invalid depth: {params.depth}",
              "valid_depths": valid_depths,
          })
  
      # Get structure
      result = await adapter.inspect_structure(
          path=params.path,
          depth=params.depth,
      )
  
      # Format response
      response: dict[str, Any] = {
          "structure": {
              "path": result.path,
              "language": result.language,
              "total_lines": result.total_lines,
          }
      }
  
      if result.classes:
          response["classes"] = [
              {
                  "name": c.name,
                  "line": c.line,
                  "methods": c.methods,
                  "fields": c.fields,
              }
              for c in result.classes
          ]
  
      if result.methods and params.depth == "method":
          response["methods"] = [
              {
                  "class": m.class_name or "",
                  "name": m.name,
                  "line": m.line,
                  "params": m.params,
                  "lines": m.lines,
              }
              for m in result.methods
          ]
  
      return encode_toon(response)

• src/mcp_refactoring/tools/inspect_structure.py:13-26 (schema)

  Pydantic model defining the input schema for the `inspect_structure` tool.

  class InspectStructureInput(BaseModel):
      """Input for inspecting code structure."""
  
      model_config = ConfigDict(str_strip_whitespace=True)
  
      path: str = Field(
          ...,
          description="File path to inspect (e.g., 'src/order.py')",
          min_length=1,
      )
      depth: str = Field(
          default="class",
          description="Level of detail: 'file', 'class', or 'method'",
      )

• src/mcp_refactoring/server.py:161-176 (registration)

  Registration of the `inspect_structure` tool within the MCP server definition.

  @mcp.tool(
      name="inspect_structure",
      annotations={
          "title": "Inspect Code Structure",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": False,
      },
  )
  async def inspect_structure(
      path: str,
      depth: str = "class",
  ) -> str:
      """Get structural information about code (classes, methods, line numbers).