sxn 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52c6ed94883c7981bdbc6bc0a2faa9d800dbe81fd4af0ee7af41dda777e95421
-  data.tar.gz: 1724ced66383451b1d914285b996a8d2c8bc82643fb08a0eb674a8c0c23a6e06
+  metadata.gz: 18c432e0aba5fd629beff742c41347cb97feede6e7bf9dfa907b8009c9ec6c03
+  data.tar.gz: 571a53c506eec48fbeecd78ce515f1e8b4d1bcec7e2daf72529e34c87e5686b5
 SHA512:
-  metadata.gz: ec072a5436b75710595263f5667828a83d0c5c42aa44f8cde622550762b30fd1ce3b244636bbf57df70b89eeda2c765abbfd04b6b80ff3c4998358e8bad4afe2
-  data.tar.gz: d1d7fa0c3acc68746767376f8f201004c74e8930ce8069b69aa4ad080b7338d4f21da7743cfd704e20746e942ddeca497fc7baa7f81c3a4d7c638e3b6a8437eb
+  metadata.gz: 6546d482da2b04f1186a08d3b7c10780e86e8b5caf08578d3d23ed2cdf7fe0031816e7e9447c835395dab5fda9f19f4f8487f28a883e0386572d109133a0131d
+  data.tar.gz: 7fad5c531582afe4f1e82109567ea152fc4ced391e4478a6c4d7e7e4f18b0b7790e37a6e99b8a5383217c21574b8e4b3b781efa8f36ff2936b18f6b4e8e4088b

data/CHANGELOG.md

@@ -5,19 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.3.0] - 2025-12-16
+## [0.4.0] - 2025-12-17
 
 ### Added
-- Session templates support for creating sessions from predefined configurations
-  - `sxn templates list` to view available templates
-  - `sxn templates show <name>` to view template details
-  - `--template` option for `sxn sessions add` to create sessions from templates
-- TemplateManager for template operations and validation
-- TemplatesConfig for loading templates from `templates.yml`
-- Session template error classes for better error handling
-
-### Fixed
-- Project rules now correctly apply when creating sessions from templates
+- **MCP Server**: Model Context Protocol server for AI assistant integration
+  - Enables Claude Code and other AI assistants to manage sessions programmatically
+  - STDIO and HTTP transport support
+  - Session management tools: create, list, get, delete, archive, activate, swap
+  - Worktree management tools: list, add, remove
+  - Project management tools: list, add, get
+  - Template and rules tools for automation
+  - Guided workflow prompts for session creation
+  - Dynamic resources for session data access
+- New CLI command: `sxn mcp start` to launch the MCP server
+- New binary: `sxn-mcp` for direct MCP server execution
+- `--template` option for `sxn sessions add` command
+
+### Documentation
+- Added MCP_IMPLEMENTATION.md with architecture and usage details
 
 ## [0.2.5] - 2025-11-30
 
@@ -115,8 +120,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial placeholder release
 - Basic gem structure
 
-[0.3.0]: https://github.com/idl3/sxn/compare/v0.2.5...v0.3.0
-[0.2.5]: https://github.com/idl3/sxn/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/idl3/sxn/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/idl3/sxn/compare/v0.2.1...v0.2.3
 [0.2.1]: https://github.com/idl3/sxn/compare/v0.2.0...v0.2.1

data/Gemfile.lock

@@ -1,13 +1,14 @@
 PATH
   remote: .
   specs:
-    sxn (0.3.0)
+    sxn (0.4.0)
       async (~> 2.0)
       bcrypt (~> 3.1)
       dry-configurable (~> 1.0)
       json-schema (~> 4.0)
       liquid (~> 5.4)
       listen (~> 3.8)
+      mcp (~> 0.4)
       openssl (>= 3.0)
       ostruct
       parallel (~> 1.23)
@@ -127,6 +128,7 @@ GEM
     json (2.13.2)
     json-schema (4.3.1)
       addressable (>= 2.8)
