feat(mcp-server): add report_session_done and get_worktree_diff tools, document MCP server

[liam-russell]

Type

• feat — new feature or user-visible capability

Summary

• Added a report_session_done MCP tool so an external agent can tell SproutGit it finished a session of work in a worktree — surfaced to the user as a toast in the workspace.
• Added a get_worktree_diff MCP tool so an agent can review its own working-tree diff (optionally scoped to one file) before reporting done.
• Added docs/mcp-server.md, a full reference for every MCP tool (parameters, return shapes, which are gated behind the mutating-tools permission, and an example session).

Why

Issue #99: packages/mcp-server existed but was undocumented, and was missing the report_session_done capability called out in the original proposal (docs/improvement-ideas.md). list_worktrees and create_worktree already covered the other two examples from that proposal.

Screenshots / recordings

Backend/tool-layer change; the only renderer touches are a one-line Settings description update and a new toast triggered by an MCP tool call (no static layout change to screenshot). Did not spin up the full Electron app to trigger the toast live — verified the event dispatch end-to-end instead via a real HTTP call into a running MCP server in app/src/main/__tests__/mcp-bridge.test.ts (asserts webContents.send receives the right EVENT_MCP_SESSION_DONE payload).

Breaking changes

None. McpServerContext gained a new required reportSessionDone field, but it's an internal type owned by this repo (packages/mcp-server + its one consumer, app/src/main/mcp-bridge.ts), both updated together.

Test plan

• pnpm lint && pnpm typecheck && pnpm test — all green across the workspace.
• New unit tests for get_worktree_diff/report_session_done handlers in packages/mcp-server/src/__tests__/tools.test.ts (including the known-worktree validation and mock-forwarding behavior).
• New end-to-end test in app/src/main/__tests__/mcp-bridge.test.ts that calls report_session_done over a real HTTP MCP request and asserts the renderer push event, plus a no-open-window no-op case.
• Updated packages/mcp-server/src/__tests__/http-server.test.ts's tools/list assertion to include the two new tool names.

[Copilot]

Pull request overview

Adds two new MCP server tools (get_worktree_diff, report_session_done) and wires report_session_done through main → preload → renderer so SproutGit can notify the user (toast) when an external agent reports it finished work in a worktree. Also introduces a comprehensive MCP server reference doc covering all tools and expected shapes.

Changes:

• Implemented and registered get_worktree_diff and report_session_done tool handlers (with shared “known worktree” validation).
• Added a new main→renderer push event (EVENT_MCP_SESSION_DONE) plus renderer listener/toast and preload API surface.
• Added/updated unit + integration tests and wrote docs/mcp-server.md as a full tool reference.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/types/src/mcp.ts	Adds McpSessionDoneEvent payload type for the renderer push event.
packages/types/src/ipc.ts	Adds IPC.EVENT_MCP_SESSION_DONE constant for main→renderer notifications.
packages/mcp-server/src/tools.ts	Adds handlers + tool registrations for get_worktree_diff and report_session_done; refactors worktree validation into assertKnownWorktree.
packages/mcp-server/src/context.ts	Extends McpServerContext with reportSessionDone callback for host-app notification.
packages/mcp-server/src/tests/tools.test.ts	Adds handler-level tests for the two new MCP tools (diff + session done forwarding/validation).
packages/mcp-server/src/tests/http-server.test.ts	Updates HTTP server context stub + tools/list assertions to include new tool names.
docs/mcp-server.md	New end-to-end documentation for MCP server enablement, security model, tool reference, and example session.
docs/agent-instructions.md	Documents packages/mcp-server/ in the repo layout list and links to the MCP server doc.
app/src/renderer/settings/McpSection.tsx	Updates Settings copy to mention diffs and session-done reporting.
app/src/renderer/routes/workspace.tsx	Adds renderer-side listener that toasts on EVENT_MCP_SESSION_DONE.
app/src/preload/index.ts	Adds api.onMcpSessionDone bridge wiring IPC event to renderer callbacks.
app/src/main/mcp-bridge.ts	Implements reportSessionDone in the MCP server context by pushing EVENT_MCP_SESSION_DONE to the workspace window (if present).
app/src/main/tests/mcp-bridge.test.ts	Adds an end-to-end test calling report_session_done over real HTTP and asserting webContents.send.