tsafe-mcp 1.2.0

#![recursion_limit = "256"]

//! tsafe-mcp - bound MCP server for the Agent Authority Firewall.
//!
//! This crate provides the companion binary behind both `tsafe-mcp serve ...`
//! and the CLI normal form `tsafe mcp serve --profile <profile> --contract
//! <contract> --workdir <repo>`. A bound MCP process fixes one profile, one
//! authority contract, and one workdir at startup. Tool calls cannot switch
//! profile, contract, workdir, or secret scope at request time.
//!
//! Bound mode exposes safe command execution through three model-facing tools:
//! `show_exec_plan`, `run_contract_command`, and `tsafe_mcp_status`. Secret
//! material is not returned to the model. No-secret diagnostic contracts are
//! valid when the contract explicitly compiles to zero allowed and required
//! secrets while still enforcing target policy and audit behavior.
//!
//! Separate agent contexts should use separate server instance normal forms,
//! for example host entries named `tsafe-cordance` and `tsafe-cortex`, each
//! with its own profile, contract, workdir, and process.
//!
//! The library entry point [`run`] is called both from the standalone
//! `tsafe-mcp` binary (`src/main.rs`) and from the meta-crate shim
//! (`crates/tsafe/src/bin/tsafe_mcp.rs`).
//!
//! The runtime exposes five subcommands per design §5.2:
//! - `tsafe-mcp serve [...]`           — stdio JSON-RPC server (default subcommand)
//! - `tsafe-mcp install <host> [...]`  — write per-host MCP config
//! - `tsafe-mcp config <host> [...]`   — emit safe host config without writing
//! - `tsafe-mcp uninstall <host> [...]`— remove the entry
//! - `tsafe-mcp status`                — print binary version + resolved scope
//!
//! All other doctrine: bound MCP stance, ADR-003 agent IPC reuse, ADR-005 module
//! layout. See `docs/architecture/ADR-006-mcp-server.md` and
//! `docs/architecture/mcp-server-design.md`.

pub mod audit;
pub mod backend;
pub mod errors;
pub mod install;
pub mod server;
pub mod session;
pub mod tools;

use crate::errors::{McpError, McpErrorKind};
use crate::install::{InstallOpts, Scope};
use crate::server::MCP_PROTOCOL_VERSION;
use crate::session::{Session, SessionArgs};

const HELP: &str = "\
tsafe-mcp — first-party MCP server for tsafe

Usage:
  tsafe-mcp serve --profile <profile> --contract <contract> --workdir <path>
  tsafe-mcp config codex --name <name> --profile <profile> --contract <contract> --workdir <path>
  tsafe-mcp install <host> --profile <profile> [--allowed-keys <glob,glob>]
  tsafe-mcp uninstall <host> --profile <profile>
  tsafe-mcp status

Bound mode fixes one profile, one contract, one workdir at process startup.
It speaks stdio JSON-RPC to an MCP host. It does not return secret values to
the model; secret material may enter only the bounded child process environment
when a contract-authorized command is run.

Privacy:
  stdio JSON-RPC is local host IPC, not product telemetry. CloudEvents and audit
  receipts remain local/export-selected tsafe surfaces, separate from this MCP
  transport.

Tools in bound contract mode:
  show_exec_plan
  run_contract_command
  tsafe_mcp_status
";

/// Top-level subcommand parsed from `std::env::args()`.
#[derive(Debug)]
enum Subcommand {
    /// JSON-RPC server over stdio. Default when no subcommand is given.
    Serve(Vec<String>),
    /// Install / uninstall / status — diagnostic shells, no JSON-RPC.
    Install {
        host: String,
        rest: Vec<String>,
    },
    Config {
        host: String,
        rest: Vec<String>,
    },
    Uninstall {
        host: String,
        rest: Vec<String>,
    },
    Status,
    Help,
}

