GStreamer Logs MCP

MCP server for GStreamer debug logs. One load per file (cached); the agent uses filters (path, category, time range in ms, level, object_name, etc.) and gets counts before requesting lines, so context stays small. Time: integer milliseconds from log start only (e.g. 10000 = 10s, 10300 = 10.3s). Standalone repo: no external project dependencies.

Requirements

• Python 3.10+

Install

From this directory:

pip install -r requirements.txt

Run (stdio, for Cursor / Claude)

python server.py

Or with uv:

uv run server.py

Configuration

Cursor

In Cursor MCP settings, add a server that runs this script, for example:

{
  "mcpServers": {
    "gst-logs": {
      "command": "python",
      "args": ["C:\\path\\to\\gst_logs_mcp\\server.py"]
    }
  }
}

Use the path to your gst_logs_mcp clone and ensure the Python that has mcp installed is the one used by Cursor.

Time format

All time filters use integer milliseconds from log start only (no fractions). E.g. 10000 = 10s, 10300 = 10.3s. Use load_log first to get time_span so you can compute ms from the first timestamp.

Tools

Resource: gst-logs://agent-guide – same content as the agent guide (for clients that support MCP resources).

Workflow: 1) get_agent_guide (once). 2) list_log_files if path unknown. 3) load_log once per file → time_span, levels, categories, object_count. 4) log_summary or object_summary with filters (category + time in ms) → get counts. 5) If total_matching is small (≤100), query_logs with same category + time (+ optional object_name/level/search).

For agents: Call get_agent_guide_tool at the start, or read resource gst-logs://agent-guide. Full guide: AGENT_GUIDE_GST_LOGS_MCP.md.

Test (no MCP client)

From project root:

python scripts/test_mcp_tools.py

Uses the same core as the server; prints SENT/GOT for list_log_files, load_log, log_summary (with time in ms), object_summary, query_logs. Time in tests is integer milliseconds (e.g. 0, 5000, 10500). The folder gst_log_files/ is gitignored; set GST_LOGS_MCP_LOG_DIR to a directory that contains GStreamer debug logs, or add a small sample log for CI.