add-serena

What this skill does

# Add Serena MCP to Any Project

This skill helps you add Serena MCP (Model Context Protocol) to any software project, providing IDE-like semantic code understanding and navigation capabilities with true multi-project support.

## What is Serena MCP?

Serena is a coding agent toolkit that provides:
- **Language Server Protocol (LSP)** integration for semantic code understanding
- **Symbol-level navigation** (find definitions, references, implementations)
- **Precise code editing tools** (insert after symbol, replace symbol body)
- **Project-aware search and file operations**
- **Memory system** for storing project-specific context
- **Onboarding and project structure analysis**

Supported languages: C#, Python, TypeScript, JavaScript, Go, Rust, Java, and more.

## Multi-Project Philosophy

**This skill enables you to add Serena to ANY project independently.**

Key principles:
- **Project-specific configuration** - Each project has its own `.mcp.json` and `.serena/` folder
- **Complete isolation** - Projects don't interfere with each other
- **Separate memory and state** - Each project maintains its own context
- **No global installation** - No hardcoded paths in `~/.claude.json`
- **Team-friendly** - Configuration can be version controlled for team sharing

**How it works:**
1. You add Serena to Project A → Works in Project A
2. You add Serena to Project B → Works in Project B
3. Both projects maintain separate Serena instances with isolated state
4. You can work on multiple projects without reconfiguration

## Prerequisites Check

Before adding Serena, verify:

### 1. uv (Python package manager) is installed

```bash
which uv
# Should return: /Users/nesbo/.local/bin/uv or similar
```

If not installed, see: https://github.com/astral-sh/uv

### 2. Python 3.11 is available

```bash
python3 --version
# Should show Python 3.11.x (Serena requires >=3.11, <3.12)
```

### 3. Language-specific requirements

- **C#:** Requires .sln file in project directory
- **Python:** Requires pyproject.toml or setup.py
- **TypeScript/JavaScript:** Requires tsconfig.json or package.json
- **Go:** Requires go.mod
- **Rust:** Requires Cargo.toml
- **Java:** Requires Maven or Gradle project file

### 4. Git repository (optional but recommended)

For .gitignore integration and version control benefits.

## Installation Approach Overview

**Per-Project Configuration with Helper Script**

This approach creates three main components in your project:

1. **`.mcp.json`** - Tells Claude Code to load Serena MCP server for this project
2. **`.serena/start-mcp.sh`** - Portable helper script that auto-detects project root
3. **`.serena/project.yml`** - Project-specific Serena configuration

**Benefits:**
- ✅ Each project is self-contained and independent
- ✅ Completely portable across team members
- ✅ No manual path configuration needed
- ✅ Can be version controlled for team consistency
- ✅ Works reliably regardless of where you start Claude Code

**Why helper script?**
- MCP servers can't reliably detect current working directory when launched via `uvx`
- Helper script ensures Serena always knows the correct project root
- More portable than hardcoded absolute paths

## Interactive Setup Guide

When using this skill, Claude Code will ask you several questions to customize the setup:

### Question 1: Programming Language

**"Which programming language is this project?"**

Options: C#, Python, TypeScript, JavaScript, Go, Rust, Java, Other

This determines:
- Language server configuration in `.serena/project.yml`
- Which project files to look for (.sln, pyproject.toml, etc.)
- LSP features available

### Question 2: Version Control

**"Should Serena configuration be version controlled and committed to git?"**

**Option A: Yes, commit for team (Recommended for team projects)**
- `.mcp.json`, `.serena/start-mcp.sh`, and `.serena/project.yml` are committed
- Entire team gets the same Serena setup
- No manual configuration per developer
- Best for: Team projects, shared codebases

**Option B: No, keep it local (Recommended for personal tooling)**
- Add Serena files to `.gitignore`
- Each developer configures independently
- Optional tooling, not required for the project
- Best for: Solo projects, experimental tools

### Question 3: Permissions

**"Should Serena tools be pre-approved?"**

**Option A: Yes, create settings.local.json with common tools**
- Pre-approves frequently used Serena tools
- Less interactive prompting during use
- Still safe - only Serena tools are pre-approved
- Best for: Frequent Serena users

**Option B: No, I'll approve interactively**
- Claude Code prompts for each tool use
- More explicit control
- More clicking required
- Best for: Security-conscious users, occasional use

## Installation Steps

### Step 1: Navigate to Your Project

```bash
cd /path/to/your/project
```

Ensure you're in the project root directory where you want to add Serena.

### Step 2: Use the add-serena Skill

In Claude Code, say:

```
Using the add-serena skill, add Serena MCP to my current project
```

or

```
@add-serena set up Serena for this project
```

Claude Code will then ask you the interactive questions (language, version control, permissions) and create all necessary files.

### Step 3: Files Created

The skill creates the following structure:

```
your-project/
├── .mcp.json                      # MCP server configuration
├── .serena/
│   ├── start-mcp.sh              # Helper script (auto-detects project root)
│   └── project.yml               # Serena project configuration
└── .claude/
    └── settings.local.json       # Permissions (if you chose pre-approval)
```

#### .mcp.json

```json
{
  "mcpServers": {
    "serena": {
      "command": "bash",
      "args": [".serena/start-mcp.sh"]
    }
  }
}
```

This tells Claude Code: "When running in this directory, start the Serena MCP server using the helper script."

#### .serena/start-mcp.sh

```bash
#!/bin/bash
PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$PROJECT_DIR"
```

This script:
- Auto-detects the project root directory
- Launches Serena with `uvx` (downloads and runs from GitHub)
- Passes the correct project path to Serena

#### .serena/project.yml

```yaml
language: csharp  # or python, typescript, etc. based on your answer
ignore_all_files_in_gitignore: true
ignored_paths: []
read_only: false
excluded_tools: []
initial_prompt: ""
project_name: "YourProjectName"
```

Configuration options:
- `language`: Programming language for LSP integration
- `ignore_all_files_in_gitignore`: Respect .gitignore patterns
- `ignored_paths`: Additional paths to ignore
- `read_only`: If true, disables editing tools
- `excluded_tools`: List of tools to disable
- `project_name`: Human-readable project identifier

#### .claude/settings.local.json (Optional)

```json
{
  "permissions": {
    "allow": [
      "mcp__serena__list_dir",
      "mcp__serena__find_file",
      "mcp__serena__get_symbols_overview",
      "mcp__serena__search_for_pattern",
      "mcp__serena__find_symbol",
      "mcp__serena__find_referencing_symbols",
      "mcp__serena__read_file",
      "mcp__serena__write_memory",
      "mcp__serena__read_memory",
      "mcp__serena__think_about_collected_information",
      "mcp__serena__onboard"
    ]
  }
}
```

Only created if you chose to pre-approve Serena tools.

### Step 4: Update .gitignore

The skill will update (or create) `.gitignore` based on your version control choice:

**If you chose to version control Serena config:**

```gitignore
# Serena cache and state (project-specific, don't commit)
.serena/.cache/
.serena/.state/
.serena/memories/
```

**If you chose NOT to version control:**

```gitignore
# Serena MCP configuration (personal preference, not committed)
.mcp.json
.serena/

# Claude Code personal settings
.claude/settings.local.json
```

### Step 5: Restart Claude Code

After the skill c