/// Process entry point. Parses argv, dispatches to the matching subcommand,
/// and exits the process with code 1 on error (same shape as
/// `tsafe-agent::run` at `crates/tsafe-agent/src/lib.rs`).
pub fn run() {
    if let Err(e) = run_inner() {
        eprintln!("tsafe-mcp: {e:#}");
        if let Some(data) = e.data {
            eprintln!("resolution: {data}");
        }
        std::process::exit(1);
    }
}

fn run_inner() -> Result<(), McpError> {
    let argv: Vec<String> = std::env::args().collect();
    let sub = parse_subcommand(&argv)?;

    match sub {
        Subcommand::Help => {
            print!("{HELP}");
            Ok(())
        }
        Subcommand::Serve(serve_args) => {
            let session_args = SessionArgs::parse(&serve_args)?;
            let session = Session::from_cli_args(&session_args)?;
            tokio::runtime::Builder::new_multi_thread()
                .enable_all()
                .build()
                .map_err(|e| {
                    McpError::new(
                        McpErrorKind::InternalError,
                        format!("tokio runtime init failed: {e}"),
                    )
                })?
                .block_on(async {
                    server::serve_stdio(session).await.map_err(|e| {
                        McpError::new(McpErrorKind::InternalError, format!("serve failed: {e}"))
                    })
                })
        }
        Subcommand::Install { host, rest } => {
            let opts = parse_install_opts(&rest, false)?;
            install::dispatch(&host, &opts)
        }
        Subcommand::Config { host, rest } => {
            let mut opts = parse_install_opts(&rest, false)?;
            opts.dry_run = true;
            if host.eq_ignore_ascii_case("codex") {
                install::validate_codex_bound_config(&opts)?;
                let rendered = install::codex::render_config(&opts)?;
                print!("{rendered}");
                Ok(())
            } else {
                install::dispatch(&host, &opts)
            }
        }
        Subcommand::Uninstall { host, rest } => {
            let opts = parse_install_opts(&rest, true)?;
            install::dispatch(&host, &opts)
        }
        Subcommand::Status => {
            status_diagnostic();
            Ok(())
        }
    }
}

fn parse_subcommand(argv: &[String]) -> Result<Subcommand, McpError> {
    // argv[0] is the binary path. Subcommand is argv[1] when present.
    if argv.len() < 2 {
        // No subcommand → default to `serve` with no additional args. The
        // serve path will still fail-closed if --profile / scope are missing.
        return Ok(Subcommand::Serve(Vec::new()));
    }

    match argv[1].as_str() {
        "--help" | "-h" | "help" => Ok(Subcommand::Help),
        "serve" if argv[2..].iter().any(|arg| arg == "--help" || arg == "-h") => {
            Ok(Subcommand::Help)
        }
        "serve" => Ok(Subcommand::Serve(argv[2..].to_vec())),
        "install" => {
            if argv.len() < 3 {
                return Err(McpError::new(
                    McpErrorKind::InvalidRequest,
                    "install: missing host argument (claude | cursor | continue | windsurf | codex)",
                ));
            }
            Ok(Subcommand::Install {
                host: argv[2].clone(),
                rest: argv[3..].to_vec(),
            })
        }
        "config" => {
            if argv.len() < 3 {
                return Err(McpError::new(
                    McpErrorKind::InvalidRequest,
                    "config: missing host argument (codex)",
                ));
            }
            Ok(Subcommand::Config {
                host: argv[2].clone(),
                rest: argv[3..].to_vec(),
            })
        }
        "uninstall" => {
            if argv.len() < 3 {
                return Err(McpError::new(
                    McpErrorKind::InvalidRequest,
                    "uninstall: missing host argument",
                ));
            }
            Ok(Subcommand::Uninstall {
                host: argv[2].clone(),
                rest: argv[3..].to_vec(),
            })
        }
        "status" => Ok(Subcommand::Status),
        // Anything else: treat as forward-compatible `serve` invocation with
        // flags only (matches the bare `tsafe-mcp --profile foo` shape used by
        // most host configs).
        other if other.starts_with("--") => Ok(Subcommand::Serve(argv[1..].to_vec())),
        unknown => Err(McpError::new(
            McpErrorKind::InvalidRequest,
            format!(
                "unknown subcommand '{unknown}'. Use: serve | install <host> | uninstall <host> | status"
            ),
        )),
    }
}

