Session MCP 🗂️

The Session MCP (Model Context Protocol) server manages session state, progress tracking, and multi-agent coordination for the Cracked Jacked Claude framework.

Features

• Session Management: Start, end, and track development sessions
• Progress Tracking: Log task progress with evidence
• Decision Recording: Document architectural and technical decisions
• Multi-Agent Support: Track sessions across multiple agents
• Handoff Preparation: Prepare context for session transitions

Installation

# Global installation
npm install -g @oneqode/session-mcp

# Or use via npx
npx @oneqode/session-mcp

Usage with Claude

Add to your .claude.json:

{
  "mcpServers": {
    "session": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@oneqode/session-mcp@latest"],
      "description": "Session state management and progress tracking"
    }
  }
}

Available Tools

start_session

Start a new development session.

session.start_session({
  project_name: "my-project",
  session_type: "development",
  agent_id: "agent-1"
})

end_session

End the current session with a summary.

session.end_session({
  summary: "Implemented user authentication with JWT",
  next_steps: [
    "Add refresh token rotation",
    "Implement password reset flow",
    "Add 2FA support"
  ]
})

log_progress

Log progress on a task.

session.log_progress({
  task_id: "task-123",
  status: "completed",
  details: "Implemented JWT authentication with tests",
  evidence: [
    "screenshots/auth-flow.png",
    "test-results/auth.test.js"
  ]
})

log_decision

Record an architectural or technical decision.

session.log_decision({
  decision: "Use JWT for authentication",
  rationale: "Stateless, scalable, and well-supported",
  alternatives: ["Session-based auth", "OAuth2"],
  impact: "Requires token refresh mechanism"
})

get_session_state

Get the current session state.

session.get_session_state()
// Or specific session:
session.get_session_state({ session_id: "abc123" })

get_session_history

Get recent session history.

session.get_session_history({
  limit: 10,
  project_name: "my-project"
})

prepare_handoff

Prepare a handoff summary for the next session.

session.prepare_handoff()
// Returns current session, recent sessions, active tasks, and recent decisions

Session Types

• development: General development work
• debugging: Debugging and troubleshooting
• planning: Project planning and architecture
• review: Code review and refactoring

Storage

Sessions are stored in ~/.session-mcp/sessions.json as a JSON file for simplicity and portability.

Multi-Agent Coordination

When multiple agents are working on the same project, each can have its own session with an agent_id. The system tracks:

• Which agent worked on what
• Task handoffs between agents
• Parallel work streams

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

License

MIT © OneQode