feat: add MCP resources for sessions, screenshots, and recordings

[dwmkerr]

Summary

Add MCP resources to allow LLMs to browse sessions and their outputs without needing filesystem access.

Proposed Resources

Sessions

Resource URI	Description
sessions://list	List all active shell sessions
session://{id}/info	Session details (cols, rows, command, recording status)
session://{id}/buffer	Current terminal buffer content
session://{id}/screenshots	List screenshots taken in this session
session://{id}/recordings	List recordings from this session

Example Usage

LLM: "What sessions do I have open?"
→ Read resource: sessions://list
← [{ id: "shell-session-a1b2c3", command: "bash", cols: 80, rows: 24 }]

LLM: "What screenshots did I take?"
→ Read resource: session://shell-session-a1b2c3/screenshots
← [{ name: "step1.png", download_url: "...", created: "..." }]

Benefits

• LLMs can discover what they've captured without filesystem access
• Works with MCP clients that don't have Bash/file read tools (Claude Desktop, ChatGPT)
• Complements feat: add inline image response mode for broader MCP client compatibility #27 (inline images) - resources list what's available, inline mode returns content

Implementation Notes

• Resources are read-only views of existing session state
• Screenshot/recording lists already tracked internally
• Could optionally return inline base64 for image resources (ties into feat: add inline image response mode for broader MCP client compatibility #27)

Related Issues

• feat: add inline image response mode for broader MCP client compatibility #27 - Add inline image response mode for broader MCP client compatibility

[dwmkerr]

Implementation Plan

Effort Estimate

~100-150 lines of code, medium complexity

Changes Required

1. Track screenshots/recordings per session

Currently not tracked. Add to Session interface:

interface Session {
  // ... existing fields
  screenshots: { name: string, path: string, created: Date }[];
  recordings: { name: string, path: string, created: Date }[];
}

2. Register resource templates

// List all sessions
server.resource("sessions", "sessions://list", readCallback);

// Session info  
server.resource("session", new ResourceTemplate("session://{id}"), readCallback);

// Session screenshots/recordings
server.resource("screenshots", new ResourceTemplate("session://{id}/screenshots"), readCallback);
server.resource("recordings", new ResourceTemplate("session://{id}/recordings"), readCallback);

// Individual files (optional - could return base64)
server.resource("screenshot", new ResourceTemplate("session://{id}/screenshots/{name}"), readCallback);
server.resource("recording", new ResourceTemplate("session://{id}/recordings/{name}"), readCallback);

3. Update tools to track files

• shell_screenshot → push to session.screenshots[]
• shell_record_stop → push to session.recordings[]

---

LLM Client Support

Resources work differently from tools - the LLM must explicitly request to read them. Current support varies:

Client	Resource Support	Notes
Claude Desktop	✅	Shows resources in UI, LLM can request
Claude Code	⚠️ Partial	Has listMcpResources but reading less common
Cursor	❓	Varies by version
ChatGPT + MCP	❓	Unknown

Important caveat: LLMs aren't great at proactively discovering and using resources yet. They work better with explicit tool calls. Resources are most useful when clients surface them in their UI.

The intended flow:

1. LLM calls shell_screenshot → gets { download_url: "..." }
2. If LLM can't curl the URL, it reads resource session://{id}/screenshots/{name}
3. Resource returns inline base64 content

This means resources complement rather than replace the inline image option (#27).

[dwmkerr]

Additional Resource: Themes

With the theme metadata added in PR #35, themes could also be exposed as an MCP resource:

Resource URI	Description
themes://list	List all available themes with metadata
theme://{name}	Theme details (name, type, description, colors)

This would allow LLMs to:

• Discover available themes programmatically
• Choose themes based on context (light/dark, use case)
• Get theme recommendations via the tip field

Example:

LLM: "What themes are available?"
→ Read resource: themes://list
← [{ name: "one-dark", type: "dark", description: "Dark theme with muted, balanced colors", tip: "Works well for most use cases" }, ...]