Skip to content

configuration.md

Latest commit

 

History

History
543 lines (424 loc) · 12.8 KB

configuration.md

File metadata and controls

543 lines (424 loc) · 12.8 KB
Raw

Configuration

This document provides a complete guide to configuring the Devora Prompt Assistant MCP server for different environments and use cases.

Table of Contents

Quick Start

Cursor Installation

The easiest way to get started is with the one-click Cursor installation:

Install MCP Server

Manual Configuration

Add this to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "devora-prompt-assistant": {
      "command": "npx",
      "args": ["-y", "@devora_no/prompt-assistant-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "OPENAI_API_KEY": "your-openai-key-here",
        "ANTHROPIC_API_KEY": "your-anthropic-key-here"
      }
    }
  }
}

Environment Variables

Required Variables

At least one AI provider API key is required:

# Choose at least one provider
OPENAI_API_KEY="sk-..."
ANTHROPIC_API_KEY="sk-ant-..."
AZURE_OPENAI_API_KEY="your-azure-key"
AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
AZURE_OPENAI_DEPLOYMENT="your-deployment-name"
GEMINI_API_KEY="AIza..."
PERPLEXITY_API_KEY="pplx-..."

Server Configuration

# Server Settings
SERVER_NAME="devora-prompt-assistant"
SERVER_VERSION="0.2.1"
LOG_LEVEL="info"                    # debug, info, warn, error
TRANSPORT="stdio"                   # stdio, streamable-http
PORT=8000                          # HTTP server port
BIND_ADDRESS="127.0.0.1"           # Server bind address

LLM Configuration

# LLM Settings
LLM_MODE="review"                  # review, refine, off
DEFAULT_PROVIDER="openai"          # openai, anthropic, gemini, perplexity, azureOpenAI

Security Configuration

# Security Settings
RATE_LIMIT_ENABLED="true"          # Enable rate limiting
RATE_LIMIT_CAPACITY=50             # Max requests per client
RATE_LIMIT_REFILL_RATE=5           # Requests per second
RATE_LIMIT_BURST_SIZE=20           # Burst capacity

# Circuit Breaker
CIRCUIT_BREAKER_ENABLED="true"     # Enable circuit breaker
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5 # Failures before opening
CIRCUIT_BREAKER_TIMEOUT=30000      # Timeout in milliseconds

# Authentication (HTTP only)
AUTH_BEARER_TOKENS="dev-token-123,prod-token-456"

Performance Configuration

# Performance Settings
LLM_TIMEOUT=30000                  # LLM request timeout
CONTEXT_COLLECTION_TIMEOUT=10000   # Context collection timeout
MAX_MEMORY_MB=512                  # Memory limit
CACHE_TTL_MINUTES=15               # Cache TTL

# Fallback Settings
FALLBACK_ENABLED="true"            # Enable fallback mechanisms
FALLBACK_TIMEOUT=10000             # Fallback timeout
FALLBACK_MAX_RETRIES=2             # Max retries

Logging Configuration

# Logging Settings
LOG_DIR="./logs"                   # Log directory
LOG_MAX_FILES=7                    # Max log files to keep
LOG_MAX_SIZE="100M"                # Max log file size
LOG_FORMAT="json"                  # json, text

Provider Setup

Anthropic Claude

  1. Get API Key: Visit Anthropic Console
  2. Set Environment Variable: 
    export ANTHROPIC_API_KEY="sk-ant-..."
  3. Default Model: claude-3-5-sonnet-latest
  4. Features: Best for complex reasoning and analysis

OpenAI

  1. Get API Key: Visit OpenAI Platform
  2. Set Environment Variable: 
    export OPENAI_API_KEY="sk-..."
  3. Default Model: o3-mini
  4. Features: Good balance of speed and quality

Azure OpenAI

  1. Get Credentials: From Azure Portal
  2. Set Environment Variables: 
    export AZURE_OPENAI_API_KEY="your-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_DEPLOYMENT="your-deployment-name"
  3. Default Model: gpt-4o-mini
  4. Features: Enterprise-grade OpenAI access

