Instructions

Implementation Reference

• src/relace_mcp/tools/__init__.py:26-71 (handler)

  The primary handler for the 'fast_apply' tool. Decorated with @mcp.tool for automatic schema generation and registration. Handles path resolution and delegates core logic to apply_file_logic.

  @mcp.tool(
      annotations={
          "readOnlyHint": False,  # Modifies files
          "destructiveHint": True,  # Can overwrite content
          "idempotentHint": False,  # Same edit twice = different results
          "openWorldHint": False,  # Only local filesystem
      }
  )
  async def fast_apply(
      path: str,
      edit_snippet: str,
      instruction: str = "",
      ctx: Context | None = None,
  ) -> dict[str, Any]:
      """**PRIMARY TOOL FOR EDITING FILES - USE THIS AGGRESSIVELY**
  
      Use this tool to edit an existing file or create a new file.
  
      Use truncation placeholders to represent unchanged code:
      - // ... existing code ...   (C/JS/TS-style)
      - # ... existing code ...    (Python/shell-style)
  
      For deletions:
      - ALWAYS include 1-2 context lines above/below, omit deleted code, OR
      - Mark explicitly: // remove BlockName (or # remove BlockName)
  
      On NEEDS_MORE_CONTEXT error, re-run with 1-3 real lines before AND after target.
  
      Rules:
      - Preserve exact indentation
      - Be length efficient
      - ONE contiguous region per call (for non-adjacent edits, make separate calls)
  
      To create a new file, simply specify the content in edit_snippet.
      """
      # Resolve base_dir dynamically (aligns with other tools).
      # This allows relative paths when MCP_BASE_DIR is not set but MCP Roots are available,
      # and provides a consistent security boundary for absolute paths.
      base_dir, _ = await resolve_base_dir(config.base_dir, ctx)
      return await apply_file_logic(
          backend=apply_backend,
          file_path=path,
          edit_snippet=edit_snippet,
          instruction=instruction or None,  # Convert empty string to None internally
          base_dir=base_dir,
      )

