Merge pull request #52 from CurtisTechSolutions/feat/mcp-stdio-host

feat(cli): launch local MCP over stdio

Author: nosam1998

.github/scripts/mcp-stdio-smoke.py

@@ -0,0 +1,121 @@
+"""Exercise the actual MCP CLI, clean stdout, game loop, EOF, signal, and restart."""
+import json
+from pathlib import Path
+import queue
+import subprocess
+import tempfile
+import threading
+import time
+
+binary = Path("target/debug/gfa").resolve()
+
+
+class Client:
+    def __init__(self, database, *options):
+        self.errors = tempfile.TemporaryFile(mode="w+t")
+        self.process = subprocess.Popen(
+            [str(binary), "mcp", "--sqlite", str(database), *options],
+            stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=self.errors,
+            text=True, bufsize=1,
+        )
+        self.lines = queue.Queue()
+        self.sequence = 0
+        self.reader = threading.Thread(target=self.read, daemon=True)
+        self.reader.start()
+
+    def read(self):
+        for line in self.process.stdout:
+            self.lines.put(line)
+        self.lines.put(None)
+
+    def send(self, message):
+        self.process.stdin.write(json.dumps(message) + "\n")
+        self.process.stdin.flush()
+
+    def request(self, method, params=None):
+        self.sequence += 1
+        request_id = self.sequence
+        self.send({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}})
+        while True:
+            line = self.lines.get(timeout=30)
+            if line is None:
+                raise RuntimeError("MCP stdout closed before a response")
+            message = json.loads(line)  # Startup/log banners contaminating stdout fail here.
+            if message.get("id") == request_id:
+                if "error" in message:
+                    raise RuntimeError(message["error"])
+                return message["result"]
+
+    def initialize(self):
+        result = self.request("initialize", {
+            "protocolVersion": "2025-11-25", "capabilities": {},
+            "clientInfo": {"name": "gfa-smoke", "version": "1"},
+        })
+        assert result["protocolVersion"] == "2025-11-25"
+        self.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+        return result
+
+    def tool(self, name, arguments, failed=False):
+        result = self.request("tools/call", {"name": name, "arguments": arguments})
+        assert result.get("isError", False) == failed, result
+        assert result["content"] and result["content"][0]["type"] == "text"
+        return result["structuredContent"]["error" if failed else "data"]
+
+    def close(self, signal=False):
+        if self.process.poll() is None:
+            if signal:
+                self.process.terminate()  # Keep stdin open to exercise blocking-reader cleanup.
+            else:
+                self.process.stdin.close()
+        try:
+            self.process.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            self.process.kill()
+            self.process.wait()
+            raise
+        if not self.process.stdin.closed:
+            self.process.stdin.close()
+        self.reader.join(timeout=2)
+        self.errors.seek(0)
+        diagnostics = self.errors.read()
+        self.errors.close()
+        assert self.process.returncode == 0, diagnostics
+        assert not self.reader.is_alive()
+
+
+with tempfile.TemporaryDirectory() as directory:
+    database = Path(directory) / "mcp.sqlite"
+    client = Client(database)
+    try:
+        client.initialize()
+        names = {tool["name"] for tool in client.request("tools/list")["tools"]}
+        assert {"list_games", "create_match", "make_move", "get_state"} <= names
+        created = client.tool("create_match", {"game_id": "tictactoe", "opponent": "random", "seed": 23})
+        match_id = created["state"]["match_id"]
+        action = created["state"]["legal_actions"][0]
+        error = client.tool("make_move", {"match_id": match_id, "action": "invalid"}, failed=True)
+        assert error["details"]["legal_actions"]
+        moved = client.tool("make_move", {"match_id": match_id, "action": action, "reasoning": "smoke"})
+        assert moved["state"]["turn"] == 2 and len(moved["opponent_actions"]) == 1
+    finally:
+        client.close()
+    restarted = Client(database)
+    try:
+        restarted.initialize()
+        assert restarted.tool("get_state", {"match_id": match_id}) == moved["state"]
+    finally:
+        restarted.close(signal=True)
+    spectator = Client(database, "--spectator")
+    try:
+        spectator.initialize()
+        view = spectator.tool("get_state", {"match_id": match_id})
+        assert view["you"] is None and view["legal_actions"] == []
+        assert spectator.tool("resign", {"match_id": match_id}, failed=True)["code"] == "FORBIDDEN"
+    finally:
+        spectator.close()
+    uninitialized = Client(database)
+    # Allow signal handler installation, then leave stdin open during shutdown.
+    time.sleep(1)
+    uninitialized.close(signal=True)
+
+print("MCP stdio game loop, clean stdout, persistence, EOF, and signal shutdown passed.")

