Skip to main content
Glama
AstralVoidZ

ppsspp-dfx

by AstralVoidZ
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

ppsspp_health

Read-onlyIdempotent

Probe the MCP server for liveness and readiness, and optionally run a four-point session health check to verify emulator state without modifying it.

Instructions

PURPOSE: Probe MCP server liveness and readiness — plus an optional four-point session health battery.

USAGE: no args for the server-level probe (does NOT contact PPSSPP); pass session_id to also run the session battery (iso_loaded / cpu_running / ws_connected / game_mode_valid — absorbed from the former ppsspp_smoke_test tool).

BEHAVIOR: READ-ONLY. Server counters are read in-memory; the session battery (when requested) contacts PPSSPP over the session transport but never mutates state.

READING session_checks: each entry carries value_status besides passed -- 'ok' (the probe really read), 'stale_address_suspected' (the read succeeded and returned zero on several consecutive readings, so the probe address may have drifted -- a suspicion, not a verdict), 'failed' (the read raised or the data was absent; no value is reported), 'not_configured' (no probe address, so nothing was read). A probe that READ ZERO and one that COULD NOT READ both show passed=false while meaning opposite things: the first is a fact about the game, the second about the tooling. Do not read passed=false alone as a finding about the emulated game.

RETURNS: Dict with status ('ok'/'degraded'), version, python_version, pydantic_version, uptime_s, tool_count, session_count — plus session_checks: [{name, passed, detail, value_status, value?}] and overall_session_status when session_id is provided.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
session_idNoOptional session ID — when provided, appends session_checks (the four-point battery: iso_loaded / cpu_running / ws_connected / game_mode_valid, absorbed from ppsspp_smoke_test) to the server-level report. Omit for the zero-contact server liveness probe.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
statusYesServer status: 'ok' when all subsystems healthy; 'degraded' when sessions.json is inaccessible/corrupted but server is otherwise functional.
versionYesMCP server version.
uptime_sYesServer uptime in seconds.
tool_countYesNumber of registered MCP tools.
session_countYesNumber of active sessions.
session_errorYesWhen status='degraded', describes the sessions.json issue (e.g. 'FileNotFoundError: ...' or 'JSONDecodeError: ...'). None when sessions.json is healthy.
python_versionYesPython interpreter version.
session_checksNo
pydantic_versionYesPydantic version.
overall_session_statusNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.7
    • addedOutput schema / $defs / _HealthSessionCheck / properties / value
      Added value: +{
+  "title": "Value",
+  "type": "integer"
+}
    • addedOutput schema / $defs / _HealthSessionCheck / properties / value_status
      Added value: +{
+  "title": "Value Status",
+  "type": "string"
+}
    • changedOutput schema / description
      Previous value: -"HealthOutput + the per-session battery keys added when `session_id`\nis given (M9: they previously existed only in the text channel — the\noutput contract dropped them from structuredContent)."New value: +"HealthOutput + the per-session battery keys added when `session_id`\nis given. They previously existed only in the text channel — the\noutput contract dropped them from structuredContent."
  2. Changed6 schema fields changedv0.1.6
    • addedInput schema / properties / session_id
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional session ID — when provided, appends session_checks (the four-point battery: iso_loaded / cpu_running / ws_connected / game_mode_valid, absorbed from ppsspp_smoke_test) to the server-level report. Omit for the zero-contact server liveness probe.",
+  "title": "Session Id"
+}
    • addedOutput schema / $defs
      Added value: +{
+  "_HealthSessionCheck": {
+    "properties": {
+      "detail": {
+        "title": "Detail",
+        "type": "string"
+      },
+      "name": {
+        "title": "Name",
+        "type": "string"
+      },
+      "passed": {
+        "title": "Passed",
+        "type": "boolean"
+      }
+    },
+    "title": "_HealthSessionCheck",
+    "type": "object"
+  }
+}
    • addedOutput schema / description
      Added value: +"HealthOutput + the per-session battery keys added when `session_id`\nis given (M9: they previously existed only in the text channel — the\noutput contract dropped them from structuredContent)."
    • addedOutput schema / properties / overall_session_status
      Added value: +{
+  "title": "Overall Session Status",
+  "type": "string"
+}
    • addedOutput schema / properties / session_checks
      Added value: +{
+  "items": {
+    "$ref": "#/$defs/_HealthSessionCheck"
+  },
+  "title": "Session Checks",
+  "type": "array"
+}
    • changedOutput schema / title
      Previous value: -"HealthOutput"New value: +"HealthWithSessionChecks"
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description nonetheless adds meaningful context: the server probe never contacts PPSSPP, the session battery contacts the transport but never mutates, and it deeply explains value_status semantics, crucially warning that passed=false can mean opposite things (read-zero vs could-not-read). This is above-and-beyond disclosure, though it stops short of e.g. counter/pagination caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded sectioned structure (PURPOSE/USAGE/BEHAVIOR/READING/RETURNS) with every block earning its place; the READING section is long but carries high-value disambiguation for interpreting passed vs value_status. Slightly verbose but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still summarizes the return shape (status, version, uptime, tool_count, session_checks, overall_session_status) and explains how to interpret the fields, which is exactly what an agent needs to act on the result. Nothing required to call or interpret the tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is already well documented, so baseline is 3; the description adds the enumeration of the four battery checks and clarifies that omitting session_id yields the zero-contact probe, giving more meaning than the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (probe server liveness/readiness plus an optional session health battery) and explicitly separates the server-level probe from the session battery, distinguishing it from siblings like ppsspp_state_observer and ppsspp_session. An agent can identify this as the health/diagnostic tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: no args for the server-level probe (no PPSSPP contact), pass session_id to also run the four-point session battery. It also names the absorbed former tool (ppsspp_smoke_test), so an agent migrating from that tool knows where it went.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools