Skip to content

config_quick_start.md

Latest commit

 

History

History
217 lines (164 loc) · 3.95 KB

config_quick_start.md

File metadata and controls

217 lines (164 loc) · 3.95 KB

Configuration Quick Start

⚡ Essential Setup

1. Initialize Configuration

# Create default config.json
make setup

# Or manually
python -c "from src.config import Config; cfg=Config(); cfg.create_default(); cfg.save()"

2. Basic Configuration

Edit config.json:

{
  "server": {
    "host": "localhost",
    "port": 3000,
    "api_key": "your-secure-api-key-here"
  },
  "logging": {
    "level": "INFO"
  },
  "mcp_servers": [
    {
      "name": "filesystem",
      "command": "uvx",
      "args": ["mcp-server-filesystem", "/path/to/directory"],
      "enabled": true
    }
  ]
}

3. Start Server

make run

🔧 Common Configurations

Filesystem Access

{
  "name": "documents",
  "command": "uvx", 
  "args": ["mcp-server-filesystem", "/home/user/documents"],
  "enabled": true
}

GitHub Integration

{
  "name": "github",
  "command": "uvx",
  "args": ["mcp-server-github"],
  "env": {
    "GITHUB_TOKEN": "ghp_your_token_here"
  },
  "enabled": true
}

Custom Python MCP

{
  "name": "custom-tools",
  "command": "python",
  "args": ["-m", "my_mcp_package"],
  "env": {
    "API_KEY": "secret"
  },
  "enabled": false
}

🛡️ Security Essentials

Change Default API Key

⚠️ Important: Change the default API key!

# Generate secure key
openssl rand -base64 32

# Update config.json
{
  "server": {
    "api_key": "generated-secure-key-here"
  }
}

File Permissions

# Secure config file
chmod 600 config.json

🧪 Test Configuration

# Validate config by loading
python -c "from src.config import Config; print('✅ Loaded' if Config() else '❌')"

# Test server
curl http://localhost:3001/health

# Test authentication
curl -H "Authorization: Bearer your-api-key" \
     http://localhost:3001/mcp/status

📝 Configuration Structure

Section Purpose Required
server Server settings & auth ✅
logging Log configuration ✅
mcp_servers MCP server definitions ✅

Server Options

  • host: Bind address (default: "localhost")
  • port: Server port (default: 3000) (for MCP server, api is on this + 1)
  • api_key: Authentication key (⚠️ change from default)

MCP Server Options

  • name: Unique server identifier
  • command: Executable to run
  • args: Command line arguments
  • env: Environment variables (optional)
  • enabled: Auto-start on server boot

🚀 Quick Patterns

Development Setup

{
  "server": {"port": 3000, "api_key": "dev-key"},
  "logging": {"level": "DEBUG"},
  "mcp_servers": [
    {"name": "test-fs", "command": "uvx", "args": ["mcp-server-filesystem", "/tmp"], "enabled": true}
  ]
}

Production Setup

{
  "server": {"host": "0.0.0.0", "port": 3000, "api_key": "secure-32-char-key"},
  "logging": {"level": "INFO"},
  "mcp_servers": [
    {"name": "workspace", "command": "uvx", "args": ["mcp-server-filesystem", "/data"], "enabled": true}
  ]
}

🔍 Troubleshooting

Config Validation Failed

# Check JSON syntax
python -m json.tool config.json

# Check configuration loading
python -c "from src.config import Config; _=Config()"

Server Won't Start

# Check port availability
lsof -i :3000

# Check command exists
which uvx

# Enable debug logging
{"logging": {"level": "DEBUG"}}

Authentication Issues

# Verify API key in config
grep api_key config.json

# Test with correct key
curl -H "Authorization: Bearer correct-key" http://localhost:3001/mcp/status

📚 Next Steps

Quick help: Run make help to see all available commands.