MCP Servers (Code Intelligence & Database)

Model Context Protocol (MCP) provides structured, token-efficient semantic code retrieval and universal database access.

---

Why integrate MCP? (Core Significance & Design Philosophy)

Traditional AI coding assistants rely on blind text searching (grep / glob) and bulk file reads to understand codebases. For non-trivial repositories, this pattern suffers from severe bottlenecks:

1. Context Window Saturation & High Token Cost: Tracing a multi-step call chain often requires reading dozens of files, quickly bloating context tokens, degrading reasoning quality, and driving up API costs.
2. Lack of Structural Global Awareness: Text grep cannot understand AST syntax trees, polymorphism / dynamic dispatch, interface implementations, or multi-hop call paths. As a result, agents easily overlook the blast radius (downstream breakages) of a change.
3. Database Hallucination & Trial-and-Error: When dealing with databases, LLMs frequently hallucinate table or column names, leading to SQL execution errors and wasted roundtrips.

To eliminate these bottlenecks, this configuration integrates a tiered Code Intelligence & Database Gateway matrix via the Model Context Protocol (MCP):

                               ┌────────────────────────────────────────────────────────┐
                               │               OpenCode Agent Team                      │
                               └───────┬─────────────────┬────────────────────┬─────────┘
                                       │                 │                    │
              ┌────────────────────────┴────────┐ ┌──────┴───────────────┐ ┌──┴─────────────────────────┐
              │      Symbol-Level (Real-time)   │ │  Macro Graph & Architecture│ │   Universal Database Gateway  │
              │         (Symbol Layer)          │ │       (Graph Layer)   │ │      (Database Layer)         │
              ├─────────────────────────────────┤ ├───────────────────────┤ ├─────────────────────────────┤
              │ Serena MCP (Live LSP)           │ │ CodeGraph / GitNexus  │ │ DBHub MCP (Bytebase)        │
              │ • find_symbol                   │ │ • codegraph_explore   │ │ • search_objects (Metadata) │
              │ • find_referencing_symbols      │ │ • Call paths / Impact │ │ • execute_sql (Read-only)   │
              │ • get_symbols_overview          │ │ • Cross-file overview │ │                             │
              └─────────────────────────────────┘ └───────────────────────┘ └─────────────────────────────┘

• Precise Symbol Inquiries → Serena (LSP): Exact definitions, references, and symbol outlines. Zero indexing wait, minimal payload, returns only what's asked without bloating the context.
• Architectural Understanding & Impact → CodeGraph / GitNexus: "How does component X work?", "What breaks if I change this function?" — single-call responses covering complete call flows and blast radius.
• Reliable Data Exploration → DBHub: Enforces discovering real schema (search_objects) before running queries (execute_sql), preventing hallucinated table/column names.

---

Built-in MCP Servers Overview

Server	Type	License	Core Tool	Best For	Lifecycle & Indexing
Serena	Live LSP Semantic Engine	MIT	find_symbol, find_referencing_symbols, get_symbols_overview	Precise symbol lookups: definitions, references, file outlines (zero hallucination)	Connects live to LSP upon session start; no pre-indexing step
CodeGraph	Code Knowledge Graph (Default)	MIT	codegraph_explore	High-level architecture, "How X works", complete call paths, blast radius / impact analysis	Run codegraph init (or /project init) once per repo; background watcher auto-syncs on every save
GitNexus	Deep Graph Analysis (Optional)	PolyForm Noncommercial	Cypher queries, clustering	Multi-repo groups, arbitrary Cypher graph queries, cluster/process visualization	Re-index with gitnexus analyze (or /project index) after big changes
DBHub	Universal DB Gateway	MIT (Bytebase)	search_objects, execute_sql	Unified gateway for PostgreSQL / MySQL / SQLite / SQL Server / MariaDB	Per-project dbhub.toml config supporting ${ENV_VAR} interpolation
IDE	JetBrains IDE Bridge	—	IDE-native tools	Live access to the running IntelliJ / WebStorm / etc. — file editing, navigation, refactoring, run configs	IDE must be running with MCP server enabled (Settings → Tools → MCP Server); endpoint dies when IDE closes

---

Automated Provisioning & Configuration

The MCP stack is seamlessly woven into the installer and agent runtime:

1. Centralized Switches & CLI Auto-Provisioning (install/options.jsonc)

Manage active MCP servers in install/options.jsonc:

// install/options.jsonc
{
  "mcp": {
    "serena": true,     // LSP semantic queries (auto-installed via uv if missing)
    "codegraph": true,  // Code knowledge graph (auto-installed via npm if missing)
    "gitnexus": false,  // Deep Cypher graph (check PolyForm license for commercial use)
    "dbhub": true,      // Universal DB gateway (auto-installed via npm if missing)
    "idea": true        // JetBrains IDE bridge (enable MCP Server in IDE first)
  }
}

• Automatic CLI Provisioning: When running pwsh install/install.ps1 or ./install/install.sh, if an enabled MCP CLI is missing from PATH, the installer automatically runs its install command (from opencode.jsonc) to provision it.

2. Runtime Profiling & Routing (project-profiler plugin)

You don't need to manually tell agents which tool to call. The bundled project-profiler.ts plugin:

• Automatically detects project languages, active MCP servers, and local index status (.codegraph/, .gitnexus/).
• Injects guidance into the system prompt: mandates querying graph/LSP backends first rather than crawling files blindly.

3. Project Lifecycle Management (/project command)

Initialize and maintain project indexes effortlessly with /project:

/project init       # One-shot scaffolding: runs `codegraph init` and scaffolds `dbhub.toml`
                    # if respective MCPs and CLIs are ready
/project index      # Refreshes indexes: runs `codegraph sync` and `gitnexus analyze`

4. Database Setup Example (dbhub.toml)

Create a dbhub.toml in your project root (or let /project init scaffold it):

# dbhub.toml
[[sources]]
id = "default"
dsn = "${DBHUB_DSN}"   # Store DSN in environment variable (e.g. postgres://user:pass@localhost:5432/mydb)

[[tools]]
name = "execute_sql"
source = "default"
readonly = true        # Safety: enforce read-only execution