Metadata-Version: 2.4
Name: dominian
Version: 1.0.6
Summary: Dominian Code Intelligence — CLI tool and MCP server for scanning, querying, and analyzing codebases
Author-email: Dominian Team <team@dominian.dev>
Maintainer-email: Dominian Team <team@dominian.dev>
License: MIT
Keywords: code-intelligence,dependency-analysis,codebase-scanner,llm-tools,mcp-server,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Code Generators
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Provides-Extra: community
Requires-Dist: networkx>=3.0; extra == "community"
Requires-Dist: python-louvain>=0.16; extra == "community"
Provides-Extra: tree-sitter
Requires-Dist: tree-sitter>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-python>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-javascript>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-typescript>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-java>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-go>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-rust>=0.20.0; extra == "tree-sitter"
Provides-Extra: all
Requires-Dist: dominian[community,tree-sitter]; extra == "all"
Dynamic: requires-python

# Dominian MCP Server

**Model Context Protocol server for Dominian Code Intelligence v3.0.7**

Scan codebases, query dependency graphs, detect cycles, find hotspots, analyze impact, and assess refactoring safety — all through the MCP protocol with minimal-format output optimized for LLM token efficiency.

---

## Overview

Dominian builds a graph database of your codebase where nodes are code entities (functions, classes, modules) and edges are relationships (imports, calls, uses, defines). The MCP server exposes this graph intelligence as tools that AI agents can invoke directly.

**Output format**: All tools return **minimal format** — ultra-compact strings designed for LLM consumption with ~85% token reduction versus verbose output while retaining 100% information content.

### Minimal Format Reference

| Symbol | Meaning |
|--------|---------|
| `✓` | Success |
| `ERR:` | Error with message |
| `🔥` | Hotspot |
| `🔄` | Cycles detected |
| `✅` | No issues / Safe |
| `📥` | Dependencies (outgoing) |
| `📤` | Dependents (incoming) |
| `⚠️` | Impact / Risk |
| `🚫` | Unsafe to refactor |
| `📍` | Node details |
| `📄` | File-level info |
| `🔗` | Cross-community edges |
| `📦` | Communities |

**Locator format**: `folder/file:name:line(type)` — the universal reference for any code entity.

**Type abbreviations**: `fn`=function/method, `cls`=class, `mod`=module, `var`=variable, `imp`=import, `dep`=dependency

---

## Installation

### Quick Install

```bash
cd dominian-mcp
pip install -e .
```

### Manual Install

```bash
pip install mcp
# Then ensure Dominian source files are in the same directory as server.py:
# database.py, formatter.py, adaptive_scanner.py, engine.py, tree_sitter_parser.py
# Plus their dependencies: tree_sitter_configs, ast_walker, __init__.py
```

### Dependencies

```
mcp>=1.0.0
# Dominian dependencies (must be in DOMINIAN_SRC path):
#   database.py, formatter.py, adaptive_scanner.py, engine.py
# Optional for community detection:
#   networkx, python-louvain
# Optional for tree-sitter parsing:
#   tree-sitter, tree-sitter-python, tree-sitter-javascript, etc.
```

---

## Configuration

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Cursor, VS Code):

**Stdio transport** (recommended for local use):

```json
{
  "mcpServers": {
    "dominian": {
      "command": "python",
      "args": ["/path/to/dominian-mcp/server.py"],
      "env": {
        "DOMINIAN_DB": "/path/to/project/.dominian/agentgraph.db",
        "DOMINIAN_ROOT": "/path/to/project",
        "DOMINIAN_SRC": "/path/to/dominian-source-files"
      }
    }
  }
}
```

**SSE transport** (for remote/server deployment):

```bash
python server.py --transport sse --host 0.0.0.0 --port 8080
```

```json
{
  "mcpServers": {
    "dominian": {
      "url": "http://localhost:8080/sse"
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DOMINIAN_DB` | `.dominian/agentgraph.db` | Path to the SQLite database |
| `DOMINIAN_ROOT` | Current working directory | Project root for scanning |
| `DOMINIAN_SRC` | Directory of `server.py` | Path to Dominian Python source files |

---

## Tools Reference

### Project Lifecycle

#### `dominian_init`

Initialize a new Dominian project and create the database.

```python
dominian_init(db_path=None)
```

**Returns**: `✓ init <dir> db:<path>`

**Example output**: `✓ init .dominian db:.dominian/agentgraph.db`

---

#### `dominian_scan`

Scan a codebase directory and populate the graph database.

