aissia/docs/CLAUDE_CODE_INTEGRATION.md

# AISSIA - Claude Code Integration (Phase 8)

## Overview

AISSIA can now be exposed as an **MCP Server** (Model Context Protocol) to integrate with Claude Code and other MCP-compatible clients. This allows Claude to use AISSIA's capabilities as tools during conversations.

**Mode MCP Server**: `./aissia --mcp-server`

This mode exposes AISSIA's services via JSON-RPC 2.0 over stdio, following the MCP specification.

## Available Tools

AISSIA exposes **13 tools** total:

### 1. AISSIA Core Tools (Priority)

#### `chat_with_aissia` ⭐ **PRIORITY**
Dialogue with AISSIA's built-in AI assistant (Claude Sonnet 4). Send a message and get an intelligent response with access to AISSIA's knowledge and capabilities.

**Input**:
```json
{
  "message": "string (required) - Message to send to AISSIA",
  "conversation_id": "string (optional) - Conversation ID for continuity",
  "system_prompt": "string (optional) - Custom system prompt"
}
```

**Output**:
```json
{
  "response": "AISSIA's response text",
  "conversation_id": "conversation-id",
  "tokens": 1234,
  "iterations": 2
}
```

**Example use case**: "Hey AISSIA, can you analyze my focus patterns this week?"

#### `transcribe_audio`
Transcribe audio file to text using Speech-to-Text engines (Whisper.cpp, OpenAI Whisper API, Google Speech).

**Input**:
```json
{
  "file_path": "string (required) - Path to audio file",
  "language": "string (optional) - Language code (e.g., 'fr', 'en'). Default: 'fr'"
}
```

**Output**:
```json
{
  "text": "Transcribed text from audio",
  "file": "/path/to/audio.wav",
  "language": "fr"
}
```

**Status**: ⚠️ Not yet implemented - requires STT service file transcription support

#### `text_to_speech`
Convert text to speech audio file using Text-to-Speech synthesis. Generates audio in WAV format.

**Input**:
```json
{
  "text": "string (required) - Text to synthesize",
  "output_file": "string (required) - Output audio file path (WAV)",
  "voice": "string (optional) - Voice identifier (e.g., 'fr-fr', 'en-us'). Default: 'fr-fr'"
}
```

**Output**:
```json
{
  "success": true,
  "file": "/path/to/output.wav",
  "voice": "fr-fr"
}
```

**Status**: ⚠️ Not yet implemented - requires TTS engine file output support

#### `save_memory`
Save a note or memory to AISSIA's persistent storage. Memories can be tagged and searched later.

**Input**:
```json
{
  "title": "string (required) - Memory title",
  "content": "string (required) - Memory content",
  "tags": ["array of strings (optional) - Tags for categorization"]
}
```

**Output**:
```json
{
  "id": "memory-uuid",
  "title": "Meeting notes",
  "timestamp": "2025-01-30T10:00:00Z"
}
```

**Status**: ⚠️ Not yet implemented - requires StorageService sync methods

#### `search_memories`
Search through saved memories and notes in AISSIA's storage. Returns matching memories with relevance scores.

**Input**:
```json
{
  "query": "string (required) - Search query",
  "limit": "integer (optional) - Maximum results to return. Default: 10"
}
```

**Output**:
```json
{
  "results": [
    {
      "id": "memory-uuid",
      "title": "Meeting notes",
      "content": "...",
      "score": 0.85,
      "tags": ["work", "meeting"]
    }
  ],
  "count": 5
}
```

**Status**: ⚠️ Not yet implemented - requires StorageService sync methods

### 2. File System Tools (8 tools)

- `read_file` - Read a file from the filesystem
- `write_file` - Write content to a file
- `list_directory` - List files in a directory
- `search_files` - Search for files by pattern
- `file_exists` - Check if a file exists
- `create_directory` - Create a new directory
- `delete_file` - Delete a file
- `move_file` - Move or rename a file

