feat: add file editing tools for all backends

README.md

@@ -19,7 +19,7 @@ When AI agents write code, they need to run it somewhere. Today that means your
 
 The [devcontainer spec](https://containers.dev/) already defines reproducible, container-based dev environments. Every major project ships a `.devcontainer/devcontainer.json`. But AI agents can't use them — until now.
 
-`devcontainer-mcp` exposes **33 MCP tools** that let any AI agent:
+`devcontainer-mcp` exposes **45 MCP tools** that let any AI agent:
 
 1. **Spin up** a dev container from any repo — locally, on a cloud VM, or in Codespaces
 2. **Run commands** inside the container — builds, tests, linting, anything
@@ -98,7 +98,7 @@ Codespaces tools require an auth handle (e.g. `"github-aniongithub"`). The MCP s
 
 Supported providers: **GitHub**, **AWS**, **Azure**, **GCP**, **Kubernetes**
 
-## MCP Tools (33 total)
+## MCP Tools (45 total)
 
 ### Auth (4 tools)
 
@@ -109,7 +109,7 @@ Supported providers: **GitHub**, **AWS**, **Azure**, **GCP**, **Kubernetes**
 | `auth_select` | Switch the active account for a provider |
 | `auth_logout` | Revoke credentials for an account |
 
-### DevPod (15 tools)
+### DevPod (19 tools)
 
 | Tool | Description |
 |------|-------------|
@@ -128,8 +128,12 @@ Supported providers: **GitHub**, **AWS**, **Azure**, **GCP**, **Kubernetes**
 | `devpod_context_use` | Switch to a different context |
 | `devpod_container_inspect` | Docker inspect — labels, ports, mounts, state |
 | `devpod_container_logs` | Stream container logs via Docker API |
+| `devpod_file_read` | Read file content with optional line range |
+| `devpod_file_write` | Create or overwrite a file (auto-creates parent dirs) |
+| `devpod_file_edit` | Surgical string replacement — old_str → new_str |
+| `devpod_file_list` | List directory contents (non-hidden, 2 levels deep) |
 
-### devcontainer CLI (7 tools)
+### devcontainer CLI (11 tools)
 
 | Tool | Description |
 |------|-------------|
@@ -140,8 +144,12 @@ Supported providers: **GitHub**, **AWS**, **Azure**, **GCP**, **Kubernetes**
 | `devcontainer_stop` | Stop a dev container (via Docker API) |
 | `devcontainer_remove` | Remove a dev container and its resources |
 | `devcontainer_status` | Get dev container state by workspace folder |
+| `devcontainer_file_read` | Read file content with optional line range |
+| `devcontainer_file_write` | Create or overwrite a file (auto-creates parent dirs) |
+| `devcontainer_file_edit` | Surgical string replacement — old_str → new_str |
+| `devcontainer_file_list` | List directory contents (non-hidden, 2 levels deep) |
 
-### GitHub Codespaces (7 tools) — require `auth` handle
+### GitHub Codespaces (11 tools) — require `auth` handle
 
 | Tool | Description |
 |------|-------------|
@@ -152,6 +160,10 @@ Supported providers: **GitHub**, **AWS**, **Azure**, **GCP**, **Kubernetes**
 | `codespaces_delete` | Delete a codespace |
 | `codespaces_view` | View detailed codespace info (state, machine, config) |
 | `codespaces_ports` | List forwarded ports with visibility and URLs |
+| `codespaces_file_read` | Read file content with optional line range |
+| `codespaces_file_write` | Create or overwrite a file (auto-creates parent dirs) |
+| `codespaces_file_edit` | Surgical string replacement — old_str → new_str |
+| `codespaces_file_list` | List directory contents (non-hidden, 2 levels deep) |
 
 ## MCP Server Configuration
 

SKILL.md

@@ -35,6 +35,18 @@ tools:
   - codespaces_delete
   - codespaces_view
   - codespaces_ports
+  - devpod_file_read
+  - devpod_file_write
+  - devpod_file_edit
+  - devpod_file_list
+  - devcontainer_file_read
+  - devcontainer_file_write
+  - devcontainer_file_edit
+  - devcontainer_file_list
+  - codespaces_file_read
+  - codespaces_file_write
+  - codespaces_file_edit
+  - codespaces_file_list
 ---
 
 # DevContainer MCP Skill
@@ -163,3 +175,46 @@ If `devpod_up`, `devcontainer_up`, or `codespaces_create` returns errors:
 - ✅ DO ask the user which account/machine type to use
 - ✅ DO use `devpod_ssh`, `devcontainer_exec`, or `codespaces_ssh` for everything
 - ✅ DO check `.devcontainer/devcontainer.json` first
+
+## File Operations
+
+**All backends support built-in file operations — no need to construct shell commands.**
+
+These tools mirror familiar editing tools (read, write, edit, list) and handle escaping, encoding, and directory creation automatically.
+
+### Reading files
+```
+devpod_file_read(workspace: "my-ws", path: "/workspaces/project/src/main.rs")
+devcontainer_file_read(workspace_folder: "/path/to/project", path: "/workspaces/project/src/main.rs")
+codespaces_file_read(auth: "github-user", codespace: "name", path: "src/main.rs")
+```
+Supports optional `start_line` and `end_line` for reading specific ranges.
+
+### Writing files
+```
+devpod_file_write(workspace: "my-ws", path: "/workspaces/project/new_file.rs", content: "fn main() {}")
+devcontainer_file_write(workspace_folder: "/path/to/project", path: "new_file.rs", content: "fn main() {}")
+codespaces_file_write(auth: "github-user", codespace: "name", path: "src/new.rs", content: "...")
+```
+Creates parent directories automatically.
+
+### Editing files (surgical replacement)
+```
+devpod_file_edit(workspace: "my-ws", path: "src/main.rs", old_str: "fn old()", new_str: "fn new()")
+devcontainer_file_edit(workspace_folder: "/path/to/project", path: "src/lib.rs", old_str: "v1", new_str: "v2")
+codespaces_file_edit(auth: "github-user", codespace: "name", path: "src/lib.rs", old_str: "TODO", new_str: "DONE")
+```
+`old_str` must match exactly once in the file. Include surrounding context to make it unique.
+
+### Listing directories
+```
+devpod_file_list(workspace: "my-ws", path: "/workspaces/project/src")
+devcontainer_file_list(workspace_folder: "/path/to/project", path: "src")
+codespaces_file_list(auth: "github-user", codespace: "name", path: ".")
+```
+Shows non-hidden files up to 2 levels deep.
+
+### When to use file tools vs exec/ssh
+- ✅ **Use file tools** for reading, writing, and editing source files
+- ✅ **Use exec/ssh** for running builds, tests, and commands
+- ❌ **Don't** construct `sed`, `cat`, or `echo` commands via exec for file editing

crates/devcontainer-mcp-core/Cargo.toml

@@ -15,3 +15,4 @@ bollard = { workspace = true }
 tracing = { workspace = true }
 futures-util = "0.3"
 async-trait = "0.1"
+base64 = "0.22"

crates/devcontainer-mcp-core/src/codespaces.rs

@@ -107,3 +107,67 @@ pub async fn ports(env: &HashMap<String, String>, codespace: &str) -> Result<Cli
     let args = vec!["ports", "-c", codespace, "--json", PORT_FIELDS];
     run_gh_cs(&args, true, Some(env)).await
 }