.github/workflows/ci.yml

@@ -33,6 +33,7 @@ jobs:
       - run: cargo test -p gfa-cli --locked
       - run: cargo build -p gfa-cli --locked
       - run: python3 .github/scripts/local-server-smoke.py
+      - run: python3 .github/scripts/mcp-stdio-smoke.py
       - name: Export generated OpenAPI
         run: cargo run -p gfa-http --example export-openapi --locked > target/openapi.json
       - uses: actions/upload-artifact@v4

crates/adapters/gfa-mcp/README.md

@@ -13,7 +13,7 @@ protocol errors; domain and input errors are ordinary isError tool results.
 MCP DTOs use the SDK's JSON Schema 2020-12 generator. The existing game-plugin
 schema dependency remains unchanged. Official-client protocol tests and output
 schema validation run at the application layer, where concrete games may be
-named. Stdio/HTTP composition and playing tools are separate implementation units.
+named. The CLI supplies stdio composition; streamable HTTP is a separate implementation unit.
 
 Dependency justification: rmcp supplies maintained protocol negotiation, wire
 types and transports rather than a project-specific JSON-RPC implementation.
@@ -23,3 +23,8 @@ Reference: https://github.com/modelcontextprotocol/rust-sdk
 Match controls: `create_match`, `get_state`, `get_legal_actions`, `make_move`, and `resign` use the host-authorized viewer. A spectator can read public state but cannot create or control a player. `play_as` must agree with the host-selected player seat. This local composition is not multiuser authorization; a hosted deployment needs a match-access policy before granting a viewer.
 
 States contain the engine text board and sorted canonical action strings, without tensors, action masks, or duplicate JSON boards. Move errors retain legal actions and recovery context. Supply both `turn` and `idempotency_key` for safe retries; without an explicit turn, the adapter reads the current turn and the service still rejects concurrent changes. Opponent replies and the resulting state arrive in the same move result. Reasoning is stored through the normal service command.
+
+
+Launch a local client with `gfa mcp --sqlite ./gfa.sqlite`. Standard output is reserved for MCP JSON-RPC; diagnostics go to stderr. `--seat 1` authorizes the second player (for example Black); `--spectator` is read-only. Database and Stockfish options are shared with `gfa serve`. No TCP listener is opened in stdio mode. The launcher controls access to the local database and selected seat; this mode is intended for one trusted local user.
+
+EOF and process signals stop MCP and background play, then close the database. The CLI bounds runtime shutdown because Tokio's stdin reader uses a blocking read that a client may leave open after a signal.

crates/apps/gfa-cli/src/main.rs

@@ -2,7 +2,7 @@
 use gfa_server::{Config, Database, ServerError};
 use std::path::PathBuf;
 
-const USAGE: &str = "Usage: gfa serve [--sqlite PATH | --postgres-env VARIABLE] [--port PORT] [--stockfish PATH]\n\nStarts a local API on 127.0.0.1 (default port 8080).\nSQLite defaults to ./gfa.sqlite. Port 0 selects an available port.\nPostgreSQL requires the postgres build feature and reads its URL from VARIABLE.\nStockfish requires an absolute binary path, Linux, bubblewrap and working user namespaces.";
+const USAGE: &str = "Usage: gfa mcp [--sqlite PATH | --postgres-env VARIABLE] [--seat SEAT | --spectator] [--stockfish PATH]\n       gfa serve [--sqlite PATH | --postgres-env VARIABLE] [--port PORT] [--stockfish PATH]\n\nmcp serves a trusted local client over stdin/stdout; seat defaults to 0. No TCP port is opened.\nserve starts a local API on 127.0.0.1 (default port 8080).\nSQLite defaults to ./gfa.sqlite. Port 0 selects an available port.\nPostgreSQL requires the postgres build feature and reads its URL from VARIABLE.\nStockfish requires an absolute binary path, Linux, bubblewrap and working user namespaces.";
 
 fn parse(args: impl IntoIterator<Item = String>) -> Result<Option<Config>, String> {
     parse_with_env(args, |name| std::env::var(name).ok())
@@ -83,6 +83,53 @@ fn parse_with_env(
     Ok(Some(config))
 }
 
+#[derive(Debug, PartialEq, Eq)]
+enum Command {
+    Serve(Config),
+    Mcp { config: Config, seat: Option<u8> },
+}
+fn command(args: impl IntoIterator<Item = String>) -> Result<Option<Command>, String> {
+    let args = args.into_iter().collect::<Vec<_>>();
+    if args.first().map(String::as_str) != Some("mcp") {
+        return parse(args).map(|config| config.map(Command::Serve));
+    }
+    let mut seat = Some(0);
+    let mut viewer_seen = false;
+    let mut forwarded = vec!["serve".to_string()];
+    let mut arguments = args.into_iter().skip(1);
+    while let Some(argument) = arguments.next() {
+        match argument.as_str() {
+            "--seat" if !viewer_seen => {
+                seat = Some(
+                    arguments
+                        .next()
+                        .ok_or("--seat requires a zero-based seat")?
+                        .parse()
+                        .map_err(|_| "Seat must be an integer from 0 to 255")?,
+                );
+                viewer_seen = true;
+            }
+            "--spectator" if !viewer_seen => {
+                seat = None;
+                viewer_seen = true;
+            }
+            "--seat" | "--spectator" => return Err("Choose --seat or --spectator once".into()),
+            "--port" => return Err("mcp uses stdin/stdout and does not accept --port".into()),
+            // Preserve values even when a filesystem path equals another option.
+            "--sqlite" | "--postgres-env" | "--stockfish" => {
+                forwarded.push(argument);
+                forwarded.push(
+                    arguments
+                        .next()
+                        .ok_or("Storage and engine options require a value")?,
+                );
+            }
+            _ => forwarded.push(argument),
+        }
+    }
+    parse(forwarded).map(|config| config.map(|config| Command::Mcp { config, seat }))
+}
+
 async fn shutdown() -> Result<(), std::io::Error> {
     #[cfg(unix)]
     {
@@ -98,16 +145,17 @@ async fn shutdown() -> Result<(), std::io::Error> {
     Ok(())
 }
 
-#[tokio::main]
-async fn main() -> Result<(), ServerError> {
-    match parse(std::env::args().skip(1)) {
-        Ok(Some(config)) => {
-            gfa_server::serve(config, async {
-                if let Err(error) = shutdown().await {
-                    eprintln!("Shutdown signal handler failed: {error}");
-                }
-            })
-            .await
+async fn shutdown_signal() {
+    if let Err(error) = shutdown().await {
+        eprintln!("Shutdown signal handler failed: {error}");
+    }
+}
+
+async fn run() -> Result<(), ServerError> {
+    match command(std::env::args().skip(1)) {
+        Ok(Some(Command::Serve(config))) => gfa_server::serve(config, shutdown_signal()).await,
+        Ok(Some(Command::Mcp { config, seat })) => {
+            gfa_server::serve_stdio(config, seat, shutdown_signal()).await
         }
         Ok(None) => {
             println!("{USAGE}");
@@ -119,6 +167,16 @@ async fn main() -> Result<(), ServerError> {
         }
     }
 }
+fn main() -> Result<(), ServerError> {
+    let runtime = tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()?;
+    let result = runtime.block_on(run());
+    // Tokio's stdin reader uses an uncancellable blocking read. A launcher may
+    // leave stdin open when sending SIGTERM; do not wait forever for that reader.
+    runtime.shutdown_timeout(std::time::Duration::from_secs(1));
+    result
+}
 
 #[cfg(test)]
 mod tests {
@@ -234,3 +292,50 @@ mod tests {
         }
     }
 }
+
+#[cfg(test)]
+mod mcp_command_tests {
+    use super::*;
+    fn parsed(args: &[&str]) -> Result<Option<Command>, String> {
+        command(args.iter().map(|arg| (*arg).to_string()))
+    }
+    #[test]
+    fn parses_stdio_and_rejects_ambiguous_viewers() -> Result<(), String> {
+        assert_eq!(
+            parsed(&["mcp"])?,
+            Some(Command::Mcp {
+                config: Config::default(),
+                seat: Some(0)
+            })
+        );
+        assert_eq!(
+            parsed(&["mcp", "--seat", "1"])?,
+            Some(Command::Mcp {
+                config: Config::default(),
+                seat: Some(1)
+            })
+        );
+        assert_eq!(
+            parsed(&["mcp", "--spectator"])?,
+            Some(Command::Mcp {
+                config: Config::default(),
+                seat: None
+            })
+        );
+        assert!(parsed(&["mcp", "--help"])?.is_none());
+        for args in [
+            vec!["mcp", "--seat"],
+            vec!["mcp", "--seat", "256"],
+            vec!["mcp", "--seat", "-1"],
+            vec!["mcp", "--seat", "0", "--spectator"],
+            vec!["mcp", "--spectator", "--seat", "0"],
+            vec!["mcp", "--spectator", "--spectator"],
+            vec!["mcp", "--port", "0"],
+            vec!["serve", "--seat", "1"],
+            vec!["mcp", "--sqlite"],
+        ] {
+            assert!(parsed(&args).is_err(), "{args:?}");
+        }
+        Ok(())
+    }
+}

crates/apps/gfa-server/Cargo.toml

@@ -9,6 +9,8 @@ default = []
 postgres = ["gfa-store/postgres"]
 
 [dependencies]
+gfa-mcp.workspace = true
+rmcp.workspace = true
 gfa-engine-uci.workspace = true
 gfa-core.workspace = true
 gfa-opponents.workspace = true
@@ -22,7 +24,6 @@ tokio.workspace = true
 uuid.workspace = true
 
 [dev-dependencies]
-gfa-mcp.workspace = true
 rmcp = { workspace = true, features = ["client"] }
 gfa-game-chess.workspace = true
 jsonschema.workspace = true

crates/apps/gfa-server/src/lib.rs

@@ -125,7 +125,12 @@ struct Application {
     service: Arc<GameService>,
 }
 
-async fn application(config: &Config, address: SocketAddr) -> Result<Application, ServerError> {
+struct Components {
+    store: Store,
+    updates: Arc<gfa_http::LiveUpdates>,
+    service: Arc<GameService>,
+}
+async fn components(config: &Config) -> Result<Components, ServerError> {
     let registry = gfa_games::registry()?;
     let opponents = stockfish::factory(config.stockfish.as_ref(), &registry).await?;
     let store = Store::open(&config.database).await?;
@@ -136,6 +141,19 @@ async fn application(config: &Config, address: SocketAddr) -> Result<Application
             .with_observer(updates.clone())
             .with_opponents(opponents, Arc::new(workers::Workers::new(4))),
     );
+    Ok(Components {
+        store,
+        updates,
+        service,
+    })
+}
+
+async fn application(config: &Config, address: SocketAddr) -> Result<Application, ServerError> {
+    let Components {
+        store,
+        updates,
+        service,
+    } = components(config).await?;
     let router = gfa_http::local_router_with_updates(service.clone(), address, updates.clone())?;
     Ok(Application {
         router,
@@ -239,3 +257,6 @@ mod mcp_tests;
 
 #[cfg(test)]
 mod mcp_play_tests;
+
+mod mcp_host;
+pub use mcp_host::serve_stdio;