XY-980: Implement read-only Decodex MCP stdio gateway

README.md

@@ -125,6 +125,7 @@ cargo run -p decodex --bin decodex -- intake goal --project decodex <CONTRACT_ID
 cargo run -p decodex --bin decodex -- intake goal --project decodex <CONTRACT_ID> --apply
 cargo run -p decodex --bin decodex -- intake issues --project decodex XY-1 XY-2 --dry-run
 cargo run -p decodex --bin decodex -- intake issues --project decodex XY-1 XY-2 --apply
+cargo run -p decodex --bin decodex -- mcp serve --transport stdio
 cargo run -p decodex --bin decodex -- radar refresh-upstream-queue
 cargo run -p decodex --bin decodex -- radar refresh-release-delta
 cargo run -p decodex --bin decodex -- radar validate
@@ -185,6 +186,12 @@ Program, and issue mappings. It never applies or removes service queue labels; r
 mapped nodes are dispatched directly by the Program scheduler instead of being
 converted into queued-label work.
 
+`decodex mcp serve --transport stdio` starts the phase-one read-only MCP gateway for
+local desktop and CLI clients. The gateway exposes checked-in documentation, checked-in
+JSON research reports, runtime Decision Contract readback, local status snapshots, and
+lane-control readback as MCP resources only. It does not expose mutating MCP tools.
+Stdout is reserved for MCP JSON-RPC messages; diagnostics and logs stay off stdout.
+
 ### Install from Source
 
 ```sh

apps/decodex/src/cli.rs

@@ -20,6 +20,7 @@ use crate::{
 	archive_hygiene::{self, ArchiveHygieneRequest},
 	maintenance::{self, MaintenanceMode, MaintenancePruneRequest, MaintenanceScope},
 	manual::{self, ManualCommitRequest, ManualLandRequest},
+	mcp::{self, McpServeRequest, McpTransport},
 	orchestrator::{
 		self, DEFAULT_STEER_RESULT_WAIT_TIMEOUT, DiagnoseRequest, EvidenceRequest,
 		IssueDispatchMode, LaneInspectRequest, LaneInterruptRequest, LaneSteerReport,
@@ -73,6 +74,7 @@ impl Cli {
 			Command::Land(args) => args.run(),
 			Command::Run(args) => args.run(),
 			Command::Serve(args) => args.run(),
+			Command::Mcp(args) => args.run(),
 			Command::Project(args) => args.run(),
 			Command::Lane(args) => args.run(),
 			Command::Status(args) => args.run(),
@@ -368,6 +370,36 @@ impl ServeCommand {
 	}
 }
 
+#[derive(Debug, Args)]
+struct McpCommand {
+	#[command(subcommand)]
+	command: McpSubcommand,
+}
+impl McpCommand {
+	fn run(&self) -> Result<()> {
+		match &self.command {
+			McpSubcommand::Serve(args) => args.run(),
+		}
+	}
+}
+
+#[derive(Debug, Args)]
+struct McpServeCommand {
+	#[command(flatten)]
+	project_config: ProjectConfigArgs,
+	/// MCP transport.
+	#[arg(long, value_enum, default_value_t = McpTransport::Stdio)]
+	transport: McpTransport,
+}
+impl McpServeCommand {
+	fn run(&self) -> Result<()> {
+		mcp::serve(McpServeRequest {
+			transport: self.transport,
+			config_path: self.project_config.as_path(),
+		})
+	}
+}
+
 #[derive(Debug, Args)]
 struct ProjectCommand {
 	#[command(subcommand)]
@@ -1634,6 +1666,8 @@ enum Command {
 	Run(RunCommand),
 	/// Run the local multi-project Decodex control plane.
 	Serve(ServeCommand),
+	/// Serve the read-only Decodex MCP gateway.
+	Mcp(McpCommand),
 	/// Manage the local Decodex project registry.
 	Project(ProjectCommand),
 	/// Inspect or influence a local lane.
@@ -1697,6 +1731,12 @@ enum ProjectSubcommand {
 	Remove(ProjectToggleCommand),
 }
 
+#[derive(Debug, Subcommand)]
+enum McpSubcommand {
+	/// Serve read-only Decodex resources over MCP.
+	Serve(McpServeCommand),
+}
+
 #[derive(Debug, Subcommand)]
 enum LaneSubcommand {
 	/// Inspect one local lane by issue identifier or tracker issue id.
@@ -1929,22 +1969,26 @@ mod tests {
 
 	use clap::Parser;
 
-	use crate::cli::{
-		AccountCommand, AccountSubcommand, AccountUseCommand, AppCommand, AttemptCommand, Cli,
-		Command, CommitCommand, DiagnoseCommand, EvidenceCommand, IntakeCommand, IntakeGoalCommand,
-		IntakeIssuesCommand, IntakeSubcommand, LandCommand, LaneCommand, LaneInspectCommand,
-		LaneInterruptCommand, LaneSteerCommand, LaneSubcommand, LegacyCloseoutRecoveryCommand,
-		MergedCloseoutRecoveryCommand, ProbeCommand, ProjectCommand, ProjectConfigArgs,
-		ProjectSubcommand, RadarBackfillReleaseRangeCommand, RadarBundleBuildCommand,
-		RadarBundleCommand, RadarBundleSubcommand, RadarBundleValidateCommand, RadarCommand,
-		RadarLedgerCommand, RadarLedgerIngestExistingCommand, RadarLedgerSubcommand,
-		RadarLedgerSummaryCommand, RadarRefreshReleaseDeltaCommand,
-		RadarRefreshUpstreamQueueCommand, RadarRenderSignalCommand, RadarSubcommand,
-		RadarValidateCommand, RecoverCommand, RecoverSubcommand, ResearchCommand,
-		ResearchCompileCommand, ResearchOutcomeArg, ResearchPromoteCommand, ResearchSubcommand,
-		ReviewHandoffAdoptCommand, ReviewHandoffDiagnoseCommand, ReviewHandoffRebindCommand,
-		ReviewHandoffRecoveryCommand, ReviewHandoffRecoverySubcommand, RunCommand, ServeCommand,
-		StatusCommand,
+	use crate::{
+		cli::{
+			AccountCommand, AccountSubcommand, AccountUseCommand, AppCommand, AttemptCommand, Cli,
+			Command, CommitCommand, DiagnoseCommand, EvidenceCommand, IntakeCommand,
+			IntakeGoalCommand, IntakeIssuesCommand, IntakeSubcommand, LandCommand, LaneCommand,
+			LaneInspectCommand, LaneInterruptCommand, LaneSteerCommand, LaneSubcommand,
+			LegacyCloseoutRecoveryCommand, McpCommand, McpServeCommand, McpSubcommand,
+			MergedCloseoutRecoveryCommand, ProbeCommand, ProjectCommand, ProjectConfigArgs,
+			ProjectSubcommand, RadarBackfillReleaseRangeCommand, RadarBundleBuildCommand,
+			RadarBundleCommand, RadarBundleSubcommand, RadarBundleValidateCommand, RadarCommand,
+			RadarLedgerCommand, RadarLedgerIngestExistingCommand, RadarLedgerSubcommand,
+			RadarLedgerSummaryCommand, RadarRefreshReleaseDeltaCommand,
+			RadarRefreshUpstreamQueueCommand, RadarRenderSignalCommand, RadarSubcommand,
+			RadarValidateCommand, RecoverCommand, RecoverSubcommand, ResearchCommand,
+			ResearchCompileCommand, ResearchOutcomeArg, ResearchPromoteCommand, ResearchSubcommand,
+			ReviewHandoffAdoptCommand, ReviewHandoffDiagnoseCommand, ReviewHandoffRebindCommand,
+			ReviewHandoffRecoveryCommand, ReviewHandoffRecoverySubcommand, RunCommand,
+			ServeCommand, StatusCommand,
+		},
+		mcp::McpTransport,
 	};
 
 	#[test]
@@ -2191,6 +2235,29 @@ mod tests {
 		}
 	}
 
+	#[test]
+	fn parses_mcp_stdio_serve() {
+		let cli = Cli::parse_from([
+			"decodex",
+			"mcp",
+			"serve",
+			"--config",
+			"./project.toml",
+			"--transport",
+			"stdio",
+		]);
+
+		assert!(matches!(
+			cli.command,
+			Command::Mcp(McpCommand {
+				command: McpSubcommand::Serve(McpServeCommand {
+					project_config: ProjectConfigArgs { config: Some(config) },
+					transport: McpTransport::Stdio,
+				})
+			}) if config == Path::new("./project.toml")
+		));
+	}
+
 	#[test]
 	fn parses_radar_validate_paths() {
 		let cli = Cli::parse_from(["decodex", "radar", "validate", "artifacts/github/bundles"]);

apps/decodex/src/lib.rs

@@ -18,6 +18,7 @@ mod github;
 mod loop_contract;
 mod maintenance;
 mod manual;
+mod mcp;
 mod orchestrator;
 mod program_intake;
 mod pull_request;