966 Setup Guide A7f1576b

# Zero-Token Skills Listing - Setup Guide

## Current Status

✅ The `/skills` command is working using the shell script fallback
⚠️ Using ~1,000 tokens per call
🎯 Goal: Reduce to **0 tokens** using MCP

## What's Happening Now

When you run `/skills`, you see:
```
⏺ I don't have access to the list_skills MCP tool, so I'll use the shell script fallback:
⏺ Bash(~/bin/list-skills.sh --names-only)
```

This works, but uses tokens. Let's fix that!

## Enable Zero-Token Operation (5 Minutes)

### Step 1: Install MCP SDK

```bash
pip install mcp
```

**Verify installation:**
```bash
python3 -c "import mcp; print('✅ MCP SDK installed!')"
```

### Step 2: Run Automated Setup

```bash
cd $HOME/Documents/ws/claude-skills/mcp-servers/skills-lister
./setup.sh
```

The setup script will:
- ✅ Check Python version (needs 3.10+)
- ✅ Verify MCP SDK is installed
- ✅ Make scripts executable
- ✅ Show you the configuration to add
- ✅ Optionally create `.claude/mcp.json` for you

### Step 3: Configure Claude Code

The setup script will generate the configuration. You need to add it to one of:

**Option A: Project-specific** (recommended for testing)
```
$HOME/Documents/ws/claude-skills/.claude/mcp.json
```

**Option B: Global** (all projects)
```
~/.claude/mcp.json
```

The configuration looks like:
```json
{
  "mcpServers": {
    "skills-lister": {
      "command": "python3",
      "args": [
        "$HOME/Documents/ws/claude-skills/mcp-servers/skills-lister/server.py"
      ]
    }
  }
}
```

### Step 4: Restart Claude Code

Exit your current Claude Code session and start a new one. The MCP server will be loaded automatically.

### Step 5: Test It!

Run `/skills` again. You should now see:

```
✅ Using MCP list_skills tool
⚡ 0 tokens used
⚡ <1 second response
```

Instead of:
```
⚠️ I don't have access to the list_skills MCP tool, so I'll use the shell script fallback
📊 ~1,000 tokens used
```

## Verification

To verify the MCP server is configured:

1. Start a new Claude Code session
2. Check the startup logs for MCP server initialization
3. Run `/skills` - should be instant with 0 tokens
4. You should NOT see "I don't have access to the list_skills MCP tool"

## Before and After

### Before (Current State)
```
User: /skills
Claude: I don't have access to the list_skills MCP tool,
        so I'll use the shell script fallback
        [Runs: ~/bin/list-skills.sh --names-only]
        [Uses: ~1,000 tokens]
        [Time: ~2 seconds]
```

### After (With MCP)
```
User: /skills
Claude: [Silently calls list_skills MCP tool]
        [Uses: 0 tokens]
        [Time: <1 second]
        Lists all 16 skills instantly!
```

## Troubleshooting

### "Module not found: mcp"
```bash
pip install mcp
```

### "Script not found"
```bash
ls -l ~/bin/list-skills.sh
# If missing:
cp $HOME/Documents/ws/claude-skills/scripts/list-skills.sh ~/bin/
chmod +x ~/bin/list-skills.sh
```

### "MCP server not loading"

Check your configuration file:
```bash
# For project-specific
cat $HOME/Documents/ws/claude-skills/.claude/mcp.json

# For global
cat ~/.claude/mcp.json
```

Verify the path to `server.py` is absolute (no `~`, starts with `/`).

### Still seeing "shell script fallback"

1. Verify MCP configuration exists
2. Restart Claude Code completely (exit and relaunch)
3. Check Claude Code logs for MCP initialization errors
4. Try running the server manually to test:
   ```bash
   cd $HOME/Documents/ws/claude-skills/mcp-servers/skills-lister
   python3 server.py
   # Should wait for input (press Ctrl+D to exit)
   ```

## Benefits You'll Get

Once configured:

| Metric | Before | After | Savings |
|--------|--------|-------|---------|
| **Tokens per call** | ~1,000 | 0 | 100% |
| **Response time** | ~2 sec | <1 sec | 50% |
| **Cost per call** | ~$0.003 | $0 | Free! |

If you run `/skills` 10 times per day:
- **Token savings**: 10,000 tokens/day
- **Cost savings**: ~$0.03/day = ~$11/year
- **Time savings**: 10+ seconds/day

## Quick Command Reference

```bash
# Install MCP SDK
pip install mcp

# Run setup
cd $HOME/Documents/ws/claude-skills/mcp-servers/skills-lister
./setup.sh

# Test shell script
~/bin/list-skills.sh --names-only

# Test MCP server manually
python3 $HOME/Documents/ws/claude-skills/mcp-servers/skills-lister/server.py

# Check configuration
cat $HOME/Documents/ws/claude-skills/.claude/mcp.json
```

## Next Steps After Setup

Once working, you can:
1. ✅ Use `/skills` with 0 tokens
2. 🚀 Create more MCP servers for other operations
3. 📊 Monitor token savings over time
4. 🎉 Enjoy instant, free skill listings!

## Need More Help?

See detailed documentation:
- [QUICK-START.md](QUICK-START.md) - Quick setup
- [INSTALL.md](INSTALL.md) - Detailed installation
- [README.md](skills-lister/README.md) - Full documentation
- [ARCHITECTURE.md](skills-lister/ARCHITECTURE.md) - How it works

## Summary

The MCP server is ready to use! Just need to:
1. `pip install mcp`
2. Run `./setup.sh`
3. Restart Claude Code
4. Enjoy zero-token skill listings! 🎉