Default io-uring and add docs.rs build config

Author: houseme

.cargo/config.toml

@@ -20,6 +20,7 @@
 # Enable Tokio unstable features required by dial9-tokio-telemetry for runtime tracing.
 # See: https://docs.rs/tokio/latest/tokio/#unstable-features
 rustflags = ["--cfg", "tokio_unstable"]
+rustdocflags = ["--cfg", "tokio_unstable"]
 
 # Enable frame pointers for CPU profiling (Linux only, optional but recommended)
 # Uncomment the following line for better CPU profiling data

.github/workflows/ci.yml

@@ -26,6 +26,7 @@ permissions:
 
 env:
   CARGO_TERM_COLOR: always
+  RUSTFLAGS: --cfg tokio_unstable
 
 concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
@@ -68,7 +69,12 @@ jobs:
         uses: Swatinem/rust-cache@v2
 
       - name: Run clippy
-        run: cargo clippy --all-targets --all-features --locked -- -D warnings
+        run: cargo clippy --all-targets --locked -- -D warnings
+
+      - name: Run clippy (io-uring)
+        env:
+          RUSTFLAGS: --cfg tokio_unstable
+        run: cargo clippy --all-targets --locked --features io-uring -- -D warnings
 
   test:
     name: Test
@@ -103,3 +109,34 @@ jobs:
 
       - name: Build release binary
         run: cargo build --release --locked -p rustfs-mcp
+
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        profile: [default, io-uring]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Build docs (default)
+        if: matrix.profile == 'default'
+        env:
+          RUSTDOCFLAGS: --cfg docsrs --cfg tokio_unstable -D warnings
+        run: cargo +nightly doc --no-deps --locked
+
+      - name: Build docs (io-uring)
+        if: matrix.profile == 'io-uring'
+        env:
+          RUSTFLAGS: --cfg tokio_unstable
+          RUSTDOCFLAGS: --cfg docsrs --cfg tokio_unstable -D warnings
+        run: cargo +nightly doc --no-deps --locked --features io-uring

.github/workflows/publish.yml

@@ -25,6 +25,7 @@ permissions:
 
 env:
   CARGO_TERM_COLOR: always
+  RUSTFLAGS: --cfg tokio_unstable
 
 concurrency:
   group: publish-${{ github.workflow }}-${{ github.ref }}
@@ -67,7 +68,12 @@ jobs:
         uses: Swatinem/rust-cache@v2
 
       - name: Run clippy
-        run: cargo clippy --all-targets --all-features --locked -- -D warnings
+        run: cargo clippy --all-targets --locked -- -D warnings
+
+      - name: Run clippy (io-uring)
+        env:
+          RUSTFLAGS: --cfg tokio_unstable
+        run: cargo clippy --all-targets --locked --features io-uring -- -D warnings
 
   test:
     name: Test
@@ -103,11 +109,42 @@ jobs:
       - name: Build release binary
         run: cargo build --release --locked -p rustfs-mcp
 
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        profile: [default, io-uring]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Build docs (default)
+        if: matrix.profile == 'default'
+        env:
+          RUSTDOCFLAGS: --cfg docsrs --cfg tokio_unstable -D warnings
+        run: cargo +nightly doc --no-deps --locked
+
+      - name: Build docs (io-uring)
+        if: matrix.profile == 'io-uring'
+        env:
+          RUSTFLAGS: --cfg tokio_unstable
+          RUSTDOCFLAGS: --cfg docsrs --cfg tokio_unstable -D warnings
+        run: cargo +nightly doc --no-deps --locked --features io-uring
+
   publish:
     name: Publish to crates.io
     runs-on: ubuntu-latest
     timeout-minutes: 15
-    needs: [fmt, clippy, test, build]
+    needs: [fmt, clippy, test, build, docs]
     if: startsWith(github.ref, 'refs/tags/v')
     steps:
       - name: Checkout repository

Cargo.toml

@@ -26,13 +26,24 @@ keywords = ["mcp", "s3", "aws", "rustfs", "server"]
 categories = ["development-tools", "web-programming"]
 documentation = "https://docs.rs/rustfs-mcp/latest/rustfs_mcp/"
 
+[package.metadata.docs.rs]
+default-target = "x86_64-unknown-linux-gnu"
+targets = ["x86_64-unknown-linux-gnu", "aarch64-unknown-linux-gnu"]
+rustc-args = ["--cfg", "tokio_unstable"]
+rustdoc-args = ["--cfg", "docsrs", "--cfg", "tokio_unstable"]
+
+[features]
+default = ["io-uring"]
+io-uring = ["tokio/io-uring"]
+
 [[bin]]
 name = "rustfs-mcp"
 path = "src/main.rs"
 
 [lints.rust]
 unsafe_code = "warn"
 unused = "warn"
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tokio_unstable)'] }
 
 [lints.clippy]
 all = "warn"
