Ops MCP Server

Instructions

Implementation Reference

• mcp_server/tools/azdo_tools.py:251-322 (handler)

  Main browse_repo handler function that browses files and folders in a Git repository by making an API call to Azure DevOps and returning a formatted directory listing with folders and files separated, including example commands to drill down further.

  def browse_repo(
      repo_name: str,
      path: str = "/",
      branch: str | None = None,
      project: str | None = None,
  ) -> str:
      """
      Browse files and folders in a Git repository — like a directory listing.
  
      USE THIS TOOL when the user wants to see what files are in a repo,
      explore folder structure, or find a specific file path.
  
      Args:
          repo_name: Repository name (from list_repos).
          path: Folder path to browse (default '/' for root). Use forward slashes.
          branch: Branch name (default: repo's default branch).
          project: Project name (default from config).
  
      Returns a directory listing with file/folder names and paths.
      Use read_repo_file(repo_name='...', path='...') to read a file's content.
      """
      url = f"{_project_url(project)}/_apis/git/repositories/{repo_name}/items"
      params: dict[str, str] = {
          "scopePath": path,
          "recursionLevel": "oneLevel",
      }
      if branch:
          params["versionDescriptor.version"] = branch
          params["versionDescriptor.versionType"] = "branch"
  
      data = _api_get(url, params=params)
  
      if isinstance(data, dict) and "error" in data:
          return data["error"]
  
      items = data.get("value", []) if isinstance(data, dict) else []
      if not items:
          return f"No items found at path '{path}' in repo '{repo_name}'."
  
      # Separate folders and files, skip the root entry itself
      folders = []
      files = []
      for item in items:
          item_path = item.get("path", "?")
          if item_path == path and item.get("isFolder", False):
              continue  # skip the directory entry itself
          if item.get("isFolder", False):
              folders.append(item)
          else:
              files.append(item)
  
      lines = [f"\U0001f4c2 **{repo_name}** \u2014 `{path}`\n"]
  
      if folders:
          lines.append(f"**Folders ({len(folders)}):**")
          for f in sorted(folders, key=lambda x: x.get("path", "")):
              folder_path = f.get("path", "?")
              folder_name = folder_path.rsplit("/", 1)[-1]
              lines.append(f"  \U0001f4c1 {folder_name}/")
              lines.append(f"     \u2192 `browse_repo(repo_name='{repo_name}', path='{folder_path}')`")
          lines.append("")
  
      if files:
          lines.append(f"**Files ({len(files)}):**")
          for f in sorted(files, key=lambda x: x.get("path", "")):
              file_path = f.get("path", "?")
              file_name = file_path.rsplit("/", 1)[-1]
              lines.append(f"  \U0001f4c4 {file_name}")
              lines.append(f"     \u2192 `read_repo_file(repo_name='{repo_name}', path='{file_path}')`")
          lines.append("")
  
      return "\n".join(lines)

• mcp_server/main.py:154-163 (registration)

  Import statement that imports browse_repo from the azdo_tools module into the main server file.

  from mcp_server.tools.azdo_tools import (              # noqa: E402
      list_repos,
      browse_repo,
      browse_repo_recursive,
      read_repo_file,
      get_current_sprint,
      get_sprint_work_items,
      get_work_item_details,
      get_backlog,
  )

• mcp_server/main.py:218-225 (registration)

  Tool registration with MCP - registers browse_repo as an available tool in the MCP server.

  # ── Register Azure DevOps tools (8) ─────────────────────────────────────────
  
  mcp.tool()(list_repos)
  mcp.tool()(browse_repo)
  mcp.tool()(browse_repo_recursive)
  mcp.tool()(read_repo_file)
  mcp.tool()(get_current_sprint)
  mcp.tool()(get_sprint_work_items)

• mcp_server/tools/azdo_tools.py:62-65 (helper)

  Helper function _project_url that constructs the base URL for a project using the configured AZDO_BASE_URL and project name.

  def _project_url(project: str | None = None) -> str:
      """Build base URL for a project: {base}/{project}"""
      proj = project or AZDO_PROJECT
      return f"{AZDO_BASE_URL.rstrip('/')}/{proj}"

• mcp_server/tools/azdo_tools.py:75-93 (helper)

  Helper function _api_get that makes authenticated GET requests to the Azure DevOps REST API, handling errors and connection issues automatically.

  def _api_get(url: str, params: dict | None = None) -> dict[str, Any] | list:
      """GET request to Azure DevOps REST API. api-version is injected automatically."""
      err = validate_azuredevops()
      if err:
          return {"error": err}
  
      session = _get_session()
      params = dict(params or {})
      params.setdefault("api-version", API_VERSION)
  
      try:
          resp = session.get(url, params=params, timeout=30)
          if resp.status_code >= 400:
              return {"error": f"Azure DevOps API returned HTTP {resp.status_code}: {resp.text[:500]}"}
          return resp.json()
      except requests.exceptions.ConnectionError as exc:
          return {"error": f"Cannot connect to Azure DevOps at {AZDO_BASE_URL}. Is VPN connected? Error: {exc}"}
      except Exception as exc:
          return {"error": f"Azure DevOps API error: {exc}"}