fn parse_install_opts(rest: &[String], uninstall: bool) -> Result<InstallOpts, McpError> {
    let mut profile: Option<String> = None;
    let mut allowed_keys: Vec<String> = Vec::new();
    let mut denied_keys: Vec<String> = Vec::new();
    let mut contract: Option<String> = None;
    let mut workdir: Option<std::path::PathBuf> = None;
    let mut allow_reveal = false;
    let mut name: Option<String> = None;
    let mut global = false;
    let mut project_dir: Option<std::path::PathBuf> = None;
    let mut dry_run = false;
    let mut audit_source: Option<String> = None;

    let mut i = 0;
    while i < rest.len() {
        let arg = &rest[i];
        match arg.as_str() {
            "--profile" => {
                i += 1;
                profile = Some(rest.get(i).cloned().ok_or_else(|| {
                    McpError::new(McpErrorKind::InvalidRequest, "--profile requires a value")
                })?);
            }
            "--allowed-keys" => {
                i += 1;
                let raw = rest.get(i).cloned().ok_or_else(|| {
                    McpError::new(
                        McpErrorKind::InvalidRequest,
                        "--allowed-keys requires a value",
                    )
                })?;
                allowed_keys = split_csv(&raw);
            }
            "--denied-keys" => {
                i += 1;
                let raw = rest.get(i).cloned().ok_or_else(|| {
                    McpError::new(
                        McpErrorKind::InvalidRequest,
                        "--denied-keys requires a value",
                    )
                })?;
                denied_keys = split_csv(&raw);
            }
            "--contract" => {
                i += 1;
                contract = Some(rest.get(i).cloned().ok_or_else(|| {
                    McpError::new(McpErrorKind::InvalidRequest, "--contract requires a value")
                })?);
            }
            "--workdir" => {
                i += 1;
                let dir = rest.get(i).cloned().ok_or_else(|| {
                    McpError::new(McpErrorKind::InvalidRequest, "--workdir requires a value")
                })?;
                workdir = Some(std::path::PathBuf::from(dir));
            }
            "--allow-reveal" => allow_reveal = true,
            "--name" => {
                i += 1;
                name = Some(rest.get(i).cloned().ok_or_else(|| {
                    McpError::new(McpErrorKind::InvalidRequest, "--name requires a value")
                })?);
            }
            "--global" => global = true,
            "--project" => {
                i += 1;
                let dir = rest.get(i).cloned().ok_or_else(|| {
                    McpError::new(
                        McpErrorKind::InvalidRequest,
                        "--project requires a directory path",
                    )
                })?;
                project_dir = Some(std::path::PathBuf::from(dir));
            }
            "--dry-run" => dry_run = true,
            "--audit-source" => {
                i += 1;
                audit_source = Some(rest.get(i).cloned().ok_or_else(|| {
                    McpError::new(
                        McpErrorKind::InvalidRequest,
                        "--audit-source requires a value",
                    )
                })?);
            }
            other => {
                return Err(McpError::new(
                    McpErrorKind::InvalidRequest,
                    format!("unknown install flag: '{other}'"),
                ));
            }
        }
        i += 1;
    }

    let scope = match project_dir {
        Some(dir) => Scope::Project { dir },
        None if global => Scope::Global,
        None => Scope::Global, // default
    };

    let profile = profile.ok_or_else(|| {
        McpError::new(
            McpErrorKind::InvalidRequest,
            "install/uninstall: --profile <name> is required",
        )
    })?;

    Ok(InstallOpts {
        profile,
        allowed_keys,
        denied_keys,
        contract,
        workdir,
        allow_reveal,
        name,
        scope,
        dry_run,
        uninstall,
        audit_source,
    })
}