+    json_rpc_handler (0.1.1)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     liquid (5.8.7)
@@ -136,6 +138,9 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
+    mcp (0.4.0)
+      json-schema (>= 4.1)
+      json_rpc_handler (~> 0.1)
     memory_profiler (1.1.0)
     metrics (0.13.0)
     mini_mime (1.1.5)

data/bin/sxn-mcp

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "sxn"
+require "sxn/mcp"
+
+# Parse command line options
+require "optparse"
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: sxn-mcp [options]"
+
+  opts.on("-w", "--workspace PATH", "Workspace path (default: auto-discover)") do |path|
+    options[:workspace] = path
+  end
+
+  opts.on("-t", "--transport TYPE", "Transport type: stdio (default), http") do |type|
+    options[:transport] = type
+  end
+
+  opts.on("-p", "--port PORT", Integer, "HTTP port (default: 3000)") do |port|
+    options[:port] = port
+  end
+
+  opts.on("-v", "--version", "Show version") do
+    puts "sxn-mcp #{Sxn::VERSION}"
+    exit
+  end
+
+  opts.on("-h", "--help", "Show help") do
+    puts opts
+    exit
+  end
+end.parse!
+
+# Create and run server
+begin
+  server = Sxn::MCP::Server.new(workspace_path: options[:workspace])
+
+  case options[:transport]
+  when "http"
+    port = options[:port] || 3000
+    warn "Starting sxn MCP server on http://localhost:#{port}"
+    server.run_http(port: port)
+  else
+    # Default to stdio transport
+    server.run_stdio
+  end
+rescue Interrupt
+  # Clean exit on Ctrl+C
+  exit 0
+rescue StandardError => e
+  warn "Error: #{e.message}"
+  warn e.backtrace.first(5).join("\n") if ENV["SXN_DEBUG"]
+  exit 1
+end

data/docs/MCP_IMPLEMENTATION.md

@@ -0,0 +1,425 @@
+# SXN MCP Server & Claude Code Plugin Implementation Plan
+
+## Overview
+
+Build an MCP (Model Context Protocol) server for sxn that enables Claude Code to manage development sessions, worktrees, templates, and rules. Then enhance with a Claude Code plugin for richer UX.
+
+## Architecture
+
+### Phase 1: MCP Server (`sxn-mcp`)
+A standalone MCP server using the official Ruby SDK that exposes sxn operations as tools, resources, and prompts.
+
+### Phase 2: Claude Code Plugin
+A plugin that bundles the MCP server with slash commands, hooks, and skills for enhanced Claude Code integration.
+
+---
+
+## Phase 1: MCP Server Implementation
+
+### Dependencies
+
+Add to `sxn.gemspec`:
+```ruby
+spec.add_dependency "mcp", "~> 0.4"  # Official Anthropic/Shopify Ruby SDK
+```
+
+Note: `async` (~2.0) and `json-schema` (~4.0) already present in gemspec.
+
+### File Structure
+
+```
+lib/sxn/
+├── mcp/
+│   ├── server.rb                 # Main MCP server class
+│   ├── tools/
+│   │   ├── base_tool.rb          # Shared tool functionality + error mapping
+│   │   ├── sessions.rb           # Session CRUD tools
+│   │   ├── worktrees.rb          # Worktree management tools
+│   │   ├── projects.rb           # Project management tools
+│   │   ├── templates.rb          # Template tools
+│   │   └── rules.rb              # Rules tools
+│   ├── resources/
+│   │   └── session_resources.rb  # Read-only context resources
+│   └── prompts/
+│       └── workflow_prompts.rb   # User-initiated workflow prompts
+├── mcp.rb                        # Module loader
+bin/
+└── sxn-mcp                       # Executable for MCP server
+```
+
+### MCP Tools
+
+#### Session Tools
+| Tool | Description |
+|------|-------------|
+| `sxn_sessions_list` | List sessions with optional status filter |
+| `sxn_sessions_create` | Create session with auto-detection, optional template |
+| `sxn_sessions_get` | Get detailed session info |
+| `sxn_sessions_delete` | Delete session (with force option) |
+| `sxn_sessions_archive` | Archive a session |
+| `sxn_sessions_activate` | Activate an archived session |
+| `sxn_sessions_swap` | Switch session + return navigation info (hybrid cd approach) |
+
+#### Worktree Tools
+| Tool | Description |
+|------|-------------|
+| `sxn_worktrees_list` | List worktrees in session |
+| `sxn_worktrees_add` | Add worktree with auto rule application |
+| `sxn_worktrees_remove` | Remove worktree from session |
+
+#### Project Tools
+| Tool | Description |
+|------|-------------|
+| `sxn_projects_list` | List registered projects |
+| `sxn_projects_add` | Register new project (auto-detect type) |
+| `sxn_projects_get` | Get project details |
+
+#### Template Tools
+| Tool | Description |
+|------|-------------|
+| `sxn_templates_list` | List available templates |
+| `sxn_templates_apply` | Apply template to session |
+
+#### Rules Tools
+| Tool | Description |
+|------|-------------|
+| `sxn_rules_list` | List rules for project |
+| `sxn_rules_apply` | Apply rules to worktree |
+
+### MCP Resources (Read-only Context)
+
+| URI | Description |
+|-----|-------------|
+| `sxn://session/current` | Current session info + worktrees |
+| `sxn://sessions` | All sessions summary |
+| `sxn://projects` | Registered projects |
+
+### MCP Prompts (User-initiated Workflows)
+
+| Prompt | Description |
+|--------|-------------|
+| `new-session` | Guided session creation workflow |
+| `multi-repo-setup` | Set up multi-repo development environment |
+
+### Session Swap: Hybrid Directory Approach
+
+The `sxn_sessions_swap` tool implements the hybrid approach:
+
+```ruby
+# Returns structured response with navigation strategy
+{
+  session: { name: "feature-xyz", path: "/path/to/session" },
+  worktrees: [{ project: "api", path: "/path/to/session/api" }],
+  navigation: {
+    strategy: "bash_cd" | "new_instance",
+    bash_command: "cd /path/to/session",  # If within allowed dirs
+    shell_command: "claude --cwd /path/to/session",  # If new instance needed
+    reason: "Session is child of current directory" | "Session outside working directory"
+  }
+}
+```
+
+Claude Code will:
+1. Try `cd` via Bash tool if session is within allowed directories
+2. If outside, suggest user run `claude --cwd <path>` for new instance
+
+### Server Implementation
+
+```ruby
+# lib/sxn/mcp/server.rb
+module Sxn
+  module MCP
+    class Server
+      def initialize(workspace_path: nil)
+        @workspace_path = workspace_path || ENV['SXN_WORKSPACE'] || discover_workspace
+        @config_manager = Sxn::Core::ConfigManager.new(@workspace_path)
+        @server = build_mcp_server
+      end
+
+      def run_stdio
+        transport = ::MCP::Server::Transports::StdioTransport.new(@server)
+        transport.open
+      end
+
+      private
+
+      def build_mcp_server
+        ::MCP::Server.new(
+          name: "sxn",
+          version: Sxn::VERSION,
+          tools: registered_tools,
+          resources: registered_resources,
+          prompts: registered_prompts,
+          server_context: build_context
+        )
+      end
+
+      def build_context
+        {
+          config_manager: @config_manager,
+          session_manager: Sxn::Core::SessionManager.new(@config_manager),
+          project_manager: Sxn::Core::ProjectManager.new(@config_manager),
+          worktree_manager: Sxn::Core::WorktreeManager.new(@config_manager),
+          template_manager: Sxn::Core::TemplateManager.new(@config_manager),
+          rules_manager: Sxn::Core::RulesManager.new(@config_manager),
+          workspace_path: @workspace_path
+        }
+      end
+    end
+  end
+end
+```
+
+### Error Mapping
+
+Map sxn errors to MCP protocol errors:
+
+```ruby
+# lib/sxn/mcp/tools/base_tool.rb
+module Sxn::MCP::Tools
+  module ErrorMapping
+    SXN_TO_MCP = {
+      Sxn::SessionNotFoundError => ::MCP::Tool::ExecutionError,
+      Sxn::ProjectNotFoundError => ::MCP::Tool::ExecutionError,
+      Sxn::MCPValidationError => ::MCP::InvalidArgumentError,
+      Sxn::ValidationError => ::MCP::InvalidArgumentError
+    }
+
+    def self.wrap
+      yield
+    rescue Sxn::Error => e
+      mcp_error = SXN_TO_MCP[e.class] || ::MCP::Tool::ExecutionError
+      raise mcp_error, e.message
+    end
+  end
+end
+```
+
+### Installation & Configuration
+
+**CLI Installation:**
+```bash
+claude mcp add --transport stdio sxn -- sxn-mcp
+```
+
+**Project `.mcp.json`:**
+```json
+{
+  "mcpServers": {
+    "sxn": {
+      "command": "sxn-mcp",
+      "args": [],
+      "env": {
+        "SXN_WORKSPACE": "${PWD}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Phase 2: Claude Code Plugin
+
+### Plugin Structure
+
+```
+sxn-claude-plugin/
+├── .claude-plugin/
+│   └── plugin.json              # Plugin manifest
+├── commands/
+│   ├── start.md                 # /sxn:start - create session
+│   ├── use.md                   # /sxn:use - switch session
+│   ├── status.md                # /sxn:status - current session info
+│   └── worktree.md              # /sxn:worktree - add worktree
+├── agents/
+│   └── session-setup.md         # Subagent for guided setup
+├── skills/
+│   └── session-management.md    # Auto-activate for session tasks
+├── hooks/
+│   └── hooks.json               # Auto-detect sxn workspaces
+└── .mcp.json                    # MCP server config
+```
+
+### Plugin Manifest
+
+```json
+{
+  "name": "sxn",
+  "version": "0.1.0",
+  "description": "Session management for multi-repository development",
+  "author": "Ernest",
+  "repository": "https://github.com/ernest/sxn"
+}
+```
+
+### Slash Commands
+
+**`/sxn:start` (commands/start.md):**
+```markdown
+Create a new sxn development session.
+
+Arguments: $ARGUMENTS
+
+Use the sxn MCP server to:
+1. If no name provided, suggest a name based on context
+2. Create session with sxn_sessions_create
+3. Optionally apply template if specified
+4. Add worktrees for requested projects
+5. Navigate to session directory
+```
+
+**`/sxn:use` (commands/use.md):**
+```markdown
+Switch to an existing sxn session.
+
+Arguments: $ARGUMENTS
+
+1. Call sxn_sessions_swap with the session name
+2. Follow navigation strategy (bash cd or suggest new instance)
+3. Show session status after switch
+```
+
+### Hooks
+
+**`hooks/hooks.json`:**
+```json
+{
+  "hooks": [
+    {
+      "event": "on_session_start",
+      "command": "sxn-detect-workspace",
+      "description": "Auto-detect sxn workspace on session start"
+    }
+  ]
+}
+```
+
+### Distribution
+
+Plugin can be installed via:
+```bash
+claude plugin install /path/to/sxn-claude-plugin
+# or from npm/registry once published
+claude plugin install sxn
+```
+
+---
+
+## Implementation Order
+
+### Step 1: MCP Server Core
+1. Add `mcp` gem dependency to gemspec
+2. Create `lib/sxn/mcp.rb` module loader
+3. Implement `lib/sxn/mcp/server.rb`
+4. Create `bin/sxn-mcp` executable
+5. Implement `lib/sxn/mcp/tools/base_tool.rb` with error mapping
+
+### Step 2: Session Tools
+1. `sxn_sessions_list`
+2. `sxn_sessions_create`
+3. `sxn_sessions_get`
+4. `sxn_sessions_delete`
+5. `sxn_sessions_archive`
+6. `sxn_sessions_activate`
+7. `sxn_sessions_swap` (with hybrid cd approach)
+
+### Step 3: Worktree & Project Tools
+1. `sxn_worktrees_list`
+2. `sxn_worktrees_add`
+3. `sxn_worktrees_remove`
+4. `sxn_projects_list`
+5. `sxn_projects_add`
+6. `sxn_projects_get`
+
+### Step 4: Template & Rules Tools
+1. `sxn_templates_list`
+2. `sxn_templates_apply`
+3. `sxn_rules_list`
+4. `sxn_rules_apply`
+
+### Step 5: Resources & Prompts
+1. `sxn://session/current` resource
+2. `sxn://sessions` resource
+3. `sxn://projects` resource
+4. `new-session` prompt
+5. `multi-repo-setup` prompt
+
+### Step 6: Tests
+1. Unit tests for each tool
+2. Integration tests with mock MCP client
+3. Use existing test patterns from `spec/unit/`
+
+### Step 7: Claude Code Plugin
+1. Create plugin directory structure
+2. Write slash command definitions
+3. Implement hooks
+4. Create session-management skill
+5. Test plugin installation
+
+---
+
+## Critical Files to Modify
+
+| File | Changes |
+|------|---------|
+| `sxn.gemspec` | Add `mcp` gem dependency |
+| `lib/sxn.rb` | Add `require_relative "sxn/mcp"` |
+| `lib/sxn/errors.rb` | Already has MCPError classes (use them) |
+| `lib/sxn/core/session_manager.rb` | Reference for session operations |
+| `lib/sxn/core/worktree_manager.rb` | Reference for worktree operations |
+| `lib/sxn/core/project_manager.rb` | Reference for project operations |
+| `lib/sxn/core/template_manager.rb` | Reference for template operations |
+| `lib/sxn/core/rules_manager.rb` | Reference for rules operations |
+
+## New Files to Create
+
+| File | Purpose |
+|------|---------|
+| `lib/sxn/mcp.rb` | Module loader |
+| `lib/sxn/mcp/server.rb` | Main MCP server |
+| `lib/sxn/mcp/tools/*.rb` | Tool implementations |
+| `lib/sxn/mcp/resources/*.rb` | Resource implementations |
+| `lib/sxn/mcp/prompts/*.rb` | Prompt implementations |
+| `bin/sxn-mcp` | Executable |
+| `spec/unit/mcp/**/*_spec.rb` | Tests |
+
+---
+
+## Usage Examples
+
+### From Claude Code (after MCP server installed)
+
+```
+User: Create a new session for the user-auth feature
+
+Claude: I'll create a new session for you.
+[calls sxn_sessions_create with name: "user-auth"]
+
+Session "user-auth" created at /path/to/sxn-sessions/user-auth
+
+Would you like me to add worktrees for specific projects?
+```
+
+```
+User: Switch to my api-refactor session
+
+Claude: I'll switch to that session.
+[calls sxn_sessions_swap with name: "api-refactor"]
+
+Switched to session "api-refactor".
+[calls cd /path/to/sxn-sessions/api-refactor via Bash]
+
+Now working in the api-refactor session. This session has worktrees for:
+- api-service (branch: api-refactor)
+- shared-libs (branch: api-refactor)
+```
+
+### With Plugin Slash Commands
+
+```
+/sxn:start user-auth --template backend-services
+/sxn:use api-refactor
+/sxn:status
+/sxn:worktree add frontend-app
+```

data/lib/sxn/CLI.rb

@@ -225,6 +225,13 @@ module Sxn
       handle_error(e)
     end
 
+    desc "mcp SUBCOMMAND", "Manage MCP server for Claude Code"
+    def mcp(subcommand = nil, *args)
+      Commands::MCP.start([subcommand, *args].compact)
+    rescue Sxn::Error => e
+      handle_error(e)
+    end
+
     desc "status", "Show overall sxn status"
     def status
       show_status