aissia/docs/CLAUDE_CODE_INTEGRATION.md

CELUNA - Claude Code Integration (Phase 8)

Overview

CELUNA 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 CELUNA's capabilities as tools during conversations.

Mode MCP Server: ./celuna --mcp-server

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

Available Tools

CELUNA exposes 13 tools total:

1. CELUNA Core Tools (Priority)

chat_with_celuna ⭐ PRIORITY

Dialogue with CELUNA's built-in AI assistant (Claude Sonnet 4). Send a message and get an intelligent response with access to CELUNA's knowledge and capabilities.

Input:

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

Output:

{
  "response": "CELUNA's response text",
  "conversation_id": "conversation-id",
  "tokens": 1234,
  "iterations": 2
}

Example use case: "Hey CELUNA, 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:

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

Output:

{
  "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:

{
  "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:

{
  "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 CELUNA's persistent storage. Memories can be tagged and searched later.

Input:

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

Output:

{
  "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 CELUNA's storage. Returns matching memories with relevance scores.

Input:

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

Output:

{
  "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 CELUNA as an MCP server:

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

Note: Replace C:\\path\\to\\celuna\\build\\celuna.exe with the actual path to your compiled CELUNA executable.

2. Verify Configuration

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

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

3. Test Integration

In Claude Code, try:

"Can you use the chat_with_celuna tool to ask CELUNA what time it is?"

Claude will call the chat_with_celuna tool, which internally uses CELUNA's LLM service to process the query.

Architecture

Synchronous Mode (MCP Server)

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

// 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:

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. CELUNA tools (5 tools)
MCPServerTools celunaTools(llmService, storageService, voiceService);
for (const auto& toolDef : celunaTools.getToolDefinitions()) {
    registry.registerTool(toolDef);
}

Total: 13 tools

Configuration Files

CELUNA 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 CELUNA'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 CELUNA:

Claude: "I need to analyze user behavior patterns. Let me ask CELUNA."
→ calls chat_with_celuna("Analyze recent focus patterns")
CELUNA: "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 CELUNA'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 CELUNA to prioritize tasks, update file"
→ calls read_file("todos.md")
→ calls chat_with_celuna("Prioritize these tasks: ...")
→ calls write_file("todos-prioritized.md", content=...)

Development

Adding New Tools

1. Declare tool in MCPServerTools.hpp:

json handleNewTool(const json& input);

2. Implement in MCPServerTools.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():

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:

if (toolName == "new_tool") {
    return handleNewTool(input);
}

Testing MCP Server

Test with nc or socat:

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

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

Expected output format:

{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"chat_with_celuna","description":"...","inputSchema":{...}}]}}

Troubleshooting

"LLMService not initialized"

Make sure config/ai.json exists with valid API key:

{
  "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:

{
  "database_path": "./data/celuna.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
• CELUNA Architecture: docs/project-overview.md
• GroveEngine Guide: docs/GROVEENGINE_GUIDE.md
• LLM Service: src/services/LLMService.hpp
• MCPServer: src/shared/mcp/MCPServer.hpp