# RIG MCP Tools

A Model Context Protocol (MCP) server providing intelligent code analysis, graph-based architecture insights, and file operations for AI assistants.

## Overview

RIG MCP Tools combines three layers of intelligence:

- **Static analysis** — A Repository Intelligence Graph (RIG) built from AST parsing (ts-morph, tree-sitter) stored in SQLite, enabling graph queries with zero LLM cost.
- **Semantic search** — Embedding-based symbol retrieval using a local model (nomic-embed-text or compatible). Embeddings are cached in SQLite after the first run. Returns precise code snippets instead of whole files — minimizes token usage.
- **LLM-powered tools** — A subset of tools that call a configurable OpenAI-compatible API for natural language reasoning over code.

## Installation

### From npm

```bash
npx rig-mcp-tools
```

### From source

```bash
git clone <repository-url>
cd rig-mcp-tools
npm install
npm run build
```

### Docker

```bash
docker build -t rig-mcp-tools .
docker run rig-mcp-tools
```

## Configuration

### MCP client (Claude Desktop, Cursor, etc.)

```json
{
  "mcpServers": {
    "rig-tools": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "WORKSPACE_PATH": "/your/project",
        "GLM_API_URL": "http://localhost:1234/v1/chat/completions",
        "GLM_MODEL": "qwen2.5-coder-7b-instruct-mlx@8bit",
        "EMBEDDING_API_URL": "http://localhost:1234/v1/embeddings",
        "EMBEDDING_MODEL": "text-embedding-nomic-embed-text-v1.5"
      }
    }
  }
}
```

### Environment variables

| Variable | Default | Description |
|---|---|---|
| `WORKSPACE_PATH` | `/workspace` | Root workspace path |
| `GLM_API_URL` | `http://localhost:1234/v1/chat/completions` | LLM API endpoint (OpenAI-compatible) |
| `GLM_MODEL` | `qwen2.5-coder-7b-instruct-mlx@8bit` | Model for LLM-powered tools |
| `EMBEDDING_API_URL` | `http://localhost:1234/v1/embeddings` | Embeddings API endpoint |
| `EMBEDDING_MODEL` | `text-embedding-nomic-embed-text-v1.5` | Model for semantic search |

LLM and embedding tools are optional — all static analysis tools work without any API.

## Available Tools

### RIG — Graph Analysis

These tools index the repository into a SQLite graph via AST parsing and query it without calling any LLM.

#### `get_smart_context`
Retrieve the most relevant files and symbols for a query using graph centrality and keyword scoring.

```json
{ "rootPath": "/project", "text": "authentication flow" }
```

#### `get_architectural_metrics`
Executive summary of repository architecture: core hubs, entry points, and stable foundations ranked by graph centrality.

```json
{ "rootPath": "/project" }
```

#### `graph_analyzer`
Component-level complexity analysis with hotspot detection and refactor recommendations.

```json
{ "rootPath": "/project" }
```

#### `generate_call_graph`
Generate call graphs or dependency diagrams between components, files, or symbols.

```json
{
  "rootPath": "/project",
  "level": "component",
  "format": "mermaid",
  "maxDepth": 5
}
```

`level`: `"component"` | `"file"` | `"symbol"`  
`format`: `"mermaid"` | `"dot"` | `"json"`

#### `generate_diagram`
Generate C4 architecture diagrams, sequence diagrams, call graphs, or dependency visualizations from the RIG.

```json
{
  "rootPath": "/project",
  "type": "c4-container",
  "format": "mermaid",
  "focus": "auth",
  "maxDepth": 3,
  "style": "default"
}
```

`type`: `"c4-context"` | `"c4-container"` | `"c4-component"` | `"sequence"` | `"call-graph"` | `"dependency-graph"`  
`format`: `"mermaid"` | `"plantuml"` | `"dot"`  
`style`: `"default"` | `"compact"` | `"detailed"`

#### `extract_method`
Surgically extract a function or class from a source file to a target file using RIG symbol coordinates.

```json
{
  "rootPath": "/project",
  "sourceFile": "src/utils/helpers.ts",
  "symbolName": "formatDate",
  "targetFile": "src/utils/date.ts"
}
```

---

### File Operations

Pure filesystem tools, no graph or LLM required.

#### `read_files`
Read content of up to 10 files in a single call.

```json
{ "files": ["src/index.ts", "src/config.ts"] }
```

#### `write_code_unit`
Write or overwrite a file with specific content. Creates parent directories as needed.

