306 lines
7.6 KiB
Markdown
306 lines
7.6 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"aissia": {
|
|
"command": "path/to/aissia.exe",
|
|
"args": ["--mcp-server"],
|
|
"disabled": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### With Auto-Approval
|
|
|
|
To skip confirmation prompts for specific tools:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```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
|
|
```json
|
|
{
|
|
"database_path": "./data/aissia.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/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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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
|