mcp-session-logging

MCP Session Logging

Record every meaningful unit of work as an McpServer session-log turn using the mcpserver plugin workflow.sessionlog.* methods. A turn is begun before work starts, enriched with dialog, actions, and design decisions while work proceeds, and then completed (success) or failed (error). All session state is owned by the McpServer; you interact with it only through the plugin API.

When to Use

• You are about to start work on a user message or task inside an McpServer workspace.
• You finished a meaningful change (edit, commit, decision, requirement, blocker) and need to persist it.
• You need to record reasoning, tool output, or a design decision for audit.
• You are wrapping up or aborting work and must close the active turn.
• You need to review recent session history before acting (queryHistory).

When Not to Use

• Trivial read-only lookups that the parent turn already covers (do not open a new turn per file read).
• TODO CRUD (use the TODO skill / workflow.todo.*), requirements (workflow.requirements.*), or GraphRAG work; those have their own skills.
• Any situation where signature verification, /health, or nonce verification has failed: log MCP_UNTRUSTED and continue without the MCP server.

Inputs

• The active marker file AGENTS-README-FIRST.yaml in the workspace root (API key, endpoints, base URL). Re-read it on any 401.
• Your real agent identity in Pascal-Case (for example ClaudeCode, Copilot), used as the agent / sourceType prefix.
• The current model name (for example claude-opus-4-8).
• The user's prompt or task text (for queryTitle / queryText and for the request-id slug).

Critical Rules

• NEVER read, edit, or write session-log files (or todo.yaml) directly with Read, Edit, Write, Grep, or shell. The plugin API is the only allowed interface.
• Begin the turn BEFORE doing the work, not after.
• Persist immediately after each meaningful change. Do not batch saves to the end.
• Use your real Pascal-Case agent identity. Never use placeholder or misleading sourceType values.
• Session id format: <Agent>-<yyyyMMddTHHmmssZ>-<suffix>; must start with the exact agent prefix (case-sensitive). Regex: ^[A-Z][A-Za-z0-9]*-\d{8}T\d{6}Z-[a-z0-9]+(?:-[a-z0-9]+)*$.
• Request id format: req-<yyyyMMddTHHmmssZ>-<seq>-<slug-from-prompt> where yyyyMMddTHHmmssZ is the UTC time the turn begins, <seq> is a zero-padded 3-digit per-session counter (001, 002, ...), and <slug> is a lowercase kebab-case truncation (~40 chars) of the prompt with articles and filler dropped. Regex: ^req-\d{8}T\d{6}Z-[a-z0-9]+(?:-[a-z0-9]+)*$.
• The requestId passed to beginTurn is the turn's identity; reuse that SAME requestId for appendDialog, appendActions, updateTurn, completeTurn, and failTurn so they bind to the turn.
• Log design decisions twice: as an appendDialog item with category: decision, and as an appendActions action with type: design_decision.
• A completed or failed turn is immutable (turn_immutable); make all updates before closing it.
• No em-dashes in any logged text.