@@ -45,7 +56,7 @@ aws-sdk-s3 = { version = "1.129.0", default-features = false, features = ["sigv4
 aws-smithy-http-client = { version = "1.1.12", default-features = false, features = ["default-client", "rustls-aws-lc"] }
 
 # Async runtime and utilities
-tokio = { version = "1.52.1", default-features = false, features = ["fs", "io-std", "io-util", "macros", "rt-multi-thread", "io-uring"] }
+tokio = { version = "1.52.1", default-features = false, features = ["fs", "io-std", "io-util", "macros", "rt-multi-thread"] }
 
 # MCP SDK with macros support
 rmcp = { version = "1.5.0", default-features = false, features = ["server", "transport-io", "macros"] }

Dockerfile

@@ -16,9 +16,17 @@ FROM rust:1.93-bookworm AS builder
 
 WORKDIR /build
 
+ARG ENABLE_IO_URING=1
+ENV RUSTFLAGS="--cfg tokio_unstable"
+ENV RUSTDOCFLAGS="--cfg tokio_unstable"
+
 # Copy project and build a reproducible release binary.
 COPY . .
-RUN cargo build --release --locked -p rustfs-mcp
+RUN if [ "$ENABLE_IO_URING" = "1" ]; then \
+      cargo build --release --locked -p rustfs-mcp; \
+    else \
+      cargo build --release --locked --no-default-features -p rustfs-mcp; \
+    fi
 
 FROM debian:bookworm-slim AS runtime
 

README.md

@@ -8,6 +8,7 @@
 
 <p align="center">
   <a href="https://github.com/rustfs/rustfs/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/rustfs/rustfs/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://docs.rs/rustfs-mcp"><img alt="docs.rs" src="https://img.shields.io/docsrs/rustfs-mcp" /></a>
   <a href="https://docs.rustfs.com/">📖 Documentation</a>
   <a href="https://github.com/rustfs/rustfs/issues">🐛 Bug Reports</a>
   <a href="https://github.com/rustfs/rustfs/discussions">💬 Discussions</a>
@@ -54,6 +55,20 @@ cargo build --release -p rustfs-mcp
 ./target/release/rustfs-mcp
 ```
 
+### Optional: Enable io-uring
+
+`io-uring` is enabled by default in this crate. Tokio requires unstable cfg for this mode:
+
+```bash
+RUSTFLAGS="--cfg tokio_unstable" cargo build --release -p rustfs-mcp
+```
+
+To explicitly disable it:
+
+```bash
+cargo build --release -p rustfs-mcp --no-default-features
+```
+
 ## ⚙️ Configuration
 
 ### Environment Variables

src/config.rs

@@ -16,7 +16,7 @@ use anyhow::Result;
 use clap::Parser;
 use tracing::info;
 
-/// Configuration for RustFS MCP Server
+/// Configuration for `rustfs-mcp`.
 #[derive(Parser, Debug, Clone)]
 #[command(
     name = "rustfs-mcp-server",
@@ -98,10 +98,12 @@ pub struct Config {
 }
 
 impl Config {
+    /// Parse configuration from command-line arguments and environment variables.
     pub fn new() -> Self {
         Config::parse()
     }
 
+    /// Validate required credentials are present.
     pub fn validate(&self) -> Result<()> {
         if self.access_key_id.is_none() {
             anyhow::bail!(
@@ -118,18 +120,21 @@ impl Config {
         Ok(())
     }
 
+    /// Return validated AWS access key id.
     pub fn access_key_id(&self) -> &str {
         self.access_key_id
             .as_ref()
             .expect("Access key ID should be validated")
     }
 
+    /// Return validated AWS secret access key.
     pub fn secret_access_key(&self) -> &str {
         self.secret_access_key
             .as_ref()
             .expect("Secret access key should be validated")
     }
 
+    /// Log a redacted configuration summary.
     pub fn log_configuration(&self) {
         let access_key_display = self
             .access_key_id

src/lib.rs

@@ -12,20 +12,43 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#![cfg_attr(docsrs, feature(doc_cfg))]
+//! RustFS MCP server library.
+//!
+//! This crate exposes a Model Context Protocol (MCP) server that provides
+//! S3-compatible storage operations, plus reusable configuration and client
+//! primitives for embedding into other Rust applications.
+//!
+//! # Optional features
+//!
+//! - `io-uring`: Enables Tokio's `io-uring` integration. This requires building
+//!   with `RUSTFLAGS="--cfg tokio_unstable"`.
+
+#[cfg(all(feature = "io-uring", not(tokio_unstable)))]
+compile_error!(
+    "feature `io-uring` requires cfg `tokio_unstable` (set RUSTFLAGS/RUSTDOCFLAGS to \"--cfg tokio_unstable\")"
+);
+
+/// Command-line and environment configuration parsing/validation.
 pub mod config;
+/// S3 client wrapper and operation/result data types.
 pub mod s3_client;
+/// MCP server and tool handlers.
 pub mod server;
 
+/// Runtime configuration for the server.
 pub use config::Config;
+/// Bucket metadata and async S3 client wrapper.
 pub use s3_client::{BucketInfo, S3Client};
+/// MCP service implementation.
 pub use server::RustfsMcpServer;
 
 use anyhow::{Context, Result};
 use rmcp::ServiceExt;
 use tokio::io::{stdin, stdout};
 use tracing::info;
 
-/// Run the MCP server with the provided configuration
+/// Start the MCP server with an explicit [`Config`].
 pub async fn run_server_with_config(config: Config) -> Result<()> {
     info!("Starting RustFS MCP Server with provided configuration");
 
@@ -49,15 +72,17 @@ pub async fn run_server_with_config(config: Config) -> Result<()> {
     Ok(())
 }
 
-/// Run the MCP server with default configuration (from environment variables)
+/// Start the MCP server with [`Config::default`].
 pub async fn run_server() -> Result<()> {
     info!("Starting RustFS MCP Server with default configuration");
 
     let config = Config::default();
     run_server_with_config(config).await
 }
 
-/// Validate environment configuration (legacy function for backward compatibility)
+/// Validate required AWS credentials in environment variables.
+///
+/// This function is kept for backward compatibility.
 pub fn validate_environment() -> Result<()> {
     use std::env;