```python
dominian_scan(path=None, db_path=None, mode="auto", workers=4)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `path` | string | CWD | Root directory to scan |
| `db_path` | string | `DOMINIAN_DB` | Database path |
| `mode` | string | `"auto"` | Scan strategy: auto/sequential/threaded/process |
| `workers` | int | 4 | Parallel workers for threaded/process modes |

**Returns**: `✓ scan <files>f <nodes>n <edges>e <duration>s mode:<mode>`

**Example output**: `✓ scan 142f 891n 2340e 3.2s mode:threaded`

**Adaptive strategy**:
- <50 files → sequential (no overhead)
- 50-500 files → multi-threaded (4-8 workers)
- 500+ files → multi-process (bypasses GIL)

---

### Search & Lookup

#### `dominian_search`

Search for code entities by name, file, or signature.

```python
dominian_search(query, db_path=None)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | **Required**. Search term |
| `db_path` | string | Database path |

**Returns**: `🔍 ref1 | ref2 | ref3` or `🔍 0`

**Example output**: `🔍 src/engine.py:query:15(fn) | src/db.py:search_nodes:369(fn)`

---

#### `dominian_node_get`

Get detailed information about a specific code entity.

```python
dominian_node_get(entity, db_path=None)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `entity` | string | **Required**. Function, class, or module name |
| `db_path` | string | Database path |

**Returns**: `📍 file:name:start-end type c:complexity q:quality deps:count used_by:count`

**Example output**: `📍 src/engine.py:query:14-29 fn c:5 q:92.1 deps:3 used_by:7`

---

### Dependency Analysis

#### `dominian_deps_direct`

Show what a code entity depends on (outgoing edges).

```python
dominian_deps_direct(entity, db_path=None)
```

**Returns**: `📥 entity→ dep1_ref | dep2_ref` or `📥 entity:0`

**Example output**: `📥 query→ src/db.py:get_node:316(fn) imports | src/db.py:search_nodes:369(fn) calls`

---

#### `dominian_deps_reverse`

Show what depends on a code entity (incoming edges).

```python
dominian_deps_reverse(entity, db_path=None)
```

**Returns**: `📤 entity← user1_ref | user2_ref` or `📤 entity:0`

**Example output**: `📤 query← src/cli.py:cmd_search:110(fn) calls | src/api.py:handle_query:45(fn) calls`

---

### Architecture Analysis

#### `dominian_arch_impact`

Analyze the blast radius of changing a code entity.

```python
dominian_arch_impact(entity, db_path=None, depth=10)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `entity` | string | — | **Required**. Entity name |
| `db_path` | string | — | Database path |
| `depth` | int | 10 | Max traversal depth |

**Returns**: `⚠️ RISK_LEVEL count:affected1,affected2,...`

**Risk levels**: LOW (0-2), MEDIUM (3-5), HIGH (6-10), CRITICAL (10+)

**Example output**: `⚠️ HIGH 7:src/api.py:handle:45,src/cli.py:cmd:110,src/test.py:test_handle:5`

---

#### `dominian_arch_communities`

Detect code communities using Louvain modularity.

```python
dominian_arch_communities(db_path=None)
```

**Returns**: `[count] [size1,size2,...] avg:average_size`

**Example output**: `[4] [12,8,5,3] avg:7`

---

#### `dominian_arch_cross_community`

Find dependency edges that cross community boundaries.

```python
dominian_arch_cross_community(db_path=None)
```

**Returns**: `🔗 from_ref→to_ref | from_ref→to_ref`

**Example output**: `🔗 src/api.py:User→src/db.py:connect | src/auth.py:login→src/db.py:query`

---

### Graph Analysis

#### `dominian_graph_stats`

Get graph database statistics.

```python
dominian_graph_stats(db_path=None)
```

**Returns**: `✓ <nodes>n <edges>e q:<quality> <top_language>`

**Example output**: `✓ 891n 2340e q:85.3 Python`

---

#### `dominian_graph_hotspots`

Find complexity hotspots — the most problematic code entities.

```python
dominian_graph_hotspots(limit=10, db_path=None)
```

**Returns**: `🔥 ref1 c:complexity q:quality | ref2 c:complexity q:quality`

**Example output**: `🔥 src/engine.py:query:14(fn) c:15 q:42.3 | src/db.py:get_impact:572(fn) c:12 q:55.1`

---

#### `dominian_graph_cycles`

Detect circular dependencies.

```python
dominian_graph_cycles(db_path=None)
```

**Returns**: `🔄 count:cycle1,cycle2,...` or `✅ 0 cycles`

**Example output**: `🔄 2:A→B→C→A,D→E→D`

---

### Refactoring Support

#### `dominian_refactor_safe`

Check if an entity is safe to refactor.

```python
dominian_refactor_safe(entity, db_path=None)
```

**Returns**: `✅ SAFE entity` or `🚫 entity direct_count total_count dependent_refs`

