e617114310
- Move test files to tests/ - Archive session notes to docs/archive/ - Remove temp/diagnostic files - Clean src/ to only contain production code
353 lines
7.7 KiB
Markdown
353 lines
7.7 KiB
Markdown
# AI Stack Deployer - Claude Code MCP Configuration Guide
|
|
|
|
## Overview
|
|
|
|
This guide explains how to configure the AI Stack Deployer MCP server to work with **Claude Code** (not OpenCode). The two systems use different configuration formats.
|
|
|
|
---
|
|
|
|
## Key Differences: OpenCode vs Claude Code
|
|
|
|
### OpenCode Configuration
|
|
```json
|
|
{
|
|
"mcp": {
|
|
"graphiti-memory": {
|
|
"type": "remote",
|
|
"url": "http://10.100.0.17:8080/mcp/",
|
|
"enabled": true,
|
|
"oauth": false,
|
|
"timeout": 30000,
|
|
"headers": {
|
|
"X-API-Key": "0c1ab2355207927cf0ca255cfb9dfe1ed15d68eacb0d6c9f5cb9f08494c3a315"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Claude Code Configuration
|
|
```json
|
|
{
|
|
"graphiti-memory": {
|
|
"type": "sse",
|
|
"url": "http://10.100.0.17:8080/mcp/",
|
|
"headers": {
|
|
"X-API-Key": "${GRAPHITI_API_KEY}"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Key differences:**
|
|
- ✅ OpenCode: Nested under `"mcp"` key
|
|
- ✅ Claude Code: Direct server definitions (no `"mcp"` wrapper)
|
|
- ✅ OpenCode: Uses `"type": "remote"` with `enabled`, `oauth`, `timeout` fields
|
|
- ✅ Claude Code: Uses `"type": "sse"` (for HTTP) or stdio config (for local)
|
|
- ✅ OpenCode: API keys in plaintext
|
|
- ✅ Claude Code: API keys via environment variables (`${VAR_NAME}`)
|
|
|
|
---
|
|
|
|
## MCP Server Types
|
|
|
|
### 1. **stdio-based** (What we have)
|
|
- Communication via standard input/output
|
|
- Server runs as a subprocess
|
|
- Used for local MCP servers
|
|
- No HTTP/network involved
|
|
|
|
### 2. **SSE-based** (What graphiti-memory uses)
|
|
- Communication via HTTP Server-Sent Events
|
|
- Server runs remotely
|
|
- Requires URL and optional headers
|
|
|
|
---
|
|
|
|
## Current Configuration Analysis
|
|
|
|
### Project's `.mcp.json` (CORRECT for stdio)
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ai-stack-deployer": {
|
|
"command": "bun",
|
|
"args": ["run", "src/mcp-server.ts"],
|
|
"env": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
This configuration is **already correct for Claude Code!** 🎉
|
|
|
|
### Why it's correct:
|
|
1. ✅ Uses `"mcpServers"` wrapper (Claude Code standard)
|
|
2. ✅ Defines `command` and `args` (stdio transport)
|
|
3. ✅ Empty `env` object (will inherit from shell)
|
|
4. ✅ Server uses `StdioServerTransport` (matches config)
|
|
|
|
---
|
|
|
|
## Setup Instructions
|
|
|
|
### Option 1: Project-Level MCP Server (Recommended)
|
|
|
|
**This is already configured!** The `.mcp.json` in your project root enables the MCP server for **this project only**.
|
|
|
|
**How to use:**
|
|
1. Navigate to this project directory:
|
|
```bash
|
|
cd ~/locale-projects/ai-stack-deployer
|
|
```
|
|
|
|
2. Start Claude Code:
|
|
```bash
|
|
claude
|
|
```
|
|
|
|
3. Claude Code will detect `.mcp.json` and prompt you to approve the MCP server
|
|
|
|
4. Accept the prompt, and the tools will be available!
|
|
|
|
**Test it:**
|
|
```
|
|
Can you list the available MCP tools?
|
|
```
|
|
|
|
You should see:
|
|
- `deploy_stack`
|
|
- `check_deployment_status`
|
|
- `list_deployments`
|
|
- `check_name_availability`
|
|
- `test_api_connections`
|
|
|
|
---
|
|
|
|
### Option 2: Global MCP Plugin (Always available)
|
|
|
|
If you want the AI Stack Deployer tools available in **all Claude Code sessions**, install it as a global plugin.
|
|
|
|
**Steps:**
|
|
|
|
1. Create plugin directory:
|
|
```bash
|
|
mkdir -p ~/.claude/plugins/ai-stack-deployer/.claude-plugin
|
|
```
|
|
|
|
2. Create `.mcp.json`:
|
|
```bash
|
|
cat > ~/.claude/plugins/ai-stack-deployer/.mcp.json << 'EOF'
|
|
{
|
|
"ai-stack-deployer": {
|
|
"command": "bun",
|
|
"args": [
|
|
"run",
|
|
"/home/odouhou/locale-projects/ai-stack-deployer/src/mcp-server.ts"
|
|
],
|
|
"env": {
|
|
"HETZNER_API_TOKEN": "${HETZNER_API_TOKEN}",
|
|
"DOKPLOY_API_TOKEN": "${DOKPLOY_API_TOKEN}",
|
|
"DOKPLOY_URL": "http://10.100.0.20:3000",
|
|
"HETZNER_ZONE_ID": "343733",
|
|
"STACK_DOMAIN_SUFFIX": "ai.flexinit.nl",
|
|
"STACK_IMAGE": "git.app.flexinit.nl/oussamadouhou/oh-my-opencode-free:latest",
|
|
"TRAEFIK_IP": "144.76.116.169"
|
|
}
|
|
}
|
|
}
|
|
EOF
|
|
```
|
|
|
|
3. Create `plugin.json`:
|
|
```bash
|
|
cat > ~/.claude/plugins/ai-stack-deployer/.claude-plugin/plugin.json << 'EOF'
|
|
{
|
|
"name": "ai-stack-deployer",
|
|
"description": "Self-service portal for deploying personal OpenCode AI stacks. Deploy, check status, and manage AI coding assistant deployments.",
|
|
"author": {
|
|
"name": "Oussama Douhou"
|
|
}
|
|
}
|
|
EOF
|
|
```
|
|
|
|
4. Set environment variables in your shell profile (`~/.bashrc` or `~/.zshrc`):
|
|
```bash
|
|
export HETZNER_API_TOKEN="your-token-here"
|
|
export DOKPLOY_API_TOKEN="your-token-here"
|
|
```
|
|
|
|
5. Restart Claude Code:
|
|
```bash
|
|
# Exit current session
|
|
claude
|
|
```
|
|
|
|
The plugin is now available globally!
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
The MCP server needs these environment variables:
|
|
|
|
| Variable | Value | Description |
|
|
|----------|-------|-------------|
|
|
| `HETZNER_API_TOKEN` | From BWS | Hetzner Cloud DNS API token |
|
|
| `DOKPLOY_API_TOKEN` | From BWS | Dokploy API token |
|
|
| `DOKPLOY_URL` | `http://10.100.0.20:3000` | Dokploy API URL |
|
|
| `HETZNER_ZONE_ID` | `343733` | flexinit.nl zone ID |
|
|
| `STACK_DOMAIN_SUFFIX` | `ai.flexinit.nl` | Domain suffix for stacks |
|
|
| `STACK_IMAGE` | `git.app.flexinit.nl/...` | Docker image |
|
|
| `TRAEFIK_IP` | `144.76.116.169` | Traefik IP address |
|
|
|
|
**Best practice:** Use environment variables instead of hardcoding in `.mcp.json`!
|
|
|
|
---
|
|
|
|
## Comparison Table
|
|
|
|
| Feature | Project-Level | Global Plugin |
|
|
|---------|---------------|---------------|
|
|
| **Scope** | Current project only | All Claude sessions |
|
|
| **Config location** | `./mcp.json` | `~/.claude/plugins/*/` |
|
|
| **Environment** | Inherits from shell | Defined in config |
|
|
| **Updates** | Automatic (uses local code) | Manual path updates |
|
|
| **Use case** | Development | Production use |
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### MCP server not appearing
|
|
|
|
1. **Check `.mcp.json` syntax:**
|
|
```bash
|
|
cat .mcp.json | jq .
|
|
```
|
|
|
|
2. **Verify Bun is installed:**
|
|
```bash
|
|
which bun
|
|
bun --version
|
|
```
|
|
|
|
3. **Test MCP server directly:**
|
|
```bash
|
|
bun run src/mcp-server.ts
|
|
# Press Ctrl+C to exit
|
|
```
|
|
|
|
4. **Check environment variables:**
|
|
```bash
|
|
cat .env
|
|
```
|
|
|
|
5. **Restart Claude Code completely:**
|
|
```bash
|
|
pkill -f claude
|
|
claude
|
|
```
|
|
|
|
### Tools not working
|
|
|
|
1. **Test API connections:**
|
|
```bash
|
|
bun run src/test-clients.ts
|
|
```
|
|
|
|
2. **Check Dokploy token is valid:**
|
|
- Visit https://deploy.intra.flexinit.nl
|
|
- Settings → Profile → API Tokens
|
|
- Generate new token if needed
|
|
|
|
3. **Check Hetzner token:**
|
|
- Visit https://console.hetzner.cloud
|
|
- Security → API Tokens
|
|
- Verify token has DNS permissions
|
|
|
|
### Deployment fails
|
|
|
|
Check the Claude Code debug logs:
|
|
```bash
|
|
tail -f ~/.claude/debug/*.log
|
|
```
|
|
|
|
---
|
|
|
|
## Converting Between Formats
|
|
|
|
If you need to convert this to OpenCode format later:
|
|
|
|
**From Claude Code (stdio):**
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ai-stack-deployer": {
|
|
"command": "bun",
|
|
"args": ["run", "src/mcp-server.ts"],
|
|
"env": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**To OpenCode (stdio):**
|
|
```json
|
|
{
|
|
"mcp": {
|
|
"ai-stack-deployer": {
|
|
"type": "stdio",
|
|
"command": "bun",
|
|
"args": ["run", "src/mcp-server.ts"],
|
|
"env": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The main difference is the `"mcp"` wrapper and explicit `"type": "stdio"`.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
✅ **Your current `.mcp.json` is already correct for Claude Code!**
|
|
|
|
✅ **No changes needed** - just start Claude Code in this directory
|
|
|
|
✅ **Optional:** Install as global plugin for use everywhere
|
|
|
|
✅ **Key insight:** stdio-based MCP servers use `command`/`args`, not `url`/`headers`
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. **Test the MCP server:**
|
|
```bash
|
|
cd ~/locale-projects/ai-stack-deployer
|
|
claude
|
|
```
|
|
|
|
2. **Ask Claude Code:**
|
|
```
|
|
Test the API connections for the AI Stack Deployer
|
|
```
|
|
|
|
3. **Deploy a test stack:**
|
|
```
|
|
Is the name "test-user" available?
|
|
Deploy an AI stack for "test-user"
|
|
```
|
|
|
|
4. **Check deployment status:**
|
|
```
|
|
Show me all recent deployments
|
|
```
|
|
|
|
---
|
|
|
|
**Ready to use! 🚀**
|