+
+// ---------------------------------------------------------------------------
+// File operations
+// ---------------------------------------------------------------------------
+
+/// Read a file from a Codespace.
+pub async fn file_read(
+    env: &HashMap<String, String>,
+    codespace: &str,
+    path: &str,
+) -> Result<CliOutput> {
+    let cmd = crate::file_ops::read_file_command(path);
+    ssh_exec(env, codespace, &cmd).await
+}
+
+/// Write (create or overwrite) a file in a Codespace.
+pub async fn file_write(
+    env: &HashMap<String, String>,
+    codespace: &str,
+    path: &str,
+    content: &str,
+) -> Result<CliOutput> {
+    let cmd = crate::file_ops::write_file_command(path, content);
+    ssh_exec(env, codespace, &cmd).await
+}
+
+/// Surgical edit: replace exactly one occurrence of `old_str` with `new_str`.
+pub async fn file_edit(
+    env: &HashMap<String, String>,
+    codespace: &str,
+    path: &str,
+    old_str: &str,
+    new_str: &str,
+) -> Result<String> {
+    let read_output = file_read(env, codespace, path).await?;
+    if read_output.exit_code != 0 {
+        return Err(crate::error::Error::FileRead(format!(
+            "Failed to read {path}: {}",
+            read_output.stderr.trim()
+        )));
+    }
+
+    let modified = crate::file_ops::apply_edit(&read_output.stdout, old_str, new_str)?;
+
+    let write_output = file_write(env, codespace, path, &modified).await?;
+    if write_output.exit_code != 0 {
+        return Err(crate::error::Error::FileEdit(format!(
+            "Failed to write {path}: {}",
+            write_output.stderr.trim()
+        )));
+    }
+
+    Ok(format!("Edit applied to {path}"))
+}
+
+/// List directory contents in a Codespace.
+pub async fn file_list(
+    env: &HashMap<String, String>,
+    codespace: &str,
+    path: &str,
+) -> Result<CliOutput> {
+    let cmd = crate::file_ops::list_dir_command(path);
+    ssh_exec(env, codespace, &cmd).await
+}

crates/devcontainer-mcp-core/src/devcontainer.rs

@@ -94,3 +94,63 @@ pub async fn status(workspace_folder: &str) -> Result<Option<docker::ContainerIn
     let client = docker::connect()?;
     docker::find_container_by_local_folder(&client, workspace_folder).await
 }