**Example output**:
- Safe: `✅ SAFE format_minimal`
- Unsafe: `🚫 GraphDatabase 3direct 5total src/cli.py:cmd_search:110,src/api.py:handle:45`

---

#### `dominian_refactor_impact`

Analyze refactoring impact (alias for `dominian_arch_impact`).

```python
dominian_refactor_impact(entity, db_path=None)
```

Same return format as `dominian_arch_impact`.

---

### File-Level Analysis

#### `dominian_file_functions`

List all functions and methods in a file.

```python
dominian_file_functions(file, db_path=None)
```

**Returns**: `📄 file count:fn name1,name2,...`

**Example output**: `📄 src/engine.py 8fn: query,_detect_intent,_resolve,_resolve_dependencies,_resolve_dependents`

---

#### `dominian_file_classes`

List all classes in a file.

```python
dominian_file_classes(file, db_path=None)
```

**Returns**: `📄 file count:cls name1,name2,...`

**Example output**: `📄 src/database.py 1cls: GraphDatabase`

---

### Advanced Queries

#### `dominian_nodes_by_type`

Get all code entities of a specific type.

```python
dominian_nodes_by_type(type, limit=25, db_path=None)
```

**Valid types**: `function`, `method`, `class`, `module`, `variable`, `import`, `dependency`

---

#### `dominian_nodes_by_quality`

Find low-quality or high-quality code entities.

```python
dominian_nodes_by_quality(quality="low", limit=15, db_path=None)
```

- `quality="low"` → nodes with quality < 70 (refactoring candidates)
- `quality="high"` → nodes with quality >= 70

---

#### `dominian_god_nodes`

Find highly-connected God Object nodes.

```python
dominian_god_nodes(limit=10, db_path=None)
```

Returns nodes with the highest total degree (in + out connections).

---

#### `dominian_orphans`

Find code entities with no connections at all.

```python
dominian_orphans(db_path=None)
```

Potential dead code or unused utilities.

---

#### `dominian_surprising_connections`

Find hidden cross-directory coupling.

```python
dominian_surprising_connections(db_path=None)
```

Returns edges between nodes in different top-level directories (excluding imports/defines).

---

#### `dominian_info`

Get project status and statistics.

```python
dominian_info(db_path=None)
```

---

## Resources

The server exposes two MCP resources for read-only access:

| Resource URI | Description |
|-------------|-------------|
| `dominian://status` | Current project status with stats |
| `dominian://schema` | Database schema and edge/node type reference |

---

## Prompts

The server provides three reusable prompt templates:

### `code_review`

Generate a structured code review for a specific entity.

```
code_review(entity="GraphDatabase")
```

Invokes: `node_get` → `deps_direct` → `deps_reverse` → `refactor_safe` → `arch_impact`

### `architecture_review`

Generate a comprehensive architecture review for the entire codebase.

```
architecture_review()
```

Invokes: `graph_stats` → `graph_hotspots` → `graph_cycles` → `arch_communities` → `arch_cross_community` → `god_nodes` → `orphans` → `surprising_connections`

### `refactor_plan`

Create a detailed refactoring plan for a specific entity.

```
refactor_plan(entity="process_request")
```

Invokes: `refactor_safe` → `arch_impact` → `deps_direct` → `deps_reverse` → `node_get`

---

## Workflow Guide for Agents

### Typical First-Time Setup

```
1. dominian_init()           # Create the database
2. dominian_scan(path=".")   # Scan the codebase
3. dominian_graph_stats()    # Verify scan results
```

### Understanding a Specific Entity

```
1. dominian_search(query="EntityName")     # Find it first
2. dominian_node_get(entity="EntityName")  # Get details
3. dominian_deps_direct(entity="EntityName")   # What it uses
4. dominian_deps_reverse(entity="EntityName")  # What uses it
```

### Assessing Change Risk

```
1. dominian_refactor_safe(entity="EntityName")   # Quick safety check
2. dominian_arch_impact(entity="EntityName")     # Full blast radius
3. dominian_graph_cycles()                        # Any cycles involved?
```

### Architecture Health Check

```
1. dominian_graph_stats()                # Overall numbers
2. dominian_graph_hotspots(limit=15)     # Problem areas
3. dominian_graph_cycles()               # Circular deps
4. dominian_arch_communities()           # Module structure
5. dominian_arch_cross_community()       # Boundary violations
6. dominian_god_nodes()                  # Over-connected entities
7. dominian_orphans()                    # Dead code candidates
```

### Finding Refactoring Targets

```
1. dominian_nodes_by_quality(quality="low", limit=20)  # Low quality code
2. dominian_graph_hotspots(limit=15)                     # Complex code
3. dominian_god_nodes()                                  # Too many responsibilities
4. dominian_orphans()                                    # Dead code
```