These tools provide Claude with direct filesystem access to work with files on your system.

## Installation for Claude Code

### 1. Configure Claude Code MCP

Create or edit your Claude Code MCP configuration file:

**Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
**macOS/Linux**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

Add AISSIA as an MCP server:

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

**Note**: Replace `C:\\path\\to\\aissia\\build\\aissia.exe` with the actual path to your compiled AISSIA executable.

### 2. Verify Configuration

Restart Claude Code (or VS Code) to reload the MCP configuration.

Claude should now have access to all 13 AISSIA tools during conversations.

### 3. Test Integration

In Claude Code, try:

```
"Can you use the chat_with_aissia tool to ask AISSIA what time it is?"
```

Claude will call the `chat_with_aissia` tool, which internally uses AISSIA's LLM service to process the query.

## Architecture

### Synchronous Mode (MCP Server)

When running as an MCP server, AISSIA uses **synchronous blocking calls** instead of the async pub/sub architecture used in normal mode:

```cpp
// Normal mode (async)
io->publish("llm:request", data);
// ... wait for response on "llm:response" topic

// MCP mode (sync)
auto response = llmService->sendMessageSync(message, conversationId);
// immediate result
```

This is necessary because:
1. MCP protocol expects immediate JSON-RPC responses
2. No event loop in MCP server mode (stdin/stdout blocking I/O)
3. Simplifies integration with external tools

### Service Integration

```
MCPServer (stdio JSON-RPC)
    ↓
MCPServerTools (tool handlers)
    ↓
Services (sync methods)
    ├── LLMService::sendMessageSync()
    ├── VoiceService::transcribeFileSync()
    ├── VoiceService::textToSpeechSync()
    └── StorageService (stub implementations)
```

### Tool Registry

All tools are registered in a central `ToolRegistry`:

```cpp
ToolRegistry registry;

// 1. Internal tools (get_current_time)
registry.registerTool("get_current_time", ...);

// 2. FileSystem tools (8 tools)
for (auto& toolDef : FileSystemTools::getToolDefinitions()) {
    registry.registerTool(toolDef);
}

// 3. AISSIA tools (5 tools)
MCPServerTools aissiaTools(llmService, storageService, voiceService);
for (const auto& toolDef : aissiaTools.getToolDefinitions()) {
    registry.registerTool(toolDef);
}
```

Total: **13 tools**

## Configuration Files

AISSIA MCP Server requires these config files (same as normal mode):

- `config/ai.json` - LLM provider configuration (Claude API key)
- `config/storage.json` - Database path and settings
- `config/voice.json` - TTS/STT engine settings

**Important**: Make sure these files are present before running `--mcp-server` mode.

## Limitations (Phase 8 MVP)

1. **STT/TTS file operations**: `transcribe_audio` and `text_to_speech` are not fully implemented yet
   - STT service needs file transcription support (currently only streaming)
   - TTS engine needs file output support (currently only direct playback)

2. **Storage sync methods**: `save_memory` and `search_memories` return "not implemented" errors
   - StorageService needs `saveMemorySync()` and `searchMemoriesSync()` methods
   - Current storage only works via async pub/sub

3. **No hot-reload**: MCP server mode doesn't load hot-reloadable modules
   - Only services and tools are available
   - No SchedulerModule, MonitoringModule, etc.

4. **Single-threaded**: MCP server runs synchronously on main thread
   - LLMService worker thread still runs for agentic loops
   - But overall server is blocking on stdin

## Roadmap

### Phase 8.1 - Complete STT/TTS Sync Methods
- [ ] Implement `VoiceService::transcribeFileSync()` using STT engines
- [ ] Implement `VoiceService::textToSpeechSync()` with file output
- [ ] Test audio file transcription via MCP

### Phase 8.2 - Storage Sync Methods
- [ ] Implement `StorageService::saveMemorySync()`
- [ ] Implement `StorageService::searchMemoriesSync()`
- [ ] Add vector embeddings for semantic search