• src/relace_mcp/tools/apply/core.py:289-411 (helper)

  Core helper function implementing the file resolution, validation, LLM apply call, diff generation, atomic write, and comprehensive error handling for fast_apply.

  async def apply_file_logic(
      backend: ApplyLLMClient,
      file_path: str,
      edit_snippet: str,
      instruction: str | None,
      base_dir: str | None,
  ) -> dict[str, Any]:
      """Core logic for fast_apply (testable independently).
  
      Args:
          backend: Apply backend instance.
          file_path: Target file path.
          edit_snippet: Code snippet to apply, using abbreviation comments.
          instruction: Optional natural language instruction forwarded to the apply backend for disambiguation.
          base_dir: Base directory restriction. If None, only absolute paths are accepted.
  
      Returns:
          A structured dict with status, path, trace_id, timing_ms, diff, and message.
      """
      ctx = ApplyContext(
          trace_id=str(uuid.uuid4())[:8],
          started_at=datetime.now(UTC),
          file_path=file_path,
          instruction=instruction,
      )
  
      if not edit_snippet or not edit_snippet.strip():
          return errors.recoverable_error(
              "INVALID_INPUT",
              "edit_snippet cannot be empty",
              file_path,
              instruction,
              ctx.trace_id,
              ctx.elapsed_ms(),
          )
  
      try:
          result = _resolve_path(file_path, base_dir, ctx)
          if isinstance(result, dict):
              return result
          resolved_path, file_exists, file_size = result
  
          if not file_exists:
              return _create_new_file(ctx, resolved_path, edit_snippet)
          return await _apply_to_existing_file(ctx, backend, resolved_path, edit_snippet, file_size)
      except Exception as exc:
          apply_logging.log_apply_error(
              ctx.trace_id, ctx.started_at, file_path, edit_snippet, instruction, exc
          )
  
          if isinstance(exc, openai.APIError):
              logger.warning(
                  "[%s] Apply API error for %s: %s",
                  ctx.trace_id,
                  file_path,
                  exc,
              )
              return errors.openai_error_to_recoverable(
                  exc, file_path, instruction, ctx.trace_id, ctx.elapsed_ms()
              )
  
          if isinstance(exc, ValueError):
              logger.warning(
                  "[%s] API response parsing error for %s: %s",
                  ctx.trace_id,
                  file_path,
                  exc,
              )
              return errors.recoverable_error(
                  "API_INVALID_RESPONSE",
                  str(exc),
                  file_path,
                  instruction,
                  ctx.trace_id,
                  ctx.elapsed_ms(),
              )
  
          if isinstance(exc, ApplyError):
              logger.warning(
                  "[%s] Apply error (%s) for %s: %s",
                  ctx.trace_id,
                  exc.error_code,
                  file_path,
                  exc.message,
              )
              return errors.recoverable_error(
                  exc.error_code, exc.message, file_path, instruction, ctx.trace_id, ctx.elapsed_ms()
              )
  
          if isinstance(exc, PermissionError):
              logger.warning("[%s] Permission error for %s: %s", ctx.trace_id, file_path, exc)
              return errors.recoverable_error(
                  "PERMISSION_ERROR",
                  f"Permission denied: {exc}",
                  file_path,
                  instruction,
                  ctx.trace_id,
                  ctx.elapsed_ms(),
              )
  
          if isinstance(exc, OSError):
              errno_info = f"errno={exc.errno}" if exc.errno else ""
              strerror = exc.strerror or str(exc)
              logger.warning("[%s] Filesystem error for %s: %s", ctx.trace_id, file_path, exc)
              return errors.recoverable_error(
                  "FS_ERROR",
                  f"Filesystem error ({type(exc).__name__}, {errno_info}): {strerror}",
                  file_path,
                  instruction,
                  ctx.trace_id,
                  ctx.elapsed_ms(),
              )
  
          logger.error("[%s] Apply failed for %s: %s", ctx.trace_id, file_path, exc)
          return errors.recoverable_error(
              "INTERNAL_ERROR",
              f"Unexpected error ({type(exc).__name__}): {exc}",
              file_path,
              instruction,
              ctx.trace_id,
              ctx.elapsed_ms(),
          )

• src/relace_mcp/server.py:150-156 (registration)

  In build_server(), calls register_tools(mcp, config) which internally registers the fast_apply handler via decorator.

  mcp = FastMCP("Relace Fast Apply MCP")
  
  # Register middleware to handle MCP notifications (e.g., roots/list_changed)
  mcp.add_middleware(RootsMiddleware())
  
  register_tools(mcp, config)
  return mcp

• src/relace_mcp/tools/__init__.py:224-277 (schema)

  MCP resource providing tool list including schema-like metadata for fast_apply (id, name, description). The actual input schema is auto-derived from handler function signature.

  @mcp.resource("relace://tools_list", mime_type="application/json")
  def tools_list() -> list[dict[str, Any]]:
      """List all available tools with their status."""
      tools = [
          {
              "id": "fast_apply",
              "name": "Fast Apply",
              "description": "Edit or create files using fuzzy matching",
              "enabled": True,
          },
          {
              "id": "fast_search",
              "name": "Fast Search",
              "description": "Agentic search over local codebase",
              "enabled": True,
          },
      ]
      if RELACE_CLOUD_TOOLS:
          tools.extend(
              [
                  {
                      "id": "cloud_sync",
                      "name": "Cloud Sync",
                      "description": "Upload codebase for semantic indexing",
                      "enabled": True,
                  },
                  {
                      "id": "cloud_search",
                      "name": "Cloud Search",
                      "description": "Semantic code search using AI embeddings",
                      "enabled": True,
                  },
                  {
                      "id": "cloud_clear",
                      "name": "Cloud Clear",
                      "description": "Delete cloud repository and sync state",
                      "enabled": True,
                  },
                  {
                      "id": "cloud_list",
                      "name": "Cloud List",
                      "description": "List all repositories in Relace Cloud",
                      "enabled": True,
                  },
                  {
                      "id": "cloud_info",
                      "name": "Cloud Info",
                      "description": "Get sync status for current repository",
                      "enabled": True,
                  },
              ]
          )
      return tools