arch-mcp

Instructions

Implementation Reference

• src/arch_ops_server/pacman.py:771-861 (handler)

  The core handler function that implements the search_package_files tool logic using pacman -F to query the file database and parse results into structured output with package, repository, version, and file paths.
  async def search_package_files(filename_pattern: str) -> Dict[str, Any]: """ Search for files across all packages. Args: filename_pattern: Filename pattern to search for Returns: Dict with matching files and packages """ if not IS_ARCH: return create_error_response( "NotSupported", "Package file search is only available on Arch Linux" ) if not check_command_exists("pacman"): return create_error_response( "CommandNotFound", "pacman command not found" ) logger.info(f"Searching for files matching: {filename_pattern}") try: # First check if file database is synced exit_code, stdout, stderr = await run_command( ["pacman", "-F", filename_pattern], timeout=30, check=False ) if exit_code == 1 and "database" in stderr.lower(): return create_error_response( "DatabaseNotSynced", "Package file database not synced. Run 'sudo pacman -Fy' first.", "File database needs to be synchronized before searching" ) if exit_code != 0 and not stdout.strip(): logger.info(f"No files found matching {filename_pattern}") return { "pattern": filename_pattern, "match_count": 0, "matches": [] } # Parse output: "repository/package version\n path/to/file" matches = [] current_package = None for line in stdout.strip().split('\n'): if not line.strip(): continue if line.startswith(' '): # This is a file path if current_package: file_path = line.strip() matches.append({ "package": current_package["package"], "repository": current_package["repository"], "version": current_package["version"], "file": file_path }) else: # This is a package line: "repository/package version" parts = line.split() if len(parts) >= 2: repo_pkg = parts[0].split('/') if len(repo_pkg) == 2: current_package = { "repository": repo_pkg[0], "package": repo_pkg[1], "version": parts[1] } logger.info(f"Found {len(matches)} files matching {filename_pattern}") return { "pattern": filename_pattern, "match_count": len(matches), "matches": matches } except Exception as e: logger.error(f"File search failed: {e}") return create_error_response( "CommandError", f"Failed to search package files: {str(e)}" )
• src/arch_ops_server/server.py:794-807 (schema)

  The input JSON schema for the search_package_files tool, defining filename_pattern as a required string parameter.
  Tool( name="search_package_files", description="[ORGANIZATION] Search for files across all packages in repositories. Requires package database sync (pacman -Fy). Only works on Arch Linux.", inputSchema={ "type": "object", "properties": { "filename_pattern": { "type": "string", "description": "File name or pattern to search for (e.g., 'vim' or '*.service')" } }, "required": ["filename_pattern"] } ),
• src/arch_ops_server/server.py:1274-1280 (registration)

  Registration in the MCP server's call_tool handler that invokes the search_package_files function with the provided arguments and formats the result as JSON text content.
  elif name == "search_package_files": if not IS_ARCH: return [TextContent(type="text", text="Error: search_package_files only available on Arch Linux systems")] filename_pattern = arguments["filename_pattern"] result = await search_package_files(filename_pattern) return [TextContent(type="text", text=json.dumps(result, indent=2))]
• src/arch_ops_server/tool_metadata.py:242-248 (helper)

  ToolMetadata definition providing category, platform, permission, workflow, and related tools information for search_package_files.
  "search_package_files": ToolMetadata( name="search_package_files", category="organization", platform="arch", permission="read", workflow="search", related_tools=["list_package_files", "find_package_owner"],