Skip to content

Basic Configuration

Jump to bottom
Jeremy Vyska edited this page Oct 30, 2025 · 3 revisions

Basic Configuration

Essential configuration guide for the BC Code Intelligence MCP Server. Learn how to set up the server for your specific needs, from simple individual use to multi-team environments.

🚀 Configuration Levels

Level 0: Zero Configuration (Default)

Perfect for getting started immediately

npm install -g bc-code-intelligence-mcp
bc-code-intel-server

What you get:

  • ✅ Embedded BC knowledge base (pre-configured topics)
  • ✅ Automatic project override detection (./bc-code-intel-overrides/)
  • ✅ Basic layer system (embedded + local overrides)
  • ✅ MCP protocol ready for AI tools

Level 1: Environment Variables

Great for consistent team environments

# Point to company knowledge repository  
export BC_KNOWLEDGE_GIT_URL="https://github.com/company/bc-knowledge"
export GITHUB_TOKEN="your_token_here"

# Start server
bc-code-intel-server

Level 2: Configuration File

Recommended for structured setups

Create bc-code-intel-config.json in your project root:

{
  "layers": [
    {
      "name": "embedded",
      "priority": 0,
      "source": { "type": "embedded" },
      "enabled": true
    },
    {
      "name": "project",
      "priority": 100,
      "source": { 
        "type": "local", 
        "location": "./bc-code-intel-overrides" 
      },
      "enabled": true
    }
  ],
  "cache": {
    "ttl": "24h"
  }
}

💡 Need Help Choosing Your Configuration Approach?

The Chris Config specialist can help you determine the best configuration level for your scenario. Ask questions like:

  • "Should I use user-level or project-level config for my team?"
  • "How do I configure Git layer authentication for my organization?"
  • "What's the best way to share team standards across projects?"

Level 3: Multi-Team Setup

For teams using shared knowledge repositories

{
  "layers": [
    {
      "name": "embedded",
      "priority": 0,
      "source": { "type": "embedded" }
    },
    {
      "name": "company",
      "priority": 25,
      "source": { 
        "type": "git",
        "location": "https://github.com/company/bc-knowledge",
        "branch": "main"
      },
      "auth": {
        "type": "token",
        "token": "${GITHUB_TOKEN}"
      }
    },
    {
      "name": "team",
      "priority": 50,
      "source": { 
        "type": "git",
        "location": "https://github.com/team/bc-patterns",
        "branch": "main"
      },
      "auth": {
        "type": "token", 
        "token": "${GITHUB_TOKEN}"
      }
    },
    {
      "name": "project",
      "priority": 100,
      "source": { 
        "type": "local",
        "location": "./bc-code-intel-overrides" 
      }
    }
  ],
  "cache": {
    "ttl": "4h"
  }
}

⚙️ Configuration Options Reference

Layer Configuration

{
  "layers": [
    {
      "name": "layer-name",              // Unique identifier
      "priority": 50,                    // 0-100, higher wins conflicts
      "enabled": true,                   // Can be toggled on/off
      "source": {
        "type": "embedded|local|git",    // Source type
        "location": "path/url",          // Path or Git URL
        "branch": "main"                 // For git sources
      },
      "auth": {                          // For private Git repos
        "type": "token",
        "token": "${GITHUB_TOKEN}"
      }
    }
  ]
}

Cache Configuration

{
  "cache": {
    "ttl": "24h",                      // Time-to-live for cached content
    "enabled": true                    // Enable/disable caching
  }
}

Performance Configuration

{
  "performance": {
    "maxConcurrentLoads": 3,           // Parallel layer loading limit
    "requestTimeout": "30s"            // Request timeout for Git operations
  }
}

🗂️ Directory Structure Patterns

Individual Developer Setup

my-bc-project/
├── bc-code-intel-config.json       # Basic configuration
├── bc-code-intel-overrides/        # Project-specific overrides
│   ├── domains/
│   │   └── performance/
│   │       └── my-caching-patterns.md
│   └── specialists/
│       └── my-code-reviewer.md
└── src/                            # Your BC source code

Team Setup

team-project/
├── bc-code-intel-config.json       # Team configuration
├── bc-code-intel-overrides/        # Project overrides
└── src/

Multi-Team Setup

enterprise-bc-solution/
├── bc-code-intel-config.json       # Multi-layer configuration
├── bc-code-intel-overrides/        # Solution-specific
└── projects/
    ├── project-a/
    └── project-b/

🔧 Configuration Discovery Order

The MCP server searches for configuration in this priority order:

  1. Command Line Arguments (highest)

    bc-code-intel-server --config /path/to/config.json

  2. Environment Variables

    export BC_CONFIG_PATH="/path/to/config.json"
export BC_KNOWLEDGE_GIT_URL="https://github.com/company/knowledge"
export GITHUB_TOKEN="your_token"

  3. Project Configuration Files

    ./bc-code-intel-config.json      # JSON format