+
+// ---------------------------------------------------------------------------
+// File operations
+// ---------------------------------------------------------------------------
+
+/// Read a file from a dev container.
+pub async fn file_read(
+    workspace_folder: &str,
+    path: &str,
+) -> Result<CliOutput> {
+    let cmd = crate::file_ops::read_file_command(path);
+    exec(workspace_folder, "sh", &["-c", &cmd]).await
+}
+
+/// Write (create or overwrite) a file in a dev container.
+pub async fn file_write(
+    workspace_folder: &str,
+    path: &str,
+    content: &str,
+) -> Result<CliOutput> {
+    let cmd = crate::file_ops::write_file_command(path, content);
+    exec(workspace_folder, "sh", &["-c", &cmd]).await
+}
+
+/// Surgical edit: replace exactly one occurrence of `old_str` with `new_str`.
+pub async fn file_edit(
+    workspace_folder: &str,
+    path: &str,
+    old_str: &str,
+    new_str: &str,
+) -> Result<String> {
+    let read_output = file_read(workspace_folder, path).await?;
+    if read_output.exit_code != 0 {
+        return Err(crate::error::Error::FileRead(format!(
+            "Failed to read {path}: {}",
+            read_output.stderr.trim()
+        )));
+    }
+
+    let modified = crate::file_ops::apply_edit(&read_output.stdout, old_str, new_str)?;
+
+    let write_output = file_write(workspace_folder, path, &modified).await?;
+    if write_output.exit_code != 0 {
+        return Err(crate::error::Error::FileEdit(format!(
+            "Failed to write {path}: {}",
+            write_output.stderr.trim()
+        )));
+    }
+
+    Ok(format!("Edit applied to {path}"))
+}
+
+/// List directory contents in a dev container.
+pub async fn file_list(
+    workspace_folder: &str,
+    path: &str,
+) -> Result<CliOutput> {
+    let cmd = crate::file_ops::list_dir_command(path);
+    exec(workspace_folder, "sh", &["-c", &cmd]).await
+}

crates/devcontainer-mcp-core/src/devpod.rs

@@ -167,3 +167,67 @@ pub async fn import(args: &[&str]) -> Result<CliOutput> {
 pub async fn export(workspace: &str) -> Result<CliOutput> {
     run_devpod(&["export", workspace], false).await
 }
+
+// ---------------------------------------------------------------------------
+// File operations
+// ---------------------------------------------------------------------------
+
+/// Read a file from a DevPod workspace.
+pub async fn file_read(
+    workspace: &str,
+    path: &str,
+    user: Option<&str>,
+) -> Result<CliOutput> {
+    let cmd = crate::file_ops::read_file_command(path);
+    ssh_exec(workspace, &cmd, user, None).await
+}
+
+/// Write (create or overwrite) a file in a DevPod workspace.
+pub async fn file_write(
+    workspace: &str,
+    path: &str,
+    content: &str,
+    user: Option<&str>,
+) -> Result<CliOutput> {
+    let cmd = crate::file_ops::write_file_command(path, content);
+    ssh_exec(workspace, &cmd, user, None).await
+}
+
+/// Surgical edit: replace exactly one occurrence of `old_str` with `new_str`.
+pub async fn file_edit(
+    workspace: &str,
+    path: &str,
+    old_str: &str,
+    new_str: &str,
+    user: Option<&str>,
+) -> Result<String> {
+    let read_output = file_read(workspace, path, user).await?;
+    if read_output.exit_code != 0 {
+        return Err(Error::FileRead(format!(
+            "Failed to read {path}: {}",
+            read_output.stderr.trim()
+        )));
+    }
+
+    let modified = crate::file_ops::apply_edit(&read_output.stdout, old_str, new_str)?;
+
+    let write_output = file_write(workspace, path, &modified, user).await?;
+    if write_output.exit_code != 0 {
+        return Err(Error::FileEdit(format!(
+            "Failed to write {path}: {}",
+            write_output.stderr.trim()
+        )));
+    }
+
+    Ok(format!("Edit applied to {path}"))
+}
+
+/// List directory contents in a DevPod workspace.
+pub async fn file_list(
+    workspace: &str,
+    path: &str,
+    user: Option<&str>,
+) -> Result<CliOutput> {
+    let cmd = crate::file_ops::list_dir_command(path);
+    ssh_exec(workspace, &cmd, user, None).await
+}

crates/devcontainer-mcp-core/src/error.rs

@@ -30,6 +30,12 @@ pub enum Error {
     #[error("DevPod command failed (exit code {exit_code}): {stderr}")]
     DevPodCommand { exit_code: i32, stderr: String },
 
+    #[error("File read error: {0}")]
+    FileRead(String),
+
+    #[error("File edit error: {0}")]
+    FileEdit(String),
+
     #[error("IO error: {0}")]
     Io(#[from] std::io::Error),