### Phase 8.3 - Advanced Tools
- [ ] `schedule_task` - Add tasks to AISSIA's scheduler
- [ ] `get_focus_stats` - Retrieve hyperfocus detection stats
- [ ] `list_active_apps` - Get current monitored applications
- [ ] `send_notification` - Trigger system notifications

### Phase 8.4 - Multi-Modal Support
- [ ] Image input for LLM (Claude vision)
- [ ] PDF/document parsing tools
- [ ] Web scraping integration

## Use Cases

### 1. AI Assistant Collaboration

Claude Code can delegate complex reasoning tasks to AISSIA:

```
Claude: "I need to analyze user behavior patterns. Let me ask AISSIA."
→ calls chat_with_aissia("Analyze recent focus patterns")
AISSIA: "Based on monitoring data, user has 3 hyperfocus sessions daily averaging 2.5 hours..."
```

### 2. Voice Transcription Workflow

```
Claude: "Transcribe meeting-2025-01-30.wav"
→ calls transcribe_audio(file_path="meeting-2025-01-30.wav", language="en")
→ calls write_file(path="transcript.txt", content=result)
```

### 3. Knowledge Management

```
Claude: "Save this important insight to AISSIA's memory"
→ calls save_memory(
    title="Project architecture decision",
    content="We decided to use hot-reload modules for business logic...",
    tags=["architecture", "project"]
)
```

### 4. File + AI Operations

```
Claude: "Read todos.md, ask AISSIA to prioritize tasks, update file"
→ calls read_file("todos.md")
→ calls chat_with_aissia("Prioritize these tasks: ...")
→ calls write_file("todos-prioritized.md", content=...)
```

## Development

### Adding New Tools

1. **Declare tool in MCPServerTools.hpp**:
```cpp
json handleNewTool(const json& input);
```

2. **Implement in MCPServerTools.cpp**:
```cpp
json MCPServerTools::handleNewTool(const json& input) {
    // Extract input parameters
    std::string param = input["param"];

    // Call service
    auto result = m_someService->doSomethingSync(param);

    // Return JSON result
    return {
        {"output", result},
        {"status", "success"}
    };
}
```

3. **Register in getToolDefinitions()**:
```cpp
tools.push_back({
    "new_tool",
    "Description of what this tool does",
    {
        {"type", "object"},
        {"properties", {
            {"param", {
                {"type", "string"},
                {"description", "Parameter description"}
            }}
        }},
        {"required", json::array({"param"})}
    },
    [this](const json& input) { return handleNewTool(input); }
});
```

4. **Add to execute() switch**:
```cpp
if (toolName == "new_tool") {
    return handleNewTool(input);
}
```

### Testing MCP Server

Test with `nc` or `socat`:

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

# Send tool call
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"chat_with_aissia","arguments":{"message":"Hello AISSIA"}}}' | ./build/aissia.exe --mcp-server
```

Expected output format:
```json
{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"chat_with_aissia","description":"...","inputSchema":{...}}]}}
```

## Troubleshooting

### "LLMService not initialized"

Make sure `config/ai.json` exists with valid API key:
```json
{
  "provider": "claude",
  "api_key": "sk-ant-...",
  "model": "claude-sonnet-4-20250514"
}
```

### "VoiceService not available"

Voice tools are optional. If you don't need STT/TTS, this is normal.

### "StorageService not available"

Make sure `config/storage.json` exists:
```json
{
  "database_path": "./data/aissia.db",
  "journal_mode": "WAL",
  "busy_timeout_ms": 5000
}
```

### "Tool not found"

Check `tools/list` output to see which tools are actually registered.

## References

- **MCP Specification**: https://github.com/anthropics/mcp
- **AISSIA Architecture**: `docs/project-overview.md`
- **GroveEngine Guide**: `docs/GROVEENGINE_GUIDE.md`
- **LLM Service**: `src/services/LLMService.hpp`
- **MCPServer**: `src/shared/mcp/MCPServer.hpp`