# MCP Configuration Guide

This document explains how to configure per-repository MCP (Model Context Protocol) servers for the Agent Manager.

## Overview

The Agent Manager supports three levels of MCP configuration:

1. **Repository-specific configuration** - Unique MCP servers for each repository
2. **Global default configuration** - Shared MCP servers for all repositories
3. **Hardcoded fallback** - Built-in gogs-mcp server (automatic)

## Configuration Priority

When processing an issue, the system looks for MCP configuration in this order:

1. `~/.config/agent-manager/mcp/{owner}/{repo}.json` - Repository-specific
2. `~/.config/agent-manager/mcp/default.json` - Global default
3. Hardcoded fallback (gogs-mcp only)

## Configuration Directory

All MCP configuration files are stored in:

```
~/.config/agent-manager/mcp/
├── default.json                    # Global default config
├── fszontagh/
│   ├── agent-manager.json         # Config for fszontagh/agent-manager
│   └── my-project.json            # Config for fszontagh/my-project
└── otheruser/
    └── their-repo.json            # Config for otheruser/their-repo
```

**Security Note:** Configuration files should have restrictive permissions (600 or 400) since they may contain secrets like API keys or JWT tokens.

## Configuration File Format

MCP configuration files use JSON format:

```json
{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}
```

### Server Types

- `stdio` - Standard input/output communication (most common)
- `http` - HTTP-based communication
- `sse` - Server-Sent Events communication

### Environment Variable Substitution

Configuration files support `${VAR_NAME}` syntax for environment variables. This allows you to keep secrets out of the config files:

```json
{
  "mcpServers": {
    "api-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/api-mcp/dist/index.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "API_URL": "https://api.example.com"
      }
    }
  }
}
```

The `${MY_API_KEY}` will be replaced with the value from `process.env.MY_API_KEY` at runtime.

## Example Configurations

### Example 1: Global Default (All Repositories)

File: `~/.config/agent-manager/mcp/default.json`

```json
{
  "mcpServers": {
    "gogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/gogs-mcp/dist/index.js"],
      "env": {}
    }
  }
}
```

### Example 2: Repository-Specific with Multiple Servers

File: `~/.config/agent-manager/mcp/fszontagh/my-app.json`

```json
{
  "mcpServers": {
    "gogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/gogs-mcp/dist/index.js"],
      "env": {}
    },
    "database": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/database-mcp/dist/index.js"],
      "env": {
        "DB_HOST": "${DB_HOST}",
        "DB_USER": "${DB_USER}",
        "DB_PASSWORD": "${DB_PASSWORD}",
        "DB_NAME": "myapp"
      }
    },
    "slack": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/slack-mcp/dist/index.js"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_CHANNEL": "#deployments"
      }
    }
  }
}
```

### Example 3: Different Configs for Different Projects

**Project A** (uses Gogs + PostgreSQL):
```json
{
  "mcpServers": {
    "gogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/gogs-mcp/dist/index.js"],
      "env": {}
    },
    "postgres": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/postgres-mcp/dist/index.js"],
      "env": {
        "PGHOST": "${PGHOST}",
        "PGUSER": "${PGUSER}",
        "PGPASSWORD": "${PGPASSWORD}"
      }
    }
  }
}
```

**Project B** (uses Gogs + MongoDB + Redis):
```json
{
  "mcpServers": {
    "gogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/gogs-mcp/dist/index.js"],
      "env": {}
    },
    "mongodb": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/mongodb-mcp/dist/index.js"],
      "env": {
        "MONGO_URI": "${MONGO_URI}"
      }
    },
    "redis": {
      "type": "stdio",
      "command": "node",
      "args": ["/data/redis-mcp/dist/index.js"],
      "env": {
        "REDIS_URL": "${REDIS_URL}"
      }
    }
  }
}
```

## Creating Configuration Files

### Method 1: Manual Creation

Create the directory structure and file:

```bash
mkdir -p ~/.config/agent-manager/mcp/owner
nano ~/.config/agent-manager/mcp/owner/repo.json
chmod 600 ~/.config/agent-manager/mcp/owner/repo.json
```

### Method 2: Using McpConfigManager API

```typescript
import { McpConfigManager } from './client/dist/index.js';

// Create global default config
McpConfigManager.createDefaultConfig({
  mcpServers: {
    gogs: {
      type: 'stdio',
      command: 'node',
      args: ['/data/gogs-mcp/dist/index.js'],
      env: {}
    }
  }
});

// Create repository-specific config
McpConfigManager.createRepoConfig('owner', 'repo', {
  mcpServers: {
    gogs: {
      type: 'stdio',
      command: 'node',
      args: ['/data/gogs-mcp/dist/index.js'],
      env: {}
    },
    custom: {
      type: 'stdio',
      command: 'node',
      args: ['/path/to/custom-mcp/dist/index.js'],
      env: {
        'API_KEY': process.env.API_KEY
      }
    }
  }
});
```

## Security Best Practices

1. **File Permissions**: Always set configuration files to 600 (owner read/write only)
   ```bash
   chmod 600 ~/.config/agent-manager/mcp/owner/repo.json
   ```

2. **Use Environment Variables**: Never hardcode secrets in config files. Use `${VAR_NAME}` syntax instead.

3. **Restrict Directory Access**: The MCP config directory should be readable only by the user running agent-manager:
   ```bash
   chmod 700 ~/.config/agent-manager/mcp
   ```

4. **Keep Secrets in .env**: Store actual secret values in the agent-manager `.env` file or system environment variables.

## Troubleshooting

### Configuration Not Loading

Check the logs when an issue is processed. You should see one of:
- `Using repository-specific MCP config: ~/.config/agent-manager/mcp/owner/repo.json`
- `Using global default MCP config: ~/.config/agent-manager/mcp/default.json`
- `Using hardcoded default MCP config (gogs-mcp only)`

### Permission Warnings

If you see:
```
Warning: MCP config file has insecure permissions (644). Should be 600 or 400.
```

Fix with:
```bash
chmod 600 ~/.config/agent-manager/mcp/owner/repo.json
```

### Environment Variables Not Substituted

Ensure the environment variable is set in the agent-manager process environment:

```bash
# In .env or systemd service file
export MY_API_KEY="secret-value"
```

Then restart the agent-manager service.

## Examples

Example configuration files are provided in `examples/`:

- `mcp-config-default.json` - Simple single-server config
- `mcp-config-multi-server.json` - Multiple servers with env var substitution

## Migration from Hardcoded Config

If you're currently using the default hardcoded gogs-mcp configuration, you can:

1. **Keep using the default** - No action needed, it will continue to work
2. **Create a global default** - Copy `examples/mcp-config-default.json` to `~/.config/agent-manager/mcp/default.json`
3. **Create repo-specific configs** - For repositories that need custom MCP servers

The system is fully backward compatible with the existing behavior.