npm package: @oneqode/session-mcp
Description: Session MCP for Cracked Jacked Claude - Manages session state, progress tracking, and multi-agent coordination
Author: OneQode
Latest version: 1.0.0

# 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

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

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

## Usage with Claude

Add to your `.claude.json`:

```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.

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

### end_session
End the current session with a summary.

```typescript
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.

```typescript
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.

```typescript
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.

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

### get_session_history
Get recent session history.

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

### prepare_handoff
Prepare a handoff summary for the next session.

```typescript
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

```bash
# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev
```

## License

MIT © OneQode