./bc-code-intel-config.yaml      # YAML format  
./bc-code-intel-overrides/config.json

  4. User Configuration

    ~/.bc-code-intel/config.json     # User home directory
~/.config/bc-code-intel/config.json

  5. Embedded Defaults (lowest)

🎛️ Runtime Configuration

Environment Variable Reference

# Core Settings
BC_CONFIG_PATH="/path/to/config"         # Configuration file location
BC_DEBUG=true                            # Enable debug logging

# Knowledge Sources
BC_KNOWLEDGE_GIT_URL="https://..."       # Remote knowledge repository
GITHUB_TOKEN="your_token_here"           # GitHub authentication

# Cache Settings
BC_CACHE_TTL="24h"                       # Cache time-to-live
BC_CACHE_DISABLED=false                  # Disable all caching

Command Line Options

# Basic usage
bc-code-intel-server                     # Use default configuration
bc-code-intel-server --port 3000        # Specify port
bc-code-intel-server --config config.json # Use specific config file

# Debug options
bc-code-intel-server --debug             # Enable debug logging
bc-code-intel-server --validate-config  # Validate configuration only

📋 Configuration Validation

Validate Configuration

# Validate configuration file
bc-code-intel-server --validate-config

# Show resolved configuration
bc-code-intel-server --show-config

Configuration Health Check

bc-code-intel-server --debug

Expected output:

BC Code Intelligence MCP Server starting...
✅ Configuration: bc-code-intel-config.json (valid)
✅ Embedded layer: Available (87 topics)
✅ Company layer: Accessible (GitHub token valid)
✅ Project layer: Found (./bc-code-intel-overrides/)
✅ MCP Server: Ready on port 3000

📊 Layer Resolution Summary:
  - Total topics available: 135
  - Project overrides: 3
  - Layer priority: embedded(0) < company(25) < project(100)

🎉 Server ready for MCP connections!

🚨 Common Configuration Issues

Issue: Layers Not Loading

Symptoms: Missing knowledge, only embedded layer working

Solutions:

# Check Git authentication
echo $GITHUB_TOKEN

# Test Git access manually
git clone https://github.com/your-org/bc-knowledge

# Enable debug logging
bc-code-intel-server --debug

Issue: Authentication Failures

Symptoms: Git layer loading fails, 401/403 errors

Solutions:

# Check GitHub token
echo $GITHUB_TOKEN

# Test token validity
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

# Use SSH instead of HTTPS
{
  "source": {
    "type": "git",
    "location": "git@github.com:company/knowledge.git"
  }
}

Issue: Project Overrides Not Found

Symptoms: Local overrides not being loaded

Solutions:

# Check directory exists
ls -la ./bc-code-intel-overrides/

# Verify structure
ls -la ./bc-code-intel-overrides/domains/
ls -la ./bc-code-intel-overrides/specialists/

🔗 Configuration Examples by Use Case

Solo Developer

{
  "layers": [
    { 
      "name": "embedded", 
      "priority": 0,
      "source": { "type": "embedded" }
    },
    { 
      "name": "project", 
      "priority": 100, 
      "source": { "type": "local", "location": "./bc-code-intel-overrides" }
    }
  ]
}

Small Team (2-5 developers)

{
  "layers": [
    { 
      "name": "embedded", 
      "priority": 0,
      "source": { "type": "embedded" }
    },
    { 
      "name": "team", 
      "priority": 50, 
      "source": { 
        "type": "git", 
        "location": "https://github.com/team/bc-knowledge" 
      },
      "auth": { "type": "token", "token": "${GITHUB_TOKEN}" }
    },
    { 
      "name": "project", 
      "priority": 100, 
      "source": { "type": "local", "location": "./bc-code-intel-overrides" }
    }
  ]
}

Multi-Team Organization

{
  "layers": [
    { 
      "name": "embedded", 
      "priority": 0,
      "source": { "type": "embedded" }
    },
    { 
      "name": "company", 
      "priority": 25, 
      "source": { 
        "type": "git", 
        "location": "https://github.com/company/bc-standards" 
      },
      "auth": { "type": "token", "token": "${GITHUB_TOKEN}" }
    },
    { 
      "name": "team", 
      "priority": 50, 
      "source": { 
        "type": "git", 
        "location": "https://github.com/team/bc-patterns" 
      },
      "auth": { "type": "token", "token": "${GITHUB_TOKEN}" }
    },
    { 
      "name": "project", 
      "priority": 100, 
      "source": { "type": "local", "location": "./bc-code-intel-overrides" }
    }
  ]
}

⏭️ Next Steps

After basic configuration:

  1. Layer System Overview - Understand the layer architecture
  2. Knowledge Overrides - Create custom content
  3. Specialists System - Configure AI personas
  4. Enterprise Configuration - Advanced multi-team setups

🔗 Related Documentation

Configuration complete? Continue to Knowledge Overrides to learn how to customize the knowledge base for your specific needs.

Clone this wiki locally