🧭 Epic

Title: Sample MCP Server – Rust Implementation (“filesystem-server”)

Goal
Ship a self-contained, memory-safe Rust (Axum) MCP server that exposes a comprehensive file-system toolkit.
It illustrates:

• zero-unsafe Rust, fully clippy-clean
• MUSL-linked static binaries (~ 4 MB)
• scratch-based multi-arch Docker images (< 10 MB)
• pattern-matching edit engine with dry-run diffs
• a turnkey Helm chart for Kubernetes rollout

Repository root: mcp-servers/rust/filesystem-server

🧭 Type of Feature

• Developer tooling / sample code
• Language-SDK showcase

🛠 Tool Catalogue

🙋‍♂️ User Story 1 — Cargo Quick-Start

As a Rust developer
I want to run cargo run -- --roots /tmp,/var/www
So that I get an MCP endpoint on 0.0.0.0:8084 sandboxed to those roots.

✅ Acceptance Criteria

Scenario: Start filesystem-server via cargo run
Given Rust ≥1.77 and target x86_64-unknown-linux-musl installed
When I execute "cargo run -- --roots /tmp,/var/www"
Then GET /version returns JSON containing "filesystem-server"
And tools/list includes read_file, edit_file, list_directory

🙋‍♂️ User Story 2 — Static Scratch Docker Image

As a platform engineer
I want docker build . to produce an image ≤ 10 MB
So that deployments start fast and have minimal CVE surface.

✅ Acceptance Criteria

Scenario: Build static image
When I run "docker build -t filesystem-server:dev ."
Then image size ≤ 10 MB
And "docker run -p 8080:8080 filesystem-server:dev --roots /tmp --transport=http"
    responds 200 to POST tools/list

🙋‍♂️ User Story 3 — Helm Deployment

As a Kubernetes operator
I want a Helm chart with probes, resource limits, and configurable roots
So that I can roll out the server via helm install.

✅ Acceptance Criteria

Scenario: Install via Helm
Given a KinD cluster is running
When I execute "helm install fs mcp-servers/rust/filesystem-server/charts/filesystem-server \
               --set roots={/workspaces,/data}"
Then Deployment "fs-filesystem-server" becomes Ready
And GET /health on the service returns {"status":"healthy"}

🙋‍♂️ User Story 4 — Safe Edit with Dry-Run

As a cautious LLM agent
I want to call edit_file with dryRun=true first
So that I can inspect the git-style diff before applying changes.

✅ Acceptance Criteria

Scenario: Dry-run edit returns diff
Given file /tmp/demo.txt contains "hello world"
When I POST tools/call edit_file {path:"/tmp/demo.txt", edits:[{oldText:"world",newText:"MCP"}], dryRun:true}
Then result.diff contains "-hello world" and "+hello MCP"
And the underlying file is unchanged
When I repeat the call with dryRun:false
Then /tmp/demo.txt now contains "hello MCP"

📂 Filesystem Layout

filesystem-server/
├── Cargo.toml
├── Dockerfile
├── README.md
└── src/
    ├── main.rs            # Axum setup, CLI flags
    ├── rpc.rs             # JSON-RPC dispatcher
    ├── sandbox.rs         # Path-safety & root confinement
    ├── tools/
    │   ├── mod.rs
    │   ├── read.rs
    │   ├── write.rs
    │   ├── edit.rs
    │   ├── search.rs
    │   └── info.rs
    └── middleware/
        ├── auth.rs        # Optional Bearer token
        └── logging.rs

📂 Component Matrix

📋 Global Acceptance Checklist

• All four user-story scenarios pass.
• CI green (cargo clippy -D warnings, unit tests, coverage ≥ 90 %, cargo audit).
• Docker image ≤ 10 MB for amd64 & arm64.
• Helm chart deploys with custom roots and passes readiness / liveness probes.
• Auth middleware blocks unauthenticated requests when enabled.
• Image published to ghcr.io/mcp-gateway-labs; chart committed under charts/.

🔄 Roll-Out Plan

1. Scaffold repo mcp-servers/rust/filesystem-server with layout above.
2. Implement sandbox module + read_file, list_directory, health/version.
3. Add remaining tools (write, edit, search, info, move, create_directory).
4. Add optional Bearer-token middleware; integrate SSE transport if time permits.
5. Wire CI, Docker, Helm; verify acceptance tests.
6. Tag v0.1.0 and attach to Release 0.9.0 milestone.