Add MCP server (v1: session_query)

[zh4ngx]

Summary

Adds a stackunderflow.mcp submodule — a Model Context Protocol server (FastMCP, stdio transport) that exposes session-log queries to MCP clients. v1 ships one tool, session_query.

Design: stateless, adapter-imported

The MCP imports stackunderflow.adapters.claude.ClaudeAdapter and parses JSONL files directly — it never touches SQLite, ingest, or ~/.stackunderflow/store.db. The adapter layer is the canonical normalised form; SQLite is downstream of it.

Why this beats wrapping the SQL store / HTTP API:

• Schema-evolution insulated. The store schema is owned by StackUnderflow and can change without warning. The adapter contract — SessionRef + Record frozen dataclasses — is the same surface every adapter has to satisfy and is the most stable point in the codebase.
• No ingest dependency. The MCP works whether or not the user has ever run stackunderflow init / reindex. It just reads the JSONL files that already exist on disk.
• Stateless and fast. No connection pool, no DB lock contention, no migrations. A query is "scan files in mtime order, parse, filter, sort, return."
• Multi-agent out of the box. v1 already iterates ~/.claude, ~/.claude-opus, ~/.claude-sonnet, ~/.claude-haiku, ~/.claude-glm (anything in Claude Code JSONL format). Adding ~/.opencode/, etc. is one line in DEFAULT_AGENT_ROOTS once a parser exists.

v1 surface

session_query(
    session_id: str | None = None,
    limit: int = 20,
    kind: Literal["tool_calls", "errors", "all"] = "all",
) -> list[dict]

Returns timestamp-sorted, most-recent-first events with: agent, project_slug, session_id, timestamp, role, model, tools, tool_calls (name + summarised args), content_preview, is_sidechain, uuid.

tool_calls filter returns only assistant records with at least one tool_use block. errors filter returns records whose tool_result blocks are flagged is_error or contain "error" / "exception" / "traceback" text.

Run

pip install -e .
stackunderflow-mcp     # stdio MCP server

Or wire into a Claude Desktop / agent config:

{
  "mcpServers": {
    "stackunderflow": {
      "command": "stackunderflow-mcp"
    }
  }
}

v2 path (not in this PR)

• git_state(cwd) — current branch / dirty status / recent commits for a project root, so the agent can check repo state without shelling out
• process_state(filter) — recent processes that an agent spawned (build runs, dev servers), pulling from session logs' Bash tool results

Both fit naturally as additional @mcp.tool() functions in server.py without schema changes elsewhere.

Files

• stackunderflow/mcp/__init__.py, stackunderflow/mcp/server.py — module
• tests/stackunderflow/test_mcp.py — 10 smoke tests
• pyproject.toml — mcp>=1.2.0 dep, stackunderflow-mcp console script
• requirements.txt — mcp>=1.2.0
• flake.nix — python3Packages.mcp in propagated inputs + dev shell

Test plan

• python -m pytest tests/stackunderflow/test_mcp.py -v — 10/10 pass
• python -m pytest tests/stackunderflow/ — 430 pass, 2 skipped, no regressions
• ruff check stackunderflow/mcp/ tests/stackunderflow/test_mcp.py — clean
• ruff format --check — clean
• mypy stackunderflow/mcp/ — clean (no new errors)
• Manual stdio smoke: python -m stackunderflow.mcp.server responds to initialize + tools/list correctly

🤖 Generated with Claude Code

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​mcp@​1.27.0

View full report

[zh4ngx]

Heads-up before further iteration on this PR

I've been exploring cortexkit/opencode-magic-context, which tackles overlapping problem space from a different angle — in-prompt active rewriting via background Historian + Dreamer agents (replaces opencode's native compaction with cache-aware deferred summarization) vs stack-underflow's observability/forum approach.

The architectures feel complementary rather than competing to me — Magic Context is the runtime memory manager, stack-underflow is the post-hoc observability layer + cross-agent knowledge base. But session_query here may overlap with their ctx_search. Want to make sure I'm not duplicating either system before going further.

Holding off on extending this MCP (was planning a git_state v2) until we sync. Happy to reframe scope to slot alongside whatever you've got going on. Will Signal you separately for a casual catch-up.

No rush — comment when you have a sec.

[0bserver07]

Rebased onto current main (which has #14's E501 lint fix) so CI could go green. No code changes to your commit beyond the rebase. All checks pass — merging now. Thanks for the contribution!

[zh4ngx]

Thanks for the rebase! Standing by — let me know if anything else needs attention from my side.

[0bserver07]

Merged as 2c44d68 — thanks @zh4ngx, this is a great surface to add.

Did a real smoke test against my local logs after the merge to make sure it actually works end-to-end:

• discover_sessions() picked up 1018 session files under ~/.claude/projects/
• session_query(limit=5, kind="all") returned the most recent 5 events from my active session, timestamps + roles all correct
• kind="tool_calls" filter caught real Bash invocations from this session
• kind="errors" filter caught 3 error records

One small cosmetic note (not a regression — flagging for a future polish PR): records returned under kind="errors" come back with content_preview="". The _is_error_record heuristic correctly finds error blocks inside nested tool_result content, but content_preview is sourced from Record.content_text which doesn't include nested tool-result text. So the AI calling the tool sees "this is an error" but no preview of what the error was. Easy fix in a follow-up — surface the matched error string into the preview when kind="errors".

Also added a tiny follow-up commit (#16) with a CHANGELOG entry crediting your contribution.

For anyone reading this later: the MCP exposes one tool — session_query(session_id, limit, kind) — that any MCP client (Claude Desktop, Claude Code, Cursor) can call to introspect local Claude-Code session logs without going through StackUnderflow's SQLite store. Stateless, fast, and architecturally insulated from schema changes since it imports the adapter layer directly. Wire-up:

{
  "mcpServers": {
    "stackunderflow": { "command": "stackunderflow-mcp" }
  }
}

Then ask Claude things like "what tools did I run in the last hour" or "find my last error".

[zh4ngx]

Thanks for actually merging + smoke-testing against your real corpus — 1018 sessions is a meaningful end-to-end signal. The kind="errors" content_preview="" quirk is real; happy to take a polish PR for that whenever, the fix is sourcing the matched error string from nested tool_result blocks into the preview field. CHANGELOG credit appreciated.

On the broader coordination question — I think session_query and your AgentDetector are genuinely complementary primitives along the artifact-vs-state and read-vs-write axes:

• session_query answers "what artifacts did agent X produce?" by reading immutable JSONL traces — a historical read-path with no side effects
• AgentDetector answers "what processes are running right now?" by reading live OS state — a live observability path that can optionally feed into control decisions (kill, migrate, etc.)

An orchestrator naturally wants both. I'd resist consolidating them into one tool — different substrates, different staleness profiles, different failure modes. But surfacing both via MCP and letting clients compose feels right. If Novalis already exposes AgentDetector via MCP (or could), they'd slot together cleanly without either repo needing to absorb the other.

Adjacent piece I just shipped: zellij-mcp — small Rust MCP server with 6 pane-id-addressed tools (list/spawn/send-text/read/focus/kill). Same compositional approach: it's the live write-path (control plane: spawn, send, kill) sitting orthogonal to your two read-paths, completing the trio — historical read (session_query), live read (AgentDetector), live write (zellij-mcp). Might be useful for Novalis automation if you ever want to drive panes from outside the GUI.

No rush on any of this — happy to continue async or hop on Signal when convenient.

— drafted by Kimi K2.6 (OpenCode Go) on behalf of Andy; human-reviewed before posting