chajus1/seshos-im-mcp

SeshOS-IM MCP Server

A comprehensive MCP (Model Context Protocol) server that enables instant messaging and collaborative sessions between Claude instances and other participants. This server allows Claude Code sessions to become group chat environments where Claude Desktop, other LLMs, or human users can join and collaborate.

Features

• 🚀 Real-time Messaging: Powered by Redis streams and pub/sub
• 👥 Session Management: Create, join, and manage collaborative sessions
• 📝 Rich Content Support: Share code snippets, artifacts, and structured data
• 🧠 Cortex Integration: Automatic memory persistence and context injection
• 🔧 Daemon Management: Background processes for notifications and sync
• 🗣️ Natural Language Redis: Execute Redis operations using natural language
• 🎯 Session Types: Specialized modes for pair programming, code review, brainstorming, and debugging

Architecture

The server integrates four powerful subsystems:

1. Daemon Management

• Background process lifecycle control
• Notification monitoring
• Session data synchronization
• Participant presence tracking

2. Redis Operations

• Stream-based message storage
• Pub/sub for real-time delivery
• Natural language query interface
• Direct Redis command execution

3. IM Protocol

• Session creation and management
• Multi-participant support
• Message editing and deletion
• Reactions and threading
• Code and artifact sharing

4. Cortex Integration

• Automatic conversation persistence
• Context injection from memories
• Artifact collaboration
• Semantic search capabilities

Installation

Prerequisites

• Node.js 18+
• Redis server
• Cortex API (optional but recommended)

Setup

1. Clone and install dependencies:

git clone https://github.com/yourusername/seshos-im-mcp.git
cd seshos-im-mcp
npm install

2. Install and start Redis:

# Ubuntu/Debian
sudo apt-get install redis-server
redis-server

# macOS with Homebrew
brew install redis
brew services start redis

3. Configure environment:

cp .env.example .env
# Edit .env with your settings:
# - REDIS_URL (default: redis://localhost:6379)
# - CORTEX_API_URL (default: http://localhost:8000)
# - DEFAULT_USER_ID

4. Start the server:

npm start
# Or for development with auto-reload:
npm run dev

MCP Tool Reference

Session Management

im_create_session

Create a new collaborative session.

{
  "name": "Debug Session",
  "type": "debug_session",
  "host_id": "claude_code_1",
  "host_name": "Claude Code",
  "auto_context": true,
  "context_query": "debugging React hooks"
}

im_join_session

Join an existing session.

{
  "session_id": "sess_abc123",
  "participant_id": "claude_desktop_1",
  "participant_name": "Claude Desktop"
}

im_list_sessions

List available sessions.

{
  "active_only": true,
  "user_id": "claude_code_1",
  "include_participants": true
}

Messaging

im_send_message

Send a text message.

{
  "session_id": "sess_abc123",
  "participant_id": "claude_code_1",
  "content": "Found the issue in the useEffect hook"
}

im_send_code

Share code with syntax highlighting.

{
  "session_id": "sess_abc123",
  "participant_id": "claude_code_1",
  "code": "const [state, setState] = useState(initialValue);",
  "language": "javascript",
  "filename": "hooks.js"
}

im_share_artifact

Share a Cortex artifact.

{
  "session_id": "sess_abc123",
  "participant_id": "claude_desktop_1",
  "title": "API Documentation",
  "content": "# REST API Guide...",
  "artifact_type": "document"
}

Cortex Integration

cortex_inject_context

Inject relevant memories into session.

{
  "session_id": "sess_abc123",
  "query": "React performance optimization",
  "tags": ["react", "performance"]
}

cortex_save_session

Save session conversation to memory.

{
  "session_id": "sess_abc123",
  "importance": 8
}

Daemon Management

daemon_start

Start a background daemon.

{
  "type": "notifier",
  "config": {
    "session_id": "sess_abc123",
    "notify_participant": "claude_desktop_1"
  }
}

Session Types

• general: Standard chat with up to 10 participants
• pair_programming: 2-person coding session with shared workspace
• code_review: 5-person review with diffs and approval features
• brainstorming: 10-person ideation with voting and mind maps
• debug_session: 3-person debugging with logs and breakpoints

Example Workflow

1. Claude Code creates a session:

const session = await mcp.im_create_session({
  name: "Fix Login Bug",
  type: "debug_session",
  host_id: "claude_code",
  host_name: "Claude Code",
  auto_context: true,
  context_query: "authentication errors"
});

2. Claude Desktop joins:

await mcp.im_join_session({
  session_id: session.session.id,
  participant_id: "claude_desktop",
  participant_name: "Claude Desktop"
});

3. Share code and collaborate:

await mcp.im_send_code({
  session_id: session.session.id,
  participant_id: "claude_code",
  code: debugCode,
  language: "javascript",
  filename: "auth.js"
});

4. Save important sessions:

await mcp.cortex_save_session({
  session_id: session.session.id,
  importance: 9
});

Development

Project Structure

seshos-im-mcp/
├── src/
│   ├── index.js           # Main server entry
│   ├── daemon/            # Background process management
│   │   ├── manager.js
│   │   └── workers/
│   ├── redis/             # Redis client and operations
│   │   └── client.js
│   ├── cortex/            # Cortex API integration
│   │   └── client.js
│   ├── im/                # Instant messaging core
│   │   ├── sessions.js
│   │   └── messages.js
│   └── tools/             # MCP tool definitions
│       ├── daemon-tools.js
│       ├── redis-tools.js
│       ├── im-tools.js
│       └── cortex-tools.js

Running Tests

npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Troubleshooting

Redis Connection Issues

• Ensure Redis is running: redis-cli ping
• Check Redis URL in .env
• Verify firewall settings

Cortex Integration

• Confirm Cortex API is accessible
• Check API URL and user ID
• Review Cortex logs for errors

Message Delivery

• Monitor Redis streams: redis-cli xrange session:chat:SESSION_ID - +
• Check daemon logs for notification issues
• Verify participant subscriptions

License

MIT License - see LICENSE file for details

Acknowledgments

• Inspired by mcp-daemonize and mcp-redis
• Built for the SeshOS collaborative AI platform
• Integrated with Cortex memory system