fn split_csv(raw: &str) -> Vec<String> {
    raw.split(',')
        .map(|s| s.trim().to_string())
        .filter(|s| !s.is_empty())
        .collect()
}

fn status_diagnostic() {
    println!("tsafe-mcp {}", env!("CARGO_PKG_VERSION"));
    println!("protocol: MCP {MCP_PROTOCOL_VERSION}");
    println!();
    println!("Resolve scope at runtime by invoking `tsafe-mcp serve` with one of:");
    println!("  --profile <name>");
    println!("  --allowed-keys <glob,glob>");
    println!("  --contract <name>");
    println!("  --workdir <path>");
    println!("  --denied-keys <glob,glob>");
    println!("  --allow-reveal");
    println!("  --audit-source <host-label>");
    println!();
    println!("See ADR-006 / docs/architecture/mcp-server-design.md for the full surface.");
}

#[cfg(test)]
mod tests {
    use super::*;

    fn argv(items: &[&str]) -> Vec<String> {
        items.iter().map(|s| s.to_string()).collect()
    }

    /// Default subcommand is `Serve(empty)` when no subcommand is supplied.
    /// The downstream session check still fails-closed without scope.
    #[test]
    fn parse_subcommand_defaults_to_serve_with_no_args() {
        let parsed = parse_subcommand(&argv(&["tsafe-mcp"])).unwrap();
        match parsed {
            Subcommand::Serve(rest) => assert!(rest.is_empty()),
            other => panic!("expected Serve, got {other:?}"),
        }
    }

    /// `tsafe-mcp serve --profile foo` parses to Serve with the rest intact.
    #[test]
    fn parse_subcommand_serve_passes_through_remaining_args() {
        let parsed = parse_subcommand(&argv(&["tsafe-mcp", "serve", "--profile", "demo"])).unwrap();
        match parsed {
            Subcommand::Serve(rest) => {
                assert_eq!(rest, vec!["--profile", "demo"]);
            }
            other => panic!("expected Serve, got {other:?}"),
        }
    }

    /// Bare flag invocation `tsafe-mcp --profile foo` (no `serve` keyword) is
    /// the shape most host configs use; it must still route to Serve.
    #[test]
    fn parse_subcommand_bare_flag_routes_to_serve() {
        let parsed = parse_subcommand(&argv(&["tsafe-mcp", "--profile", "demo"])).unwrap();
        match parsed {
            Subcommand::Serve(rest) => {
                assert_eq!(rest, vec!["--profile", "demo"]);
            }
            other => panic!("expected Serve, got {other:?}"),
        }
    }

    /// `install` without a host argument is InvalidRequest.
    #[test]
    fn parse_subcommand_install_without_host_returns_invalid_request() {
        let err = parse_subcommand(&argv(&["tsafe-mcp", "install"])).unwrap_err();
        assert_eq!(err.kind, McpErrorKind::InvalidRequest);
        assert!(err.message.contains("install"));
    }

    /// `uninstall` mirrors `install`: host required.
    #[test]
    fn parse_subcommand_uninstall_without_host_returns_invalid_request() {
        let err = parse_subcommand(&argv(&["tsafe-mcp", "uninstall"])).unwrap_err();
        assert_eq!(err.kind, McpErrorKind::InvalidRequest);
    }

    /// `status` parses with no further arguments.
    #[test]
    fn parse_subcommand_status_parses_cleanly() {
        let parsed = parse_subcommand(&argv(&["tsafe-mcp", "status"])).unwrap();
        assert!(matches!(parsed, Subcommand::Status));
    }

    /// Unknown subcommand is InvalidRequest with a hint pointing at the
    /// supported set.
    #[test]
    fn parse_subcommand_unknown_returns_invalid_request_with_hint() {
        let err = parse_subcommand(&argv(&["tsafe-mcp", "diagnose"])).unwrap_err();
        assert_eq!(err.kind, McpErrorKind::InvalidRequest);
        assert!(
            err.message.contains("serve")
                && err.message.contains("install")
                && err.message.contains("status"),
            "hint should list supported subcommands: {}",
            err.message
        );
    }

