dominian 1.0.6

Dominian Code Intelligence — CLI tool and MCP server for scanning, querying, and analyzing codebases

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

cd dominian-mcp
pip install -e .

Manual Install

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):

{
  "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):

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

{
  "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.

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.

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.

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.

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).

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).

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

dominian_orphans(db_path=None)

Potential dead code or unused utilities.

---

dominian_surprising_connections

Find hidden cross-directory coupling.

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.

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.