Blockscout MCP Server

Instructions

Implementation Reference

• blockscout_mcp_server/tools/contract/inspect_contract_code.py:16-65 (handler)

  The main handler function implementing the core logic of the 'inspect_contract_code' tool. It handles metadata retrieval or specific file fetching, progress reporting, validation, and response construction using shared helpers.

  @log_tool_invocation
  async def inspect_contract_code(
      chain_id: Annotated[str, Field(description="The ID of the blockchain.")],
      address: Annotated[str, Field(description="The address of the smart contract.")],
      file_name: Annotated[
          str | None,
          Field(
              description=(
                  "The name of the source file to inspect. "
                  "If omitted, returns contract metadata and the list of source files."
              ),
          ),
      ] = None,
      *,
      ctx: Context,
  ) -> ToolResponse[ContractMetadata | ContractSourceFile]:
      """Inspects a verified contract's source code or metadata."""
      if file_name is None:
          start_msg = f"Starting to fetch contract metadata for {address} on chain {chain_id}..."
      else:
          start_msg = f"Starting to fetch source code for '{file_name}' of contract {address} on chain {chain_id}..."
      await report_and_log_progress(
          ctx,
          progress=0.0,
          total=2.0,
          message=start_msg,
      )
  
      processed = await _fetch_and_process_contract(chain_id, address, ctx)
      if file_name is None:
          metadata = ContractMetadata.model_validate(processed.metadata)
          instructions = None
          notes = None
          if metadata.constructor_args_truncated:
              notes = ["Constructor arguments were truncated to limit context size."]
          if processed.source_files:
              instructions = [
                  (
                      "To retrieve a specific file's contents, call this tool again with the "
                      "'file_name' argument using one of the values from 'source_code_tree_structure'."
                  )
              ]
          return build_tool_response(data=metadata, instructions=instructions, notes=notes)
      if file_name not in processed.source_files:
          available = ", ".join(processed.source_files.keys())
          raise ValueError(
              f"File '{file_name}' not found in the source code for this contract. Available files: {available}"
          )
      return build_tool_response(data=ContractSourceFile(file_content=processed.source_files[file_name]))

• blockscout_mcp_server/tools/contract/_shared.py:25-104 (helper)

  Key helper function that fetches contract data from Blockscout API or cache, processes source files and metadata (including truncation), and returns a CachedContract object used by the handler.

  async def _fetch_and_process_contract(chain_id: str, address: str, ctx: Context) -> CachedContract:
      """Fetch contract data from cache or Blockscout API."""
  
      normalized_address = address.lower()
      cache_key = f"{chain_id}:{normalized_address}"
      if cached := await contract_cache.get(cache_key):
          return cached
  
      base_url = await get_blockscout_base_url(chain_id)
      await report_and_log_progress(
          ctx,
          progress=1.0,
          total=2.0,
          message="Resolved Blockscout instance URL.",
      )
      api_path = f"/api/v2/smart-contracts/{normalized_address}"
      raw_data = await make_blockscout_request(base_url=base_url, api_path=api_path)
      await report_and_log_progress(
          ctx,
          progress=2.0,
          total=2.0,
          message="Successfully fetched contract data.",
      )
      raw_data.setdefault("name", normalized_address)
      for key in [
          "language",
          "compiler_version",
          "verified_at",
          "optimization_enabled",
          "optimization_runs",
          "evm_version",
          "license_type",
          "proxy_type",
          "is_fully_verified",
          "decoded_constructor_args",
      ]:
          raw_data.setdefault(key, None)
  
      source_files: dict[str, str] = {}
      if raw_data.get("source_code"):
          if raw_data.get("additional_sources"):
              main_file_path = _determine_file_path(raw_data)
              source_files[main_file_path] = raw_data.get("source_code")
              for item in raw_data.get("additional_sources", []):
                  item_path = item.get("file_path")
                  if item_path:
                      source_files[item_path] = item.get("source_code")
          else:
              file_path = _determine_file_path(raw_data)
              source_files[file_path] = raw_data.get("source_code")
  
      # Create a copy to avoid mutating the original raw_data
      metadata_copy = raw_data.copy()
  
      # Process constructor args on the copy instead of the original
      from blockscout_mcp_server.tools.common import _truncate_constructor_args  # Local import to avoid cycles
  
      processed_args, truncated_flag = _truncate_constructor_args(metadata_copy.get("constructor_args"))
      metadata_copy["constructor_args"] = processed_args
      metadata_copy["constructor_args_truncated"] = truncated_flag
      if metadata_copy["decoded_constructor_args"]:
          processed_decoded, decoded_truncated = _truncate_constructor_args(metadata_copy["decoded_constructor_args"])
          metadata_copy["decoded_constructor_args"] = processed_decoded
          if decoded_truncated:
              metadata_copy["constructor_args_truncated"] = True
      metadata_copy["source_code_tree_structure"] = list(source_files.keys())
      for field in [
          "abi",
          "deployed_bytecode",
          "creation_bytecode",
          "source_code",
          "additional_sources",
          "file_path",
      ]:
          metadata_copy.pop(field, None)
  
      cached_contract = CachedContract(metadata=metadata_copy, source_files=source_files)
      await contract_cache.set(cache_key, cached_contract)
      return cached_contract

• blockscout_mcp_server/models.py:122-158 (schema)

  Pydantic models ContractMetadata (for metadata response) and ContractSourceFile (for file content response) defining the structured output schema for the tool. Used in ToolResponse[ContractMetadata | ContractSourceFile].

  class ContractMetadata(BaseModel):
      """Detailed metadata for a verified smart contract."""
  
      # Allow extra fields to preserve language-specific and contract-specific metadata
      # from Blockscout API that varies by verification status and contract type
      model_config = ConfigDict(extra="allow")
  
      name: str = Field(description="The name of the contract.")
      language: str | None = Field(description="The programming language of the contract (e.g., Solidity, Vyper).")
      compiler_version: str | None = Field(description="The compiler version used.")
      verified_at: str | None = Field(description="The timestamp when the contract was verified.")
      source_code_tree_structure: list[str] = Field(description="A list of all source file paths for the contract.")
  
      optimization_enabled: bool | None = Field(description="Flag indicating if compiler optimization was enabled.")
      optimization_runs: int | None = Field(description="The number of optimization runs.")
      evm_version: str | None = Field(description="The EVM version target.")
      license_type: str | None = Field(description="The license of the contract code (e.g., MIT, none).")
      proxy_type: str | None = Field(
          description="The type of proxy if the contract is a proxy (e.g., basic_implementation)."
      )
      is_fully_verified: bool | None = Field(description="Flag indicating if the contract is fully verified.")
  
      constructor_args: str | None = Field(description="The raw constructor arguments, possibly truncated.")
      decoded_constructor_args: str | dict | list | None = Field(
          default=None, description="Decoded constructor arguments, if available."
      )
      constructor_args_truncated: bool = Field(
          default=False, description="Indicates if constructor_args or decoded_constructor_args was truncated."
      )
  
  
  # --- Model for inspect_contract_code File Payload ---
  class ContractSourceFile(BaseModel):
      """Container for a single contract source file."""
  
      file_content: str = Field(description="The raw source code of the file.")

• blockscout_mcp_server/server.py:178-180 (registration)

  Registration of the 'inspect_contract_code' tool with the FastMCP server instance, including annotations for title, read-only hint, etc.

      structured_output=False,
      annotations=create_tool_annotations("Inspect Contract Code"),
  )(inspect_contract_code)