feat: add auto-start, AFK mode, and comprehensive cross-platform setup

Major Features: - Auto-start: MCP server now automatically starts Telegram bridge on demand - AFK Mode: Toggle notifications on/off with /afk slash command - New telegram_toggle_afk MCP tool for controlling notification state - Dynamic enable/disable via new /toggle and /status API endpoints MCP Server Improvements: - Auto-detects if bridge is running and starts it automatically - Monitors bridge process health and logs output - Clean shutdown handling for both MCP server and bridge - Process spawning with proper environment variable passing Telegram Bridge Updates: - Runtime toggle for ENABLED state (was previously static) - POST /toggle endpoint to toggle notifications with Telegram confirmation - GET /status endpoint to check current notification state - Telegram messages sent when state changes (🟢/🔴 indicators) Documentation: - Cross-platform setup instructions (Mac, Linux, Windows) - Claude Code CLI setup guide with claude mcp add commands - Global vs project-specific MCP configuration explained - Troubleshooting section for fixing configuration scope issues - Complete AFK mode usage documentation - All new API endpoints documented Slash Commands: - Created /afk command in .claude/commands/afk.md - Available in both InnerVoice and ESO-MCP projects Files Changed: - src/mcp-server.ts: Auto-start logic and telegram_toggle_afk tool - src/index.ts: Dynamic ENABLED toggle and new API endpoints - README.md: Comprehensive setup and troubleshooting guide - mcp-config.json: Updated with correct absolute path - .claude/commands/afk.md: New slash command for AFK mode 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-23 14:15:46 -05:00
parent c4cfcf6eb8
commit c45fe4d509
5 changed files with 338 additions and 15 deletions
--- a/README.md
+++ b/README.md
@@ -101,23 +101,63 @@ pnpm daemon

 ### 5. Add MCP Server to Claude

-#### Option A: Auto-Generate Config (Easiest)
+> **✨ Auto-Start Feature:** The MCP server now automatically starts the Telegram bridge when needed - no need to run it separately!

+#### Option A: Claude Code CLI (Recommended)
+
+> **Note:** Using `claude mcp add` automatically adds the server **globally** (available in all projects). This is the recommended approach.
+
+**For Mac and Linux:**
 ```bash
-cd innervoice
-./scripts/get-mcp-config.sh
+# Navigate to the innervoice directory
+cd /path/to/innervoice
+
+# Add the MCP server globally (available in all projects)
+claude mcp add --transport stdio telegram \
+  --env TELEGRAM_BRIDGE_URL=http://localhost:3456 \
+  -- node "$(pwd)/dist/mcp-server.js"
+
+# Verify it was added globally
+claude mcp list
 ```

-Copy the output to your MCP config file.
+**For Windows (PowerShell):**
+```powershell
+# Navigate to the innervoice directory
+cd C:\path\to\innervoice

-#### Option B: Manual Setup
+# Add the MCP server globally
+claude mcp add --transport stdio telegram `
+  --env TELEGRAM_BRIDGE_URL=http://localhost:3456 `
+  -- node "$((Get-Location).Path)\dist\mcp-server.js"

