aissia/config/README_MCP.md

# Celuna MCP Configuration for Claude Code

This directory contains an example MCP (Model Context Protocol) configuration for integrating Celuna with Claude Code.

## Quick Setup

### 1. Locate Claude Code MCP Settings

The MCP configuration file location depends on your operating system:

**Windows**:
```
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
```

Full path example:
```
C:\Users\YourUsername\AppData\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
```

**macOS**:
```
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
```

**Linux**:
```
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
```

### 2. Copy Configuration

Copy the contents of `claude_code_mcp_config.json` to the Claude Code MCP settings file.

**Important**: Update the `command` path to point to your actual Celuna executable:

```json
{
  "mcpServers": {
    "celuna": {
      "command": "C:\\path\\to\\your\\celuna\\build\\celuna.exe",
      "args": ["--mcp-server"],
      "disabled": false
    }
  }
}
```

### 3. Restart Claude Code

Restart VS Code (or reload window: `Ctrl+Shift+P` → "Developer: Reload Window") to apply the changes.

### 4. Verify Integration

Open Claude Code and check that Celuna tools are available:

```
You: Can you list the available MCP servers?
Claude: I have access to the following MCP servers:
- celuna: 13 tools available
```

## Available Tools

Once configured, Claude will have access to these 13 Celuna tools:

### Celuna Core (5 tools)
1. **chat_with_celuna** ⭐ - Dialogue with Celuna's AI assistant (Claude Sonnet 4)
2. **transcribe_audio** - Transcribe audio files to text
3. **text_to_speech** - Convert text to speech audio files
4. **save_memory** - Save notes to Celuna's persistent storage
5. **search_memories** - Search through saved memories

### File System (8 tools)
6. **read_file** - Read file contents
7. **write_file** - Write content to files
8. **list_directory** - List files in a directory
9. **search_files** - Search for files by pattern
10. **file_exists** - Check if a file exists
11. **create_directory** - Create directories
12. **delete_file** - Delete files
13. **move_file** - Move or rename files

## Configuration Options

### Basic Configuration

```json
{
  "mcpServers": {
    "celuna": {
      "command": "path/to/celuna.exe",
      "args": ["--mcp-server"],
      "disabled": false
    }
  }
}
```

### With Auto-Approval

To skip confirmation prompts for specific tools:

```json
{
  "mcpServers": {
    "celuna": {
      "command": "path/to/celuna.exe",
      "args": ["--mcp-server"],
      "disabled": false,
      "alwaysAllow": ["chat_with_celuna", "read_file", "write_file"]
    }
  }
}
```

### Disable Server

To temporarily disable Celuna without removing the configuration:

```json
{
  "mcpServers": {
    "celuna": {
      "command": "path/to/celuna.exe",
      "args": ["--mcp-server"],
      "disabled": true  // <-- Set to true
    }
  }
}
```

## Prerequisites

Before running Celuna in MCP server mode, ensure these config files exist:

### config/ai.json
```json
{
  "provider": "claude",
  "api_key": "sk-ant-api03-...",
  "model": "claude-sonnet-4-20250514",
  "max_iterations": 10,
  "system_prompt": "Tu es Celuna, un assistant personnel intelligent..."
}
```

### config/storage.json
```json
{
  "database_path": "./data/celuna.db",
  "journal_mode": "WAL",
  "busy_timeout_ms": 5000
}
```

### config/voice.json (optional)
```json
{
  "tts": {
    "enabled": true,
    "rate": 0,
    "volume": 80
  },
  "stt": {
    "active_mode": {
      "enabled": false
    }
  }
}
```

## Testing MCP Server

You can test the MCP server independently before integrating with Claude Code:

```bash
# Test tools/list
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./build/celuna.exe --mcp-server

# Test chat_with_celuna tool
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"chat_with_celuna","arguments":{"message":"What time is it?"}}}' | ./build/celuna.exe --mcp-server
```

## Troubleshooting

### "Server not found" or "Connection failed"

1. Verify the `command` path is correct and points to `celuna.exe`
2. Make sure Celuna compiles successfully: `cmake --build build`
3. Test running `./build/celuna.exe --mcp-server` manually

### "LLMService not initialized"

Celuna requires `config/ai.json` with a valid Claude API key. Check:
1. File exists: `config/ai.json`
2. API key is valid: `"api_key": "sk-ant-api03-..."`
3. Provider is set: `"provider": "claude"`

### "Tool execution failed"

Some tools have limited functionality in Phase 8 MVP:
- `transcribe_audio` - Not fully implemented yet (STT file support needed)
- `text_to_speech` - Not fully implemented yet (TTS file output needed)
- `save_memory` - Not fully implemented yet (Storage sync methods needed)
- `search_memories` - Not fully implemented yet (Storage sync methods needed)

These will be completed in Phase 8.1 and 8.2.

### Server starts but tools don't appear

1. Check Claude Code logs: `Ctrl+Shift+P` → "Developer: Open Extension Logs"
2. Look for MCP server initialization errors
3. Verify JSON syntax in the MCP configuration file

## Example Use Cases

### 1. Ask Celuna for Help

```
You: Use chat_with_celuna to ask "What are my top productivity patterns?"
Claude: [calls chat_with_celuna tool]
Celuna: Based on your activity data, your most productive hours are 9-11 AM...
```

### 2. File Operations + AI

```
You: Read my TODO.md file and ask Celuna to prioritize the tasks
Claude: [calls read_file("TODO.md")]
Claude: [calls chat_with_celuna with task list]
Celuna: Here's a prioritized version based on urgency and dependencies...
```

### 3. Voice Transcription (future)

```
You: Transcribe meeting-notes.wav to text
Claude: [calls transcribe_audio("meeting-notes.wav")]
Result: "Welcome to the team meeting. Today we're discussing..."
```

## Advanced Configuration

### Multiple MCP Servers

You can configure multiple MCP servers alongside Celuna:

```json
{
  "mcpServers": {
    "celuna": {
      "command": "C:\\path\\to\\celuna\\build\\celuna.exe",
      "args": ["--mcp-server"],
      "disabled": false
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users"],
      "disabled": false
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "disabled": false,
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}
```

### Environment Variables

Pass environment variables to Celuna:

```json
{
  "mcpServers": {
    "celuna": {
      "command": "C:\\path\\to\\celuna\\build\\celuna.exe",
      "args": ["--mcp-server"],
      "disabled": false,
      "env": {
        "Celuna_LOG_LEVEL": "debug",
        "CLAUDE_API_KEY": "sk-ant-api03-..."
      }
    }
  }
}
```

## References

- **Full Documentation**: `docs/CLAUDE_CODE_INTEGRATION.md`
- **MCP Specification**: https://github.com/anthropics/mcp
- **Claude Code Extension**: https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev

## Support

For issues or questions:
1. Check the full documentation: `docs/CLAUDE_CODE_INTEGRATION.md`
2. Review logs: Celuna writes to stderr in MCP mode
3. Test manually: `./build/celuna.exe --mcp-server` and send JSON-RPC requests