chore(mcp): integrate stdio and format resources

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.
@@ -25,6 +25,11 @@ Match controls: `create_match`, `get_state`, `get_legal_actions`, `make_move`, a
 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.
+
+
 `get_match_history` scans bounded pages of the trusted local user's database; follow `next` even when a game filter produces an empty page. `get_replay` returns paginated viewer-scoped events with canonical moves, visible reasoning, and control outcomes. It omits raw initial states and seeds, and preserves the service's rule that another seat's reasoning stays hidden during active play. A future multiuser host must restrict match history and access to its authenticated principal.
 
 

crates/adapters/gfa-mcp/src/history.rs

@@ -4,7 +4,9 @@ use rmcp::{model::CallToolResult, schemars::JsonSchema};
 use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
 
-fn page_size() -> u32 { 25 }
+fn page_size() -> u32 {
+    25
+}
 #[derive(Deserialize, JsonSchema)]
 #[schemars(crate = "rmcp::schemars")]
 #[serde(deny_unknown_fields)]
@@ -64,51 +66,165 @@ pub(crate) struct ReplayOutput {
     pub next: Option<u64>,
 }
 impl McpServer {
-    pub(crate) async fn history_tool(&self, arguments: Value) -> Result<CallToolResult,ApiError> {
+    pub(crate) async fn history_tool(&self, arguments: Value) -> Result<CallToolResult, ApiError> {
         let args: HistoryArgs = decode(arguments)?;
-        let page = self.service.list_matches(MatchHistoryQuery{game_id:args.game_id,limit:args.limit,after:args.after,status:None}).await?;
-        let matches = page.matches.into_iter().map(|entry|MatchSummary {
-            match_id:entry.match_id,game_id:entry.game_id,status:match entry.status{MatchStatus::Active=>"active",MatchStatus::Finished=>"finished"}.into(),
-            turn:entry.turn,returns:entry.returns,created_at_ms:entry.created_at_ms,
-        }).collect::<Vec<_>>();
-        let text = format!("{}\nNext cursor: {}",matches.iter().map(|entry|format!("{}: {} — {}, {} moves, returns {:?}",entry.match_id,entry.game_id,entry.status,entry.turn,entry.returns)).collect::<Vec<_>>().join("\n"),page.next.as_deref().unwrap_or("none"));
-        success(HistoryOutput{matches,next:page.next},text)
+        let page = self
+            .service
+            .list_matches(MatchHistoryQuery {
+                game_id: args.game_id,
+                limit: args.limit,
+                after: args.after,
+                status: None,
+            })
+            .await?;
+        let matches = page
+            .matches
+            .into_iter()
+            .map(|entry| MatchSummary {
+                match_id: entry.match_id,
+                game_id: entry.game_id,
+                status: match entry.status {
+                    MatchStatus::Active => "active",
+                    MatchStatus::Finished => "finished",
+                }
+                .into(),
+                turn: entry.turn,
+                returns: entry.returns,
+                created_at_ms: entry.created_at_ms,
+            })
+            .collect::<Vec<_>>();
+        let text = format!(
+            "{}\nNext cursor: {}",
+            matches
+                .iter()
+                .map(|entry| format!(
+                    "{}: {} — {}, {} moves, returns {:?}",
+                    entry.match_id, entry.game_id, entry.status, entry.turn, entry.returns
+                ))
+                .collect::<Vec<_>>()
+                .join("\n"),
+            page.next.as_deref().unwrap_or("none")
+        );
+        success(
+            HistoryOutput {
+                matches,
+                next: page.next,
+            },
+            text,
+        )
     }
-    pub(crate) async fn replay_tool(&self, arguments: Value) -> Result<CallToolResult,ApiError> {
+    pub(crate) async fn replay_tool(&self, arguments: Value) -> Result<CallToolResult, ApiError> {
         let args: ReplayArgs = decode(arguments)?;
-        let page = self.service.get_events(&args.match_id,EventsQuery{since:args.since,limit:args.limit,seat:None},self.viewer).await?;
+        let page = self
+            .service
+            .get_events(
+                &args.match_id,
+                EventsQuery {
+                    since: args.since,
+                    limit: args.limit,
+                    seat: None,
+                },
+                self.viewer,
+            )
+            .await?;
         let mut events = Vec::with_capacity(page.events.len());
         for entry in page.events {
-            let mut output = ReplayEntry{sequence:entry.sequence,kind:String::new(),turn:None,seat:None,action:None,reasoning:None,details:Value::Null};
+            let mut output = ReplayEntry {
+                sequence: entry.sequence,
+                kind: String::new(),
+                turn: None,
+                seat: None,
+                action: None,
+                reasoning: None,
+                details: Value::Null,
+            };
             match entry.event {
-                EventData::Created {game_id,engine_version,config,assists,at_ms,..} => {
+                EventData::Created {
+                    game_id,
+                    engine_version,
+                    config,
+                    assists,
+                    at_ms,
+                    ..
+                } => {
                     output.kind = "created".into();
                     output.details = json!({"game_id":game_id,"engine_version":engine_version,"config":config,"assists":assists,"at_ms":at_ms});
                 }
-                EventData::Action {turn,seat,action,reasoning,opponent_info,events,at_ms} => {
-                    output.kind = "action".into();output.turn=Some(turn);output.seat=Some(seat);
-                    output.action=action.map(|action|action.string);output.reasoning=reasoning;
-                    output.details=json!({"opponent_info":opponent_info,"events":events,"at_ms":at_ms});
+                EventData::Action {
+                    turn,
+                    seat,
+                    action,
+                    reasoning,
+                    opponent_info,
+                    events,
+                    at_ms,
+                } => {
+                    output.kind = "action".into();
+                    output.turn = Some(turn);
+                    output.seat = Some(seat);
+                    output.action = action.map(|action| action.string);
+                    output.reasoning = reasoning;
+                    output.details =
+                        json!({"opponent_info":opponent_info,"events":events,"at_ms":at_ms});
                 }
-                EventData::ForkedFrom {source} => {
-                    output.kind="forked_from".into();output.details=serde_json::to_value(source).map_err(|_|internal())?;
+                EventData::ForkedFrom { source } => {
+                    output.kind = "forked_from".into();
+                    output.details = serde_json::to_value(source).map_err(|_| internal())?;
                 }
-                EventData::Resigned {turn,seat,at_ms} => {
-                    output.kind="resigned".into();output.turn=Some(turn);output.seat=Some(seat);output.details=json!({"at_ms":at_ms});
+                EventData::Resigned { turn, seat, at_ms } => {
+                    output.kind = "resigned".into();
+                    output.turn = Some(turn);
+                    output.seat = Some(seat);
+                    output.details = json!({"at_ms":at_ms});
                 }
-                EventData::DrawOffered {turn,seat,at_ms} => {
-                    output.kind="draw_offered".into();output.turn=Some(turn);output.seat=Some(seat);output.details=json!({"at_ms":at_ms});
+                EventData::DrawOffered { turn, seat, at_ms } => {
+                    output.kind = "draw_offered".into();
+                    output.turn = Some(turn);
+                    output.seat = Some(seat);
+                    output.details = json!({"at_ms":at_ms});
                 }
-                EventData::Finished {turn,returns,terminated,truncated} => {
-                    output.kind="finished".into();output.turn=Some(turn);
-                    output.details=json!({"returns":returns,"terminated":terminated,"truncated":truncated});
+                EventData::Finished {
+                    turn,
+                    returns,
+                    terminated,
+                    truncated,
+                } => {
+                    output.kind = "finished".into();
+                    output.turn = Some(turn);
+                    output.details =
+                        json!({"returns":returns,"terminated":terminated,"truncated":truncated});
                 }
             }
             events.push(output);
         }
-        let text = format!("Match: {}. Revision: {}. Next sequence: {:?}.\n{}",args.match_id,page.revision,page.next,
-            events.iter().map(|entry|format!("#{} {} turn={:?} seat={:?} action={} reasoning={} details={}",entry.sequence,entry.kind,entry.turn,entry.seat,
-                entry.action.as_deref().unwrap_or("none/private"),entry.reasoning.as_deref().unwrap_or("none/private"),entry.details)).collect::<Vec<_>>().join("\n"));
-        success(ReplayOutput{match_id:args.match_id,revision:page.revision,events,next:page.next},text)
+        let text = format!(
+            "Match: {}. Revision: {}. Next sequence: {:?}.\n{}",
+            args.match_id,
+            page.revision,
+            page.next,
+            events
+                .iter()
+                .map(|entry| format!(
+                    "#{} {} turn={:?} seat={:?} action={} reasoning={} details={}",
+                    entry.sequence,
+                    entry.kind,
+                    entry.turn,
+                    entry.seat,
+                    entry.action.as_deref().unwrap_or("none/private"),
+                    entry.reasoning.as_deref().unwrap_or("none/private"),
+                    entry.details
+                ))
+                .collect::<Vec<_>>()
+                .join("\n")
+        );
+        success(
+            ReplayOutput {
+                match_id: args.match_id,
+                revision: page.revision,
+                events,
+                next: page.next,
+            },
+            text,
+        )
     }
 }