@dici1435/session-mcp

Filesystem-based session tracking MCP server for dici-spec projects. Tracks tasks, blockers, checkpoints, and generates structured handoff documents for multi-session work.

Installation

npm install -g @dici1435/session-mcp
# or run directly
npx @dici1435/session-mcp

Configured automatically by dici-spec init.

Tools

| Tool | Description | |---|---| | session_start | Start a new feature session. Creates a session file and sets it as active. | | session_save | Save a checkpoint in the active session to preserve progress | | session_done | Mark a task as complete (by ID, or first in-progress task) | | session_task | Add a new task or update an existing one (pending/in_progress/done/blocked) | | session_blocker | Log a new blocker or resolve an existing one | | session_status | Get full active session state: tasks, blockers, checkpoints, progress | | session_handoff | Generate a structured handoff document for a fresh agent context | | session_end | End the active session. Validates no unresolved blockers, writes summary. | | session_all | List all sessions with metadata: name, feature, status, task/blocker counts | | session_switch | Switch to a different existing (non-ended) session | | validate | Check the active session for issues: incomplete tasks, unresolved blockers, missing checkpoints |

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | PROJECT_ROOT | No | process.cwd() | Root directory for locating session files | | SESSIONS_DIR | No | .dici/sessions | Relative path under PROJECT_ROOT for session storage |

Session Lifecycle

session_start → session_task → session_save → session_done → session_end
                     ↕               ↕
              session_blocker   session_handoff

Sessions are stored as JSON files in .dici/sessions/. Each session tracks:

• Tasks with status (pending, in_progress, done, blocked)
• Blockers with timestamps and resolution status
• Checkpoints for progress preservation
• Start/end timestamps and summaries

Transport

Stdio (stdin/stdout). Designed to be launched by AI agent IDEs as a child process.

License

MIT