# Code Analysis

> >

- **Type:** Skill
- **Install:** `agentstack add skill-bug-ops-zeph-code-analysis`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bug-ops](https://agentstack.voostack.com/s/bug-ops)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bug-ops](https://github.com/bug-ops)
- **Source:** https://github.com/bug-ops/zeph/tree/main/.zeph/skills/code-analysis
- **Website:** https://bug-ops.github.io/zeph/

## Install

```sh
agentstack add skill-bug-ops-zeph-code-analysis
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Code Analysis with LSP

Use LSP tools for accurate, compiler-verified code understanding. These tools require the `mcpls`
MCP server to be configured.

## Positions

Positions are **1-based**: line 1, column 1 is the first character. If you read a file and see
line numbers in the output, use those directly — no conversion needed (mcpls translates to 0-based
LSP positions internally).

File paths must be absolute. Relative paths will not resolve correctly.

## Tool Reference

### Code Intelligence

| Tool | Purpose | When to use |
|---|---|---|
| `get_hover` | Type signature, inferred type, and documentation at a position | "What type is X?", "What does this function do?" |
| `get_definition` | Navigate to where a symbol is defined | Read a function/type implementation before reasoning about it |
| `get_references` | Find all usages of a symbol across the workspace | Before renaming, deleting, or changing a symbol's signature |
| `get_completions` | Context-aware suggestions respecting types and scope | Exploring unknown APIs, discovering available methods |
| `get_document_symbols` | Structured outline of a file (functions, types, constants, fields) | Understanding file structure without reading every line |
| `workspace_symbol_search` | Search for a symbol by name across the entire workspace | Know a name but not which file defines it |

### Diagnostics and Correctness

| Tool | Purpose | When to use |
|---|---|---|
| `get_diagnostics` | Real compiler errors and warnings for a file | After editing code — always call to verify correctness |
| `get_cached_diagnostics` | Previously cached diagnostics (no fresh check) | Quick check when file has not changed recently |
| `get_code_actions` | Quick fixes, refactorings, source actions at a position | Fix diagnostics automatically, add missing imports |

### Refactoring

| Tool | Purpose | When to use |
|---|---|---|
| `rename_symbol` | Workspace-wide rename with full reference tracking | Always prefer over manual find-and-replace |
| `format_document` | Apply language-specific formatting rules | After editing, before committing |

### Call Hierarchy

| Tool | Purpose | When to use |
|---|---|---|
| `prepare_call_hierarchy` | Get callable items at a position | First step before incoming/outgoing calls |
| `get_incoming_calls` | Find all callers of a function | "Who calls this?" — impact analysis |
| `get_outgoing_calls` | Find all callees of a function | "What does this call?" — dependency analysis |

### Server Monitoring

| Tool | Purpose | When to use |
|---|---|---|
| `get_server_logs` | Internal log messages from the language server | Debug "no results" issues, server startup failures |
| `get_server_messages` | User-facing messages from the language server | Check for server notifications, progress, errors |

## Workflow Patterns

### Diagnostic-Driven Editing

After editing a file:

1. Save the file to disk (diagnostics reflect the file on disk, not in-memory).
2. Call `get_diagnostics` on the changed file.
3. For each error, call `get_code_actions` to find available fixes.
4. Apply fixes or edit manually.
5. Repeat until `get_diagnostics` returns an empty list.

### Impact Analysis Before Refactoring

1. Call `get_references` on the symbol you intend to change.
2. Review all usage sites to understand the blast radius.
3. Make the change (or use `rename_symbol` for renames).
4. Call `get_diagnostics` on all affected files.

### Type Exploration

1. Call `get_hover` on an unknown symbol to see its type and documentation.
2. Call `get_definition` to read the implementation.
3. Call `get_references` to understand how other code uses it.

### Call Graph Analysis

1. Call `prepare_call_hierarchy` on a function — this returns a call hierarchy item.
2. Pass the item to `get_incoming_calls` to see what calls it (consumers).
3. Pass the item to `get_outgoing_calls` to see what it calls (dependencies).
4. Repeat recursively to trace deeper call chains.

### Workspace Navigation

1. Call `workspace_symbol_search` with a partial name to find symbols across the project.
2. Call `get_definition` on the result to jump to the source.
3. Call `get_document_symbols` on the target file to understand its full structure.

## Configuration

mcpls auto-detects language servers based on project markers:

| Language | Server | Markers |
|---|---|---|
| Rust | rust-analyzer | `Cargo.toml`, `rust-toolchain.toml` |
| Python | pyright | `pyproject.toml`, `setup.py`, `requirements.txt` |
| TypeScript | typescript-language-server | `package.json`, `tsconfig.json` |
| Go | gopls | `go.mod`, `go.sum` |
| C/C++ | clangd | `CMakeLists.txt`, `compile_commands.json`, `Makefile` |
| Zig | zls | `build.zig`, `build.zig.zon` |

Custom servers can be added in `~/.config/mcpls/mcpls.toml`:

```toml
[[lsp_servers]]
language_id = "rust"
command = "rust-analyzer"
args = []
file_patterns = ["*.rs"]
timeout_seconds = 30

[lsp_servers.initialization_options]
check.command = "clippy"
```

Environment variables:

| Variable | Description | Default |
|---|---|---|
| `MCPLS_CONFIG` | Path to config file | `~/.config/mcpls/mcpls.toml` |
| `MCPLS_LOG` | Log level (trace/debug/info/warn/error) | `info` |
| `MCPLS_LOG_JSON` | Output logs as JSON | `false` |

## Troubleshooting

### No results from get_hover or get_definition

1. The file may not be indexed yet. mcpls opens files lazily — the first access to a file
   triggers indexing, which may take a few seconds for large projects.
2. Call `get_server_logs` to check if the language server is running and has finished indexing.
3. Verify the language server is installed and in `$PATH` (e.g., `which rust-analyzer`).
4. Check that the project has the expected marker files (e.g., `Cargo.toml` for Rust).

### get_diagnostics returns stale results

- Diagnostics reflect the file **on disk**. If you edited the file but did not save, the
  diagnostics will be for the old content. Always save before calling `get_diagnostics`.
- After a save, the language server needs time to re-analyze. Wait briefly and retry.
- Use `get_cached_diagnostics` only when you know the file has not changed — it returns
  push-based diagnostics from the server's last notification, which may be outdated.

### Language server not starting

1. Check `get_server_logs` for startup errors.
2. Verify the server binary is installed: `which rust-analyzer`, `which pyright`, etc.
3. Check the config file (`~/.config/mcpls/mcpls.toml`) for misconfigured `command` or `args`.
4. Ensure the project root contains the expected marker files for auto-detection.
5. For non-standard setups, add an explicit `[[lsp_servers]]` entry in the config.

### Slow responses

- Initial indexing can take 10-30 seconds for large Rust workspaces. Subsequent calls are fast.
- Set `timeout_seconds` higher in the config for large projects.
- Check `get_server_logs` for memory or CPU warnings from the language server.
- For rust-analyzer, ensure `rust-analyzer.cargo.buildScripts.enable` is not causing excessive
  build script evaluation.

### rename_symbol fails or misses references

- `rename_symbol` only works on symbols the language server can resolve. If a symbol is in a
  macro expansion or generated code, the rename may be partial.
- Always call `get_references` first to verify the server can see all usage sites.
- After rename, call `get_diagnostics` on affected files to catch any breakage.

## Edge Cases

- **Macro-generated code**: `get_hover` and `get_definition` may not resolve symbols inside
  procedural macro expansions. Use `get_references` on the macro invocation site instead.
- **Conditional compilation**: Symbols behind `#[cfg(...)]` may not be visible depending on the
  active feature set. Configure the language server's feature flags accordingly.
- **Multi-root workspaces**: mcpls supports multiple roots via the `roots` config option. Each
  root gets its own language server instance.
- **Large files**: `get_document_symbols` on very large files (10k+ lines) may be slow. Prefer
  targeted `get_hover` or `workspace_symbol_search` instead.
- **Cross-crate navigation**: `get_definition` may jump into dependency source code
  (e.g., `~/.cargo/registry/`). This is expected behavior — the language server resolves through
  the full dependency graph.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bug-ops](https://github.com/bug-ops)
- **Source:** [bug-ops/zeph](https://github.com/bug-ops/zeph)
- **License:** MIT
- **Homepage:** https://bug-ops.github.io/zeph/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bug-ops-zeph-code-analysis
- Seller: https://agentstack.voostack.com/s/bug-ops
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.