aissia/config/README_MCP.md

AISSIA MCP Configuration for Claude Code

This directory contains an example MCP (Model Context Protocol) configuration for integrating AISSIA 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 AISSIA executable:

{
  "mcpServers": {
    "aissia": {
      "command": "C:\\path\\to\\your\\aissia\\build\\aissia.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 AISSIA tools are available:

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

Available Tools

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

AISSIA Core (5 tools)

1. chat_with_aissia ⭐ - Dialogue with AISSIA'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 AISSIA'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

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

With Auto-Approval

To skip confirmation prompts for specific tools:

{
  "mcpServers": {
    "aissia": {
      "command": "path/to/aissia.exe",
      "args": ["--mcp-server"],
      "disabled": false,
      "alwaysAllow": ["chat_with_aissia", "read_file", "write_file"]
    }
  }
}

Disable Server

To temporarily disable AISSIA without removing the configuration:

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

Prerequisites

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

config/ai.json

{
  "provider": "claude",
  "api_key": "sk-ant-api03-...",
  "model": "claude-sonnet-4-20250514",
  "max_iterations": 10,
  "system_prompt": "Tu es AISSIA, un assistant personnel intelligent..."
}

config/storage.json

{
  "database_path": "./data/aissia.db",
  "journal_mode": "WAL",
  "busy_timeout_ms": 5000
}

config/voice.json (optional)

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

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

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

Troubleshooting

"Server not found" or "Connection failed"

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

"LLMService not initialized"

AISSIA 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 AISSIA for Help

You: Use chat_with_aissia to ask "What are my top productivity patterns?"
Claude: [calls chat_with_aissia tool]
AISSIA: 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 AISSIA to prioritize the tasks
Claude: [calls read_file("TODO.md")]
Claude: [calls chat_with_aissia with task list]
AISSIA: 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 AISSIA:

{
  "mcpServers": {
    "aissia": {
      "command": "C:\\path\\to\\aissia\\build\\aissia.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 AISSIA:

{
  "mcpServers": {
    "aissia": {
      "command": "C:\\path\\to\\aissia\\build\\aissia.exe",
      "args": ["--mcp-server"],
      "disabled": false,
      "env": {
        "AISSIA_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: AISSIA writes to stderr in MCP mode
3. Test manually: ./build/aissia.exe --mcp-server and send JSON-RPC requests