```json
{ "path": "src/utils/new-file.ts", "content": "export const foo = 1;" }
```

#### `ls_tree`
List directory structure as an ASCII tree.

```json
{ "path": "/project/src", "maxDepth": 3 }
```

#### `search_code`
Search text or regex patterns recursively across the codebase.

```json
{ "path": "/project/src", "pattern": "useEffect", "useRegex": false }
```

#### `inspect_symbols`
Extract class and function signatures from a file using AST analysis (ts-morph).

```json
{ "file": "src/tools/index.ts" }
```

#### `run_shell_task`
Execute allowed shell commands.

```json
{ "command": "npm run build", "timeout": 60000 }
```

Allowed prefixes: `npm test`, `npm run`, `npm list`, `npx vitest`, `npx tsc`, `npx eslint`, `node --version`, `tsc`, `git status`, `git diff`, `git log`, `git show`, `git blame`, `ls`, `pwd`, `cat`, `wc`.

---

### Quality Analysis

Static analysis tools, no LLM required.

#### `detect_patterns`
Detect anti-patterns, code smells, and security issues using Babel AST analysis.

```json
{ "sourceCode": "...", "filePath": "src/auth/login.ts" }
```

#### `suggest_refactor`
Detect refactoring opportunities: long functions, deep nesting, magic numbers, duplicate code, and missing type annotations.

```json
{
  "file_path": "src/services/user.ts",
  "max_suggestions": 10,
  "min_priority": 3,
  "include_diff": true
}
```

Either `file_path` or `code_snippet` must be provided.

#### `analyze_dependencies`
Build a lightweight dependency graph of TypeScript files via import analysis. Returns nodes, circular dependencies, and DOT format for Graphviz.

```json
{ "rootPath": "/project/src" }
```

---

### Embedding-Powered

Requires `EMBEDDING_API_URL` and `EMBEDDING_MODEL`. Embeddings are generated once per symbol and cached in `.rig/index.db` — subsequent queries only embed the query string.

#### `search_semantic`
Semantic symbol search using vector similarity. Returns the most relevant functions and classes with their code snippets. **Use this before `read_files`** to avoid loading entire files into context. Embeddings are generated once per symbol and cached in `.rig/index.db`.

```json
{
  "repoPath": "/project",
  "query": "how is authentication handled",
  "maxResults": 5,
  "threshold": 0.3
}
```

---

### LLM-Powered

Requires `GLM_API_URL` and `GLM_MODEL`.

#### `analyze_logic`
Ask a natural language question about a piece of code. Uses the configured LLM to reason about behavior, intent, or logic.

```json
{
  "filePath": "/project/src/auth/login.ts",
  "question": "What edge cases does this miss?"
}
```

Prefer `filePath` over `code` to avoid passing file contents through context.

#### `smart_summarize`
Generate an intelligent summary of a code file including imports, exports, purpose, and key dependencies.

```json
{ "filePath": "/project/src/services/user.ts", "maxLength": 200 }
```

#### `generate_unit_tests`
Generate vitest unit tests for a specific function or class. Uses the RIG index to extract only the method body (not the whole file) — token-efficient. Covers happy path, edge cases, and error cases.

```json
{
  "repoPath": "/project",
  "symbolName": "createUser",
  "filePath": "src/services/user.ts"
}
```

`filePath` is required only if the symbol exists in multiple files.

#### `investigate_ts_fix`
Run `tsc --noEmit` and use the LLM to explain and suggest minimal fixes for each TypeScript error. Token-efficient: only passes the snippet around the error line (±8 lines), not the whole file.

```json
{
  "repoPath": "/project",
  "filePath": "src/services/user.ts",
  "maxErrors": 5
}
```

`filePath` and `maxErrors` are optional. Omit `filePath` to investigate all errors across the repo.

---

## Architecture

```
src/
├── cli/           # rig-indexer CLI (pre-index a repo into .rig/index.db)
├── graph/         # RIG graph engine (indexer, parsers, SQLite storage, types)
├── security/      # Path validation and safe extension checks
└── tools/         # MCP tool implementations (19 tools)
```

### Pre-indexing a repository

For large codebases, pre-index before using RIG tools:

```bash
npx tsx src/cli/index.ts /path/to/project --db /path/to/project/.rig/index.db
```

Options: `--max-files <n>`, `--include-tests`, `--json`

## Development

```bash
npm run build   # Compile TypeScript
npm run dev     # Run in development mode
npm test        # Run test suite
npm run clean   # Clean build artifacts
```

## License

MIT