    /// `parse_install_opts` round-trip: scope, contract, allow-reveal, name,
    /// audit-source all land on the right fields.
    #[test]
    fn parse_install_opts_round_trips_all_flags() {
        let rest = argv(&[
            "--profile",
            "demo",
            "--allowed-keys",
            "demo/*,shared/*",
            "--denied-keys",
            "demo/secret",
            "--contract",
            "deploy",
            "--allow-reveal",
            "--name",
            "testsrv",
            "--audit-source",
            "mcp:claude:proof",
        ]);
        let opts = parse_install_opts(&rest, false).unwrap();
        assert_eq!(opts.profile, "demo");
        assert_eq!(opts.allowed_keys, vec!["demo/*", "shared/*"]);
        assert_eq!(opts.denied_keys, vec!["demo/secret"]);
        assert_eq!(opts.contract.as_deref(), Some("deploy"));
        assert!(opts.allow_reveal);
        assert_eq!(opts.name.as_deref(), Some("testsrv"));
        assert_eq!(opts.audit_source.as_deref(), Some("mcp:claude:proof"));
        assert!(!opts.uninstall);
        assert!(!opts.dry_run);
    }

    /// `--project <dir>` switches scope to Project.
    #[test]
    fn parse_install_opts_project_scope() {
        let rest = argv(&[
            "--profile",
            "demo",
            "--allowed-keys",
            "demo/*",
            "--project",
            "/tmp/myproject",
            "--dry-run",
        ]);
        let opts = parse_install_opts(&rest, false).unwrap();
        match opts.scope {
            crate::install::Scope::Project { dir } => {
                assert_eq!(dir, std::path::PathBuf::from("/tmp/myproject"));
            }
            crate::install::Scope::Global => panic!("expected Project scope, got Global"),
        }
        assert!(opts.dry_run);
    }

    /// Missing `--profile` value is InvalidRequest.
    #[test]
    fn parse_install_opts_missing_profile_value() {
        let rest = argv(&["--profile"]);
        let err = parse_install_opts(&rest, false).unwrap_err();
        assert_eq!(err.kind, McpErrorKind::InvalidRequest);
        assert!(err.message.contains("--profile"));
    }

    /// `parse_install_opts` without `--profile` at all also surfaces
    /// InvalidRequest from the final check.
    #[test]
    fn parse_install_opts_missing_profile_entirely() {
        let rest = argv(&["--allowed-keys", "demo/*"]);
        let err = parse_install_opts(&rest, false).unwrap_err();
        assert_eq!(err.kind, McpErrorKind::InvalidRequest);
        assert!(err.message.contains("--profile"));
    }

    /// Unknown install flag bubbles up as InvalidRequest, never silently
    /// swallowed.
    #[test]
    fn parse_install_opts_rejects_unknown_flag() {
        let rest = argv(&["--profile", "demo", "--mystery-flag"]);
        let err = parse_install_opts(&rest, false).unwrap_err();
        assert_eq!(err.kind, McpErrorKind::InvalidRequest);
        assert!(err.message.contains("unknown install flag"));
    }

    /// Uninstall flag is plumbed through correctly.
    #[test]
    fn parse_install_opts_uninstall_sets_flag() {
        let rest = argv(&["--profile", "demo"]);
        let opts = parse_install_opts(&rest, true).unwrap();
        assert!(opts.uninstall);
    }

    /// `split_csv` strips whitespace and drops empty entries — matters for
    /// `--allowed-keys "demo/*, , bar/*"` and similar copy-paste shapes.
    #[test]
    fn split_csv_handles_whitespace_and_empties() {
        assert_eq!(split_csv("demo/*, , shared/*"), vec!["demo/*", "shared/*"]);
        assert!(split_csv("").is_empty());
        assert_eq!(split_csv(" only "), vec!["only"]);
    }
}