Implement serenamcp: Serena MCP server integration

[vredchenko]

Summary

The `serenamcp` plugin sets up and manages the Serena MCP server, which provides Claude Code with symbolic code analysis capabilities (go-to-definition, find-references, semantic search). This is valuable because MCP server configuration is manual and error-prone, and Serena needs project-specific setup for language servers.

Original Intent

Plugin to install and make use of Serena MCP for symbolic code search and navigation.

Commands

`/serenamcp:setup`

Purpose: Install and configure Serena MCP server for the current project.

Behavior:

1. Check if Serena is installed:
   ```bash
   uvx serena --version 2>/dev/null || pip show serena 2>/dev/null
   ```

   • If not installed → install: `uv tool install serena-mcp` (or `pip install serena-mcp`)

2. Detect project languages by scanning for:

   File	Language	Language Server
   `tsconfig.json`, `*.ts`	TypeScript	`typescript-language-server`
   `pyproject.toml`, `*.py`	Python	`pyright` or `pylsp`
   `go.mod`, `*.go`	Go	`gopls`
   `Cargo.toml`, `*.rs`	Rust	`rust-analyzer`
   `*.java`, `pom.xml`	Java	`jdtls`

3. Check if required language servers are installed:

   • TypeScript: `bun add -g typescript-language-server typescript`
   • Python: `uv tool install pyright`
   • Go: `go install golang.org/x/tools/gopls@latest`
   • Rust: comes with `rustup component add rust-analyzer`

4. Generate `.mcp.json` in project root:
   ```json
   {
   "mcpServers": {
   "serena": {
   "command": "uvx",
   "args": ["serena-mcp", "--workspace", "."],
   "env": {}
   }
   }
   }
   ```

5. Generate Serena config (`.serena/config.yml` or similar) if needed:
   ```yaml
   workspace: .
   languages:

   • typescript
   • python
     exclude:
   • node_modules
   • .venv
   • dist
     ```

6. Verify connection:

   • Start Serena in test mode
   • Try a simple operation (e.g., list symbols in a file)
   • Report success/failure

7. Add `.mcp.json` to `.gitignore` if it contains local paths

8. Output:
   ```
   Serena MCP Setup Complete

   Server: serena-mcp (via uvx)
   Languages: TypeScript, Python
   Workspace: /path/to/project

   Capabilities:
   ✓ Go to definition
   ✓ Find references
   ✓ Symbol search
   ✓ Hover information
   ✓ Diagnostics

   Config: .mcp.json (created)
   ```

Edge cases:

• Multiple language servers needed → configure all
• Existing `.mcp.json` with other servers → merge Serena config without disturbing others
• `uv` not available → fall back to `pip install`
• Serena version mismatch → suggest upgrade

`/serenamcp:status` (new)

Purpose: Check Serena MCP server health and capabilities.

Behavior:

1. Check if `.mcp.json` exists and has Serena configured

2. Check if Serena is installed and accessible

3. Check if language servers are running/available:
   ```
   Serena MCP Status

   Installation:
   ✓ serena-mcp 0.5.2 (via uvx)

   Configuration:
   ✓ .mcp.json found
   ✓ Workspace: /path/to/project

   Language Servers:
   ✓ typescript-language-server 4.3.3 — responding
   ✗ pyright — not found (install: uv tool install pyright)

   Capabilities:
   ✓ Go to definition
   ✓ Find references
   ✓ Symbol search
   ⚠ Diagnostics — requires language server restart
   ```

4. For each issue, provide the fix command

5. Offer to auto-fix what can be fixed

Edge cases:

• Serena installed but not configured → suggest running `/serenamcp:setup`
• Language server crashed → suggest restarting
• Wrong workspace path → offer to update `.mcp.json`

Hooks

None — MCP server management should be explicit, not automatic.

File Manifest

File	Est. Lines	Purpose
`commands/setup.md`	100-120	Install and configure Serena
`commands/status.md`	70-90	Health check and diagnostics
`README.md`	120-150	Full plugin documentation
`.claude-plugin/plugin.json`	15-20	Plugin manifest

README Outline

1. Overview — What Serena MCP provides: symbolic code intelligence for Claude Code
2. Quick Start — Installation + `/serenamcp:setup`
3. Commands — Table with both commands
4. Language Support — Table of supported languages and their language servers
5. Configuration — `.mcp.json` format and options
6. Capabilities — What symbolic analysis enables (go-to-def, find-refs, etc.)
7. Troubleshooting — Common issues (server not starting, language not detected, workspace wrong)
8. References — Links to Serena docs, MCP spec, language server protocol

Prerequisites

• `uv` or `pip` (for installing Serena)
• Language-specific servers (plugin will guide installation)

Quality Checklist

• Each command .md is 60+ lines with concrete steps
• README is 100+ lines with examples and reference tables
• Language server detection covers major languages
• `.mcp.json` generation is correct and complete
• Plugin provides clear value (automated MCP setup vs manual config)