Google Gemini

  1. Get API Key: Visit Google AI Studio
  2. Set Environment Variable: 
    export GEMINI_API_KEY="AIza..."
  3. Default Model: gemini-2.0-flash
  4. Features: Fast and cost-effective

Perplexity

  1. Get API Key: Visit Perplexity Console
  2. Set Environment Variable: 
    export PERPLEXITY_API_KEY="pplx-..."
  3. Default Model: sonar
  4. Features: Good for research tasks

Transport Options

Stdio Transport (Default)

Best for: Local development, Cursor integration

{
  "mcpServers": {
    "devora-prompt-assistant": {
      "command": "npx",
      "args": ["-y", "@devora_no/prompt-assistant-mcp"],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}

Features:

  • Direct process communication
  • No network overhead
  • Automatic process management
  • Secure (no network exposure)

HTTP Transport (Experimental)

Best for: Remote access, production deployment

{
  "mcpServers": {
    "devora-prompt-assistant": {
      "command": "npx",
      "args": ["-y", "@devora_no/prompt-assistant-mcp"],
      "env": {
        "TRANSPORT": "streamable-http",
        "PORT": "8000",
        "AUTH_BEARER_TOKENS": "your-token-here"
      }
    }
  }
}

Features:

  • Server-Sent Events (SSE)
  • Load balancer compatible
  • Bearer token authentication
  • CORS support

Security Configuration

Rate Limiting

# Enable rate limiting
RATE_LIMIT_ENABLED="true"

# Configure limits
RATE_LIMIT_CAPACITY=50             # Max requests per client
RATE_LIMIT_REFILL_RATE=5           # Requests per second
RATE_LIMIT_BURST_SIZE=20           # Burst capacity

Circuit Breaker

# Enable circuit breaker
CIRCUIT_BREAKER_ENABLED="true"

# Configure thresholds
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5 # Failures before opening
CIRCUIT_BREAKER_TIMEOUT=30000      # Timeout in milliseconds

Authentication (HTTP Only)

# Set bearer tokens
AUTH_BEARER_TOKENS="dev-token-123,prod-token-456"

# Use in requests
curl -H "Authorization: Bearer dev-token-123" http://localhost:8000/health

Network Security

# Bind to localhost only
BIND_ADDRESS="127.0.0.1"

# Bind to all interfaces (production)
BIND_ADDRESS="0.0.0.0"

Performance Tuning

Memory Management

# Set memory limit
MAX_MEMORY_MB=512                  # Default
MAX_MEMORY_MB=1024                 # High memory
MAX_MEMORY_MB=2048                 # Very high memory

Caching

# Adjust cache TTL
CACHE_TTL_MINUTES=15               # Default
CACHE_TTL_MINUTES=30               # Longer cache
CACHE_TTL_MINUTES=5                # Shorter cache

Timeouts

# LLM timeout
LLM_TIMEOUT=30000                  # 30 seconds
LLM_TIMEOUT=60000                  # 60 seconds

# Context collection timeout
CONTEXT_COLLECTION_TIMEOUT=10000   # 10 seconds
CONTEXT_COLLECTION_TIMEOUT=30000   # 30 seconds

Connection Pooling

# HTTP connection settings (automatic)
# Max sockets: 100
# Max free sockets: 10
# Keep-alive: enabled

Logging Configuration

Log Levels

# Debug logging
LOG_LEVEL="debug"

# Production logging
LOG_LEVEL="info"

# Minimal logging
LOG_LEVEL="error"

Log Files

# Log directory
LOG_DIR="./logs"

# Log rotation
LOG_MAX_FILES=7                    # Keep 7 days
LOG_MAX_SIZE="100M"                # Max file size

# Log format
LOG_FORMAT="json"                  # JSON format
LOG_FORMAT="text"                  # Text format

Log Files Created

  • logs/YYYY-MM-DD-server.log - General application logs
  • logs/YYYY-MM-DD-error.log - Error-only logs
  • logs/YYYY-MM-DD-audit.log - Security and audit events

Environment-Specific Configs

Development Environment

# .env.development
LOG_LEVEL="debug"
RATE_LIMIT_ENABLED="false"
CIRCUIT_BREAKER_ENABLED="false"
LLM_MODE="review"

Production Environment

# .env.production
LOG_LEVEL="info"
RATE_LIMIT_ENABLED="true"
CIRCUIT_BREAKER_ENABLED="true"
MAX_MEMORY_MB=1024
CACHE_TTL_MINUTES=30

Testing Environment

# .env.test
LOG_LEVEL="error"
LLM_MODE="off"
CACHE_TTL_MINUTES=1
FALLBACK_ENABLED="false"

Docker Environment

# Docker environment
TRANSPORT="streamable-http"
BIND_ADDRESS="0.0.0.0"
LOG_FORMAT="json"

Configuration Examples

Minimal Configuration

{
  "mcpServers": {
    "devora-prompt-assistant": {
      "command": "npx",
      "args": ["-y", "@devora_no/prompt-assistant-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Full Configuration

{
  "mcpServers": {
    "devora-prompt-assistant": {
      "command": "npx",
      "args": ["-y", "@devora_no/prompt-assistant-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "LOG_LEVEL": "info",
        "LLM_MODE": "review",
        "DEFAULT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "RATE_LIMIT_ENABLED": "true",
        "CIRCUIT_BREAKER_ENABLED": "true",
        "MAX_MEMORY_MB": "512",
        "CACHE_TTL_MINUTES": "15"
      }
    }
  }
}

Production Configuration

{
  "mcpServers": {
    "devora-prompt-assistant": {
      "command": "npx",
      "args": ["-y", "@devora_no/prompt-assistant-mcp"],
      "env": {
        "TRANSPORT": "streamable-http",
        "PORT": "8000",
        "BIND_ADDRESS": "0.0.0.0",
        "LOG_LEVEL": "info",
        "LOG_FORMAT": "json",
        "LLM_MODE": "review",
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "AUTH_BEARER_TOKENS": "prod-token-123",
        "RATE_LIMIT_ENABLED": "true",
        "CIRCUIT_BREAKER_ENABLED": "true",
        "MAX_MEMORY_MB": "1024",
        "CACHE_TTL_MINUTES": "30"
      }
    }
  }
}

Troubleshooting

Common Configuration Issues

"No providers configured" Error

  1. Check API keys: Ensure at least one provider API key is set
  2. Verify format: Check API key format and validity
  3. Check environment: Ensure environment variables are loaded

"Invalid configuration" Error

  1. Check syntax: Verify JSON syntax in configuration files
  2. Check values: Ensure all values are within valid ranges
  3. Check required fields: Ensure all required fields are present

"Rate limit exceeded" Error

  1. Wait and retry: Automatic backoff is enabled
  2. Adjust limits: Increase RATE_LIMIT_CAPACITY if needed
  3. Use different provider: Switch to a different AI provider

"Circuit breaker open" Error

  1. Wait for timeout: Circuit breaker resets after timeout
  2. Check provider health: Ensure AI provider is accessible
  3. Reset manually: Use health check endpoint to reset

Debug Commands

Check Configuration

# Test configuration
node -e "console.log(process.env.OPENAI_API_KEY ? 'OpenAI configured' : 'OpenAI not configured')"

Check Server Health

# Health check
curl http://localhost:8000/health

# Metrics
curl http://localhost:8000/metrics

Check Logs

# Server logs
tail -f logs/server.log

# Error logs
tail -f logs/error.log

# Debug logs
LOG_LEVEL=debug npm start

Getting Help

  1. Check Documentation: Review this guide and other docs
  2. GitHub Issues: Report bugs
  3. Discussions: Ask questions
  4. Security: Report security issues

Last Updated: October 12, 2025
Version: 0.2.1
Status: Production Ready
Security Status: ✅ Secured & Monitored
Maintained by: Devora

Developed by Devora ☔️

Brave • Innovative • Responsible • Creative • Different