Feature proposal: poll until combat play phase in get_game_state + lightweight hand-only MCP tools

[judgeou]

Why
In combat, get_game_state often returns battle.is_play_phase: false after end turn, so agents must poll manually. Between card plays, full state is heavier than needed when only hand / energy / hand_select matter (indices shift every play).

Proposal
get_game_state: If JSON shows combat with is_play_phase === false, poll until it becomes playable or a max wait elapses; on timeout return a short explicit response (no infinite hang).

New tools: get_game_state_handcard and mp_get_game_state_handcard — same game JSON fetch, return only hand-related fields (+ energy, etc.) in markdown/json for cheap refreshes between plays.

judgeou@8c6b3bb

[fanqiNO1]

Thank you so much for pointing this out!

This field (battle.is_play_phase) reflects the real-time game state, so we don't force the calculations to complete immediately. For instance, when it's the enemy's turn or an animation is still playing, battle.is_play_phase is false.

I said the animation is blocking me from starting. lol
我说动画卡我启动了 😄

A better solution is actually to allow skipping this animation, and conveniently, the base game already has this option. We will release an update in v0.3.2 to fix this by unlocking instant mode (PR #21), which makes all animations and calculations instant.

[Gennadiyev]

Regarding the get hand function, it can effectively reduce the number of tokens used per state. Thanks for your idea.

Inspired by your tool, I'm thinking about adding an optional &delta=1 parameter in API calls and expose it to the MCP server.

It will show only the delta of state compared to the previous get_state, on the MCP level. Also more context-friendly (#11).

@fanqiNO1 your thoughts on this?

[fanqiNO1]

Emm, I believe that while setting delta=1 can effectively reduce token usage, it may place a heavier burden on the model's ability to understand context. This is because the model needs to combine the state obtained in the previous step and then analyze the current situation based on the delta. If the model repeatedly uses delta=1, as in the following sequence:

full state (S1) -> delta state (S2 - S1) -> delta state (S3 - S2?)

The model might even need to continuously retain the initial full state in memory, which imposes higher demands on its multi-turn capabilities.

I think the delta approach is promising, but it requires more thorough testing or should be implemented as an independent tool.

[judgeou]

it may place a heavier burden on the model's ability to understand context.

Yes—but this is precisely the test I’m putting the large language models through. If they can't handle this, it proves they aren't up to the task.

[judgeou]

I’ve come up with an even better idea: judgeou@196192c

By waiting one second after calling combat_play_card before returning the content from get_game_state, we directly reduce the number of round-trips. The tokens saved by doing this far outweigh the savings gained from merely pruning the game state.

I’ve tested this myself, and I feel the AI's decision-making flows much more smoothly than before.

[Gennadiyev]

Looks highly promising. This fundamentally change how the model interacts with the game, and what's more impressive is that it is an MCP server side edit.

Please create a PR for this. I will discuss a bit and come back to you soon.

[judgeou]

#34

I only applied a similar operation to combat_play_card and rewards_claim, but I feel that it might be necessary for other functions as well.

[jamesmcm]

I think a pain here is that many harnesses cache MCP server results e.g. tools available - assuming they do not change, as that is what the MCP protocol specifies (i.e. it does not expect dynamic changes in tools).

In my case I wrote a little CLI wrapper around it that does this filtering (and waiting for animations to finish), so the agent can use that directly, it's still work in progress though - https://github.com/jamesmcm/sts2harness

Thanks so much for STS2MCP btw! Before I found it I was trying to do this with memory scanning and simulating a gamepad, but it was extremely brittle (see https://github.com/jamesmcm/StS2Agent ) - especially the UI detection as inactive nodes aren't removed in memory, etc.