bc-code-intelligence-mcp

--- title: "Layer System Fundamentals" domain: "chris-config" bc_versions: "1.5.0+" difficulty: "intermediate" tags: ["mcp-configuration", "layer-architecture", "knowledge-management", "override-system"] related_topics: - "content-types-structure.md" - "layer-override-strategies.md" - "configuration-file-discovery.md" applies_to: - "BC Code Intelligence MCP Server" - "Knowledge Layer Architecture" last_updated: "2025-10-27" --- # Layer System Fundamentals ## Overview The BC Code Intelligence MCP server uses a **4-layer knowledge architecture** that enables progressive customization from embedded defaults through company-wide standards to project-specific overrides. Understanding this layered approach is fundamental to effective MCP configuration. ## The Four-Layer Architecture ### **Layer 0: Embedded Knowledge** (Priority 0) - **Source**: NPM package embedded knowledge (git submodule) - **Content**: Core BC knowledge - 87+ topics, 14 specialists, methodologies - **Scope**: Universal - available to all users - **Modifiable**: No - read-only embedded content - **Use Case**: Default knowledge base, zero-configuration experience **Key Characteristics:** - Highest reliability - always available - Officially maintained BC knowledge - Comprehensive coverage of BC development patterns - Updates via npm package updates ### **Layer 1-2: Company Knowledge** (Priority 20-50) - **Source**: Git repositories (Azure DevOps, GitHub, etc.) - **Content**: Company-specific specialists, standards, patterns - **Scope**: Organization-wide - **Modifiable**: Yes - via git repository updates - **Use Case**: Company coding standards, custom specialists, org patterns **Key Characteristics:** - Centrally managed company knowledge - Authentication-based access control (PAT tokens) - Cached locally for performance (`.bckb-cache/git-repos/`) - Can override embedded knowledge with company-specific guidance ### **Layer 3: Team Knowledge** (Priority 60-80) - **Source**: Shared team directories or repositories - **Content**: Team conventions, project templates, shared patterns - **Scope**: Team or department - **Modifiable**: Yes - team-managed - **Use Case**: Team-specific patterns, shared project standards **Key Characteristics:** - Team collaboration and knowledge sharing - More specific than company, less specific than project - Useful for department or team conventions ### **Layer 4: Project Knowledge** (Priority 100) - **Source**: Local `./bc-code-intel-overrides/` directory - **Content**: Project-specific overrides, custom topics, local specialists - **Scope**: Single project/workspace - **Modifiable**: Yes - locally managed - **Use Case**: Project-specific patterns, temporary overrides, local experimentation **Key Characteristics:** - Highest priority - always wins in conflicts - Local filesystem access (no authentication needed) - Perfect for project-specific customization - Useful for testing new knowledge before promoting to higher layers ## Layer Resolution and Override Behavior ### **Priority-Based Resolution** When the same topic/specialist exists in multiple layers: 1. **Highest priority layer wins** (Project > Team > Company > Embedded) 2. Content is **completely replaced**, not merged 3. Only the highest-priority version is returned **Example:** ``` Embedded Layer (0): sam-coder.md (official specialist) Company Layer (20): sam-coder.md (company-customized version) Project Layer (100): sam-coder.md (project-specific override) Result: Project layer version is used ``` ### **Content Type Support** All layers support three content types (as of v1.5.0): - **Topics**: BC domain knowledge (in `domains/` subdirectory) - **Specialists**: AI persona definitions (in `specialists/` subdirectory) - **Methodologies**: Systematic workflows (in `methodologies/` subdirectory) Each layer independently manages these three content types. ## Layer Configuration ### **Embedded Layer** (No Configuration Needed) ```json // Automatically available - no configuration required // Loaded from NPM package embedded-knowledge/ directory ``` ### **Git Layer** (Company/Team Knowledge) ```json { "knowledge_layers": [ { "name": "Company BC Standards", "type": "git", "priority": 20, "source": { "repository_url": "https://dev.azure.com/your-org/BC-Knowledge/_git/bc-standards", "branch": "main", "auth": { "type": "pat", "token_env_var": "AZURE_DEVOPS_PAT" } } } ] } ``` ### **Project Layer** (Local Overrides) ```json { "knowledge_layers": [ { "name": "Project Overrides", "type": "project", "priority": 100, "source": { "path": "./bc-code-intel-overrides" } } ] } ``` ## Directory Structure Requirements Each layer must follow this structure for content type discovery: ``` layer-root/ ├── domains/ # BC knowledge topics │ ├── performance/ │ ├── api-design/ │ └── [other domains]/ ├── specialists/ # AI specialist definitions │ ├── sam-coder.md │ ├── dean-debug.md │ └── [other specialists].md └── methodologies/ # Systematic workflows ├── optimize-performance/ └── [other workflows]/ ``` **Important:** Git layers look for these subdirectories. If missing, that content type won't be loaded from that layer. ## Workspace Management and Layer Loading ### **VS Code Workspace Detection Issue** The VS Code MCP extension doesn't set `process.cwd()` to the workspace root, causing project layer detection to fail. **Solution:** Use workspace management tools (v1.5.0+) ```typescript // Set workspace root explicitly set_workspace_root({ workspace_root: "/path/to/your/workspace" }) // Triggers: // 1. process.chdir() to workspace // 2. Full service reinitialization // 3. Layer reloading with new workspace context ``` ### **Lazy Initialization Pattern** The MCP server uses lazy initialization: 1. **Startup**: Load embedded knowledge only (fast startup) 2. **First Tool Call**: If workspace not set, prompt for `set_workspace_root` 3. **After Workspace Set**: Full initialization including all configured layers ## Layer Caching and Performance ### **Git Layer Caching** Git repositories are cloned to `.bckb-cache/git-repos/{hash}/`: - **First Load**: Clone repository (may take seconds) - **Subsequent Loads**: Use cached local copy (sub-100ms) - **Updates**: Periodic pull or manual cache invalidation ### **Performance Characteristics** - Embedded Layer: <10ms (in-memory) - Project Layer: <50ms (filesystem access) - Git Layer (cached): <100ms (filesystem + parsing) - Git Layer (uncached): 2-5 seconds (git clone operation) ## Best Practices 1. **Start Simple**: Use embedded knowledge first, add layers as needed 2. **Layer Discipline**: Keep clear separation between layer purposes 3. **Override Sparingly**: Only override when truly necessary for your context 4. **Document Decisions**: Each layer should have clear purpose documentation 5. **Test Incrementally**: Add one layer at a time, validate before adding next 6. **Cache Management**: Understand git layer caching for performance tuning ## Common Patterns ### **Individual Developer** (Zero Config) ``` Embedded Layer only - no configuration needed ``` ### **Company with Standards** (Git Layer) ``` Embedded Layer (BC knowledge) + Company Git Layer (org standards) ``` ### **Team with Project Overrides** (All Layers) ``` Embedded + Company Git + Project Local ``` ## Troubleshooting **Layer not loading?** - Check directory structure (domains/, specialists/, methodologies/) - Verify authentication (PAT tokens for git layers) - Check layer priority configuration - Use diagnostic tools if enabled **Content not found?** - Verify content type is in correct subdirectory - Check YAML frontmatter format (required for specialists) - Confirm layer priority order - Search across all layers to see where content exists ## See Also - [Content Types Structure](content-types-structure.md) - Format requirements for each content type - [Layer Override Strategies](layer-override-strategies.md) - When and how to override - [Configuration File Discovery](configuration-file-discovery.md) - Where config files are found - [Workspace Detection Solutions](workspace-detection-solutions.md) - Solving workspace issues - [Git Layer Configuration](git-layer-configuration.md) - Git layer setup details