mcp: Instructions file for GitHub Copilot

Copilot Instructions

Project Overview

mcp is a Rust CLI that turns MCP (Model Context Protocol) servers into terminal commands. It supports stdio and HTTP transports, a proxy/gateway mode, server registry, audit logging, and ACL-based auth.

Tech Stack

• Language: Rust (edition 2021)
• Async runtime: Tokio (full features)
• HTTP: Axum (server), Reqwest with rustls-tls (client)
• Serialization: Serde + serde_json
• Error handling: anyhow::Result throughout
• Storage: chrondb for persistent state
• Tests: built-in #[cfg(test)] modules, tempfile for test fixtures

Code Style & Conventions

• No #[allow(dead_code)] — wire it up or delete it.
• Functions do one thing. Max ~50 lines. Max 3 levels of nesting.
• Comments explain why, not what.
• No unnecessary abstractions — solve the actual problem, not a hypothetical one.
• Zero unsafe code — all concurrency through safe abstractions.

Error Handling

• All functions return anyhow::Result<T>. No custom error types.
• Use .context("msg")? or .with_context(|| format!("msg {var}"))? to add context on propagation.
• Use bail!("msg") for early returns with error.
• Use .map_err(|e| anyhow::anyhow!("msg: {e:?}")) only when wrapping external library errors that don't implement std::error::Error.
• Never silently swallow errors — at minimum log with eprintln!.

Async Patterns

• All async via Tokio. Entry point is #[tokio::main].
• Interior mutability with Arc<Mutex<T>> or Arc<RwLock<T>> for shared state across tasks.
• Bounded mpsc::channel for task communication, oneshot for request-response matching.
• tokio::spawn for background tasks (readers, writers). spawn_blocking for sync-heavy work (db writes).
• Timeouts via tokio::time::timeout(Duration, future) — never block indefinitely.

Serialization

• Derive order: #[derive(Debug, Serialize, Deserialize, Clone)].
• #[serde(rename = "camelCase")] for protocol fields matching JSON-RPC/MCP spec.
• #[serde(skip_serializing_if = "Option::is_none")] on all Option fields for compact JSON.
• #[serde(default)] on optional deserialization fields.
• #[serde(untagged)] for config enums with variant ordering (serde tries in declaration order).