---

## CLI Command ↔ MCP Tool Mapping

| CLI Command | MCP Tool |
|-------------|----------|
| `dominian init` | `dominian_init` |
| `dominian scan <path>` | `dominian_scan` |
| `dominian search <query>` | `dominian_search` |
| `dominian node get <entity>` | `dominian_node_get` |
| `dominian node show <entity>` | `dominian_node_get` |
| `dominian deps direct <entity>` | `dominian_deps_direct` |
| `dominian deps reverse <entity>` | `dominian_deps_reverse` |
| `dominian arch impact <entity>` | `dominian_arch_impact` |
| `dominian arch communities` | `dominian_arch_communities` |
| `dominian arch cross-community` | `dominian_arch_cross_community` |
| `dominian graph stats` | `dominian_graph_stats` |
| `dominian graph hotspots` | `dominian_graph_hotspots` |
| `dominian graph cycles` | `dominian_graph_cycles` |
| `dominian graph circular` | `dominian_graph_cycles` |
| `dominian refactor safe <entity>` | `dominian_refactor_safe` |
| `dominian refactor safety <entity>` | `dominian_refactor_safe` |
| `dominian refactor impact <entity>` | `dominian_refactor_impact` |
| `dominian file functions <file>` | `dominian_file_functions` |
| `dominian file classes <file>` | `dominian_file_classes` |
| `dominian info` | `dominian_info` |

---

## Architecture

```
┌─────────────────────────────────────────────┐
│              MCP Client                      │
│  (Claude Desktop, Cursor, VS Code, etc.)    │
└──────────────┬──────────────────────────────┘
               │ MCP Protocol (stdio/SSE)
               ▼
┌─────────────────────────────────────────────┐
│          Dominian MCP Server (server.py)     │
│                                              │
│  ┌─────────┐ ┌──────────┐ ┌──────────────┐ │
│  │  Tools   │ │ Resources│ │   Prompts    │ │
│  │ (20+)    │ │ (2)      │ │ (3)          │ │
│  └────┬─────┘ └────┬─────┘ └──────┬───────┘ │
│       │            │               │         │
│       ▼            ▼               ▼         │
│  ┌─────────────────────────────────────┐     │
│  │         formatter.py (minimal)       │     │
│  └─────────────────┬───────────────────┘     │
│                    │                          │
│  ┌─────────────────▼───────────────────┐     │
│  │         database.py (GraphDB)        │     │
│  └─────────────────┬───────────────────┘     │
│                    │                          │
│  ┌─────────────────▼───────────────────┐     │
│  │     SQLite (.dominian/agentgraph.db) │     │
│  └─────────────────────────────────────┘     │
│                                              │
│  ┌─────────────────────────────────────┐     │
│  │  adaptive_scanner.py (on scan)       │     │
│  │  └── tree_sitter_parser.py           │     │
│  │  └── engine.py (QueryEngine)         │     │
│  └─────────────────────────────────────┘     │
└──────────────────────────────────────────────┘
```

---

## Error Handling

All errors return strings prefixed with `ERR:` so agents can detect failures:

| Error | Cause | Resolution |
|-------|-------|------------|
| `ERR:not found: <entity>` | Entity doesn't exist in database | Run `dominian_scan` or check spelling |
| `ERR:query required` | Empty search query | Provide a non-empty query string |
| `ERR:entity name required` | Missing entity parameter | Provide the entity name |
| `ERR:file path required` | Missing file parameter | Provide the file path |
| `ERR:path not found: <path>` | Scan directory doesn't exist | Check the path |
| `ERR:not initialized` | Database doesn't exist | Run `dominian_init` first |
| `ERR:database empty` | No nodes in database | Run `dominian_scan` first |
| `ERR:adaptive_scanner not available` | Missing dependencies | Install Dominian with all deps |
| `ERR:requires networkx and python-louvain` | Missing community detection deps | `pip install networkx python-louvain` |

---

## Performance

| Operation | Typical Latency |
|-----------|----------------|
| `dominian_search` | <5ms |
| `dominian_node_get` | <5ms |
| `dominian_deps_direct/reverse` | <10ms |
| `dominian_graph_stats` | <5ms |
| `dominian_graph_hotspots` | <50ms |
| `dominian_graph_cycles` | <100ms |
| `dominian_arch_impact` | <50ms (depth=10) |
| `dominian_arch_communities` | <500ms (Louvain) |
| `dominian_scan` | Varies by project size |

The SQLite database uses WAL mode with full indexing, enabling microsecond query times for most operations.

---

## License

Same as Dominian Code Intelligence.
