Files

Oussama Douhou e617114310 refactor: enterprise-grade project structure

- Move test files to tests/
- Archive session notes to docs/archive/
- Remove temp/diagnostic files
- Clean src/ to only contain production code

2026-01-10 12:32:54 +01:00

7.7 KiB

Raw Blame History

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

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

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

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

✅ Uses "mcpServers" wrapper (Claude Code standard)
✅ Defines command and args (stdio transport)
✅ Empty env object (will inherit from shell)
✅ 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:

Navigate to this project directory:
```
cd ~/locale-projects/ai-stack-deployer
```
Start Claude Code:
```
claude
```
Claude Code will detect .mcp.json and prompt you to approve the MCP server
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:

Create plugin directory:

mkdir -p ~/.claude/plugins/ai-stack-deployer/.claude-plugin

Create .mcp.json:

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

Create plugin.json:

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

Set environment variables in your shell profile (~/.bashrc or ~/.zshrc):

export HETZNER_API_TOKEN="your-token-here"
export DOKPLOY_API_TOKEN="your-token-here"

Restart Claude Code:
```
# 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

Check .mcp.json syntax:
```
cat .mcp.json | jq .
```
Verify Bun is installed:
```
which bun
bun --version
```

Test MCP server directly:

bun run src/mcp-server.ts
# Press Ctrl+C to exit

Check environment variables:
```
cat .env
```
Restart Claude Code completely:
```
pkill -f claude
claude
```

Tools not working

Test API connections:
```
bun run src/test-clients.ts
```
Check Dokploy token is valid:
- Visit https://deploy.intra.flexinit.nl
- Settings → Profile → API Tokens
- Generate new token if needed
Check Hetzner token:
- Visit https://console.hetzner.cloud
- Security → API Tokens
- Verify token has DNS permissions

Deployment fails

Check the Claude Code debug logs:

tail -f ~/.claude/debug/*.log

Converting Between Formats

If you need to convert this to OpenCode format later:

From Claude Code (stdio):

{
  "mcpServers": {
    "ai-stack-deployer": {
      "command": "bun",
      "args": ["run", "src/mcp-server.ts"],
      "env": {}
    }
  }
}

To OpenCode (stdio):

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

Test the MCP server:

cd ~/locale-projects/ai-stack-deployer
claude

Ask Claude Code:

Test the API connections for the AI Stack Deployer

Deploy a test stack:

Is the name "test-user" available?
Deploy an AI stack for "test-user"

Check deployment status:
```
Show me all recent deployments
```

Ready to use! 🚀

7.7 KiB Raw Blame History