-Add to your Claude Code MCP settings (`~/.config/claude-code/settings/mcp.json`):
+# Verify it was added
+claude mcp list
+```
+
+**For Windows (Command Prompt):**
+```cmd
+# Navigate to the innervoice directory
+cd C:\path\to\innervoice
+
+# Add the MCP server globally
+claude mcp add --transport stdio telegram --env TELEGRAM_BRIDGE_URL=http://localhost:3456 -- node "%CD%\dist\mcp-server.js"
+
+# Verify it was added
+claude mcp list
+```
+
+#### Option B: Manual Config File Setup
+
+Add to your Claude Code MCP settings:
+
+**Mac/Linux:** `~/.claude.json`
+**Windows:** `%USERPROFILE%\.claude.json`

 ```json
 {
  "mcpServers": {
-    "innervoice": {
+    "telegram": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/innervoice/dist/mcp-server.js"
@@ -130,17 +170,27 @@ Add to your Claude Code MCP settings (`~/.config/claude-code/settings/mcp.json`)
 }
 ```

-**Find your path:**
+**Find your absolute path:**
+
+**Mac/Linux:**
 ```bash
 cd innervoice && pwd
 # Use output: <result>/dist/mcp-server.js
 ```

-#### MCP Config Locations
+**Windows (PowerShell):**
+```powershell
+cd innervoice
+(Get-Location).Path
+# Use output: <result>\dist\mcp-server.js
+```

- **Global (all projects):** `~/.config/claude-code/settings/mcp.json`
- **Per-project:** `your-project/.claude/mcp.json`
- **VS Code:** `your-project/.vscode/mcp.json`
+**Windows (Command Prompt):**
+```cmd
+cd innervoice
+cd
+# Use output: <result>\dist\mcp-server.js
+```

 ### 6. Available Tools

@@ -150,6 +200,7 @@ Once configured, Claude can automatically use:
 - `telegram_get_messages` - Check for messages from you
 - `telegram_reply` - Reply to your messages
 - `telegram_check_health` - Check bridge status
+- `telegram_toggle_afk` - Toggle AFK mode (enable/disable notifications)

 **View detailed tool info:**
 ```bash
@@ -158,7 +209,60 @@ pnpm tools
 node scripts/list-tools.js
 ```

-### 7. Test It
+### 7. AFK Mode - Control Your Notifications
+
+Use the `/afk` slash command to toggle notifications on/off:
+
+```bash
+# In Claude Code, just type:
+/afk
+```
+
+This is perfect for:
+- **Enabling** when you step away from your computer (get notified via Telegram)
+- **Disabling** when you're actively working (no interruptions)
+
+The toggle state is preserved while the bridge is running, and you'll get a Telegram message confirming each change.
+
+### 8. Verify Global Setup
+
+After adding the MCP server, verify it's available globally:
+
+```bash
+# Check that telegram appears in the list
+claude mcp list
+
+# Should show:
+# ✓ telegram: Connected
+```
+
+**Troubleshooting:** If `telegram` only appears in one project but not others, it was added to a project-specific config instead of globally. To fix:
+
+1. Open `~/.claude.json` in your editor
+2. Find the `telegram` server config under `projects` → `your-project-path` → `mcpServers`
+3. **Move it** to the root-level `mcpServers` section (same level as other global servers)
+4. Remove the `telegram` entry from the project-specific section
+
+**Example structure:**
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/innervoice/dist/mcp-server.js"],
+      "env": {"TELEGRAM_BRIDGE_URL": "http://localhost:3456"}
+    }
+  },
+  "projects": {
+    "/your/project/path": {
+      "mcpServers": {}  // Should be empty or not contain telegram
+    }
+  }
+}
+```
+
+### 9. Test It

 Restart Claude Code, then tell Claude:

@@ -217,6 +321,20 @@ Check if the Telegram bridge is running and healthy.
 > "Let me verify the Telegram bridge is working."
 > *Claude uses: `telegram_check_health({})`*

+### `telegram_toggle_afk`
+Toggle AFK (Away From Keyboard) mode - enables or disables Telegram notifications.
+
+**No parameters required**
+
+**Example Claude Usage:**
+> "Toggle AFK mode"
+> *Claude uses: `telegram_toggle_afk({})`*
+
+**When to use:**
+- Enable when stepping away from your computer (get notifications)
+- Disable when actively working (avoid interruptions)
+- State is preserved while the bridge is running
+
 ## Git Setup (For Sharing)

 If you want to push this to your own Git repository:
@@ -443,6 +561,30 @@ Check service health
 }
 ```

+### POST /toggle
+Toggle notifications on/off (AFK mode)
+
+**Response:**
+```json
+{
+  "success": true,
+  "enabled": true,
+  "previousState": false,
+  "message": "🟢 InnerVoice notifications ENABLED - You will receive messages"
+}
+```
+
+### GET /status
+Get current notification state
+
+**Response:**
+```json
+{
+  "enabled": true,
+  "message": "Notifications are ON"
+}
+```
+
 ## Integration with ESO-MCP

 Add this helper to your ESO-MCP project: