title: "[Feature Request] Integrate Serena for Semantic Code Understanding"
labels: ["enhancement", "mcp", "semantic-search"]

Feature Request: Integrate Serena for Semantic Code Understanding

Summary

Add support for Serena - a powerful coding agent toolkit providing semantic code retrieval and editing capabilities via Language Server Protocol (LSP).

Background

Currently, OpenCode has excellent file-level search capabilities but lacks semantic code understanding. When I ask questions like:

• "Find all usages of this function"
• "Go to definition of this symbol"
• "Show me the class hierarchy"
• "Where is error handling for API calls?"

These require understanding code structure and relationships, not just text matching.

Serena provides IDE-like semantic capabilities:

• Symbol-level code understanding via LSP
• Find references across codebase
• Go to definition/declaration
• Precise code edits at symbol level
• Cross-language support

Why Serena?

1. MCP Compatible: Serena works as MCP server - OpenCode already supports MCP
2. Actively Maintained: 16.1K+ stars, active development
3. Proven Technology: Used in production by teams building AI coding agents
4. Token Efficient: Semantic retrieval reduces context needed vs grep/text search
5. Framework Agnostic: Not tied to specific LLMs

Proposed Implementation

Option 1: MCP Server Integration (Recommended)

Add Serena as built-in MCP server in OpenCode:

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "serena": {
      "type": "local",
      "command": "serena",
      "args": ["mcp"],
      "enabled": true
    }
  }
}

Benefits:

• Users can enable/disable in config
• Leverages existing MCP infrastructure
• No breaking changes

Option 2: Direct Tool Integration

Add Serena as first-class OpenCode tool (similar to existing grep/ripgrep tools):

{
  name: "serena_find_symbols",
  description: "Find symbols and references using Serena LSP",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string" },
      language: { type: "string" }
    }
  }
}

Option 3: Auto-Detection

Automatically detect and integrate Serena when:

1. serena binary is in PATH
2. serena MCP server is available
3. Serena config exists in project

Use Cases

1. Semantic Code Search

User prompt: "Find all functions that handle user authentication"

Current behavior: Uses grep/ripgrep - matches text "authentication"
With Serena: Returns functions authenticateUser(), login(), verifyCredentials() with file locations and line numbers

2. Go to Definition

User prompt: "Show me the User schema definition"

Current behavior: Searches files for "User" and "schema"
With Serena: Jumps directly to User class/interface definition with import tree

3. Find References

User prompt: "Where is PaymentProcessor used?"

Current behavior: Text search for "PaymentProcessor"
With Serena: Returns list of all usages with context (imports, instantiations, method calls)

4. Cross-File Refactoring

User prompt: "Rename UserService to AccountService across all files"

Current behavior: Text search and replace (error-prone)
With Serena: Semantic rename across LSP-aware files (safely)

Technical Details

Serena Capabilities

From Serena README:

• Symbol search and navigation
• Cross-reference finding
• Semantic code retrieval
• Multi-language support (TypeScript, Python, Go, etc.)
• LSP-based editing primitives

Integration Effort

• MCP Path: Low (2-3 hours) - Serena has MCP support
• Direct Path: Medium (1-2 days) - Needs tool registration
• Auto-Detection: Medium (1 day) - Add detection logic

Alternatives Considered

1. Keep using grep/ripgrep: Fast, but no semantic understanding
2. Build custom LSP client: Higher effort, maintenance burden
3. Use existing MCP servers: See below (directory-indexer, Codebase)

Related Issues

• Split off MCP configuration: Split off MCP server configuration from config.json #1998
• MCP server documentation: docs/mcp-servers

References

• Serena repo: https://github.com/oraios/serena
• Serena MCP integration: MCP server mode
• OpenCode MCP docs: https://opencode.ai/docs/mcp-servers/

Acceptance Criteria

• Serena can be added as MCP server in opencode.json
• OpenCode can call Serena tools (symbol search, go-to-definition)
• Documentation updated with Serena examples
• User feedback from beta testing
• Performance impact evaluated (should be minimal)

Questions for Maintainers

1. Do you prefer MCP server integration or direct tool integration?
2. Should Serena be opt-in or auto-detected?
3. Are there concerns about adding another MCP server (token usage)?

Open these issues to discuss approach and implementation details!