SourceIntelligence 2.4.0

SourceIntelligence

A Model Context Protocol (MCP) server that rapidly indexes large codebases and provides deep code intelligence to any MCP-compatible AI client — search, symbol lookup, git history, code metrics, dead-code detection, call-chain graphs, and more — built with .NET 10.

Features

• ⚡ Fast full-text search across all indexed source files with declaration-first ranking
• 🔍 Symbol lookup — find class, interface, method, enum, record, struct, and delegate definitions
• 📄 File outline — structural overview of all declarations in any file
• 🔗 Find usages & implementations — all call-sites, references, and interface implementations
• 🧹 Dead-code detection — heuristic unreferenced public types and methods
• 📦 NuGet & project dependency graphs — all PackageReference and ProjectReference entries
• 🌿 Git integration — blame, diffs, commit log, branch comparison, contributor stats, recently changed files, commit search
• 📊 Code metrics — lines of code, comment lines, blank lines per file
• 🕸️ Call-chain graph — end-to-end Mermaid flowchart from any entry-point method
• ✏️ Edit tools — write files, patch line ranges, and replace text with crash-safe WAL recovery
• 🔁 Live file watcher — incremental re-index within 500 ms of any file change, with silent background updates to code graph, cognition, and snapshots
• 💾 Warm cache — compressed cache makes subsequent starts near-instant
• 🧠 Cognition engine — knowledge graph, importance scoring, domain ownership, and multi-resolution context summaries
• 🕸️ Code graph — callers, callees, inheritance, and import relationships with multi-hop BFS traversal
• 🧭 Enterprise AI doc generator — incremental module-scoped docs + MCP scoped retrieval config for Copilot and LLM workflows
• 🌐 Dual transport — stdio (MCP clients) or HTTP (browser / SSE)
• 🪟 Windows Service support — run as an auto-start background service

Requirements

• .NET 10 SDK or later
• Git (optional — required only for git-related tools)

Installation

As a .NET Global Tool (recommended)

dotnet tool install -g SourceIntelligence

To update to the latest version:

dotnet tool update -g SourceIntelligence

From source

git clone https://github.com/BasitNaeem/SourceIntelligence.git
cd SourceIntelligence
dotnet build -c Release
dotnet run --project src/SourceIntelligence.csproj -- --repo /path/to/your/codebase

Getting Started

After installing the global tool, run it pointing at any repository:

sourceintelligence --repo /path/to/your/codebase

The server prints its status to stderr on startup:

Repository root : /path/to/your/codebase
Indexing files  ... (full build)
Index ready     : 1 234 files loaded  |  watcher active  |  git-watcher active

On subsequent runs the cache is loaded and the server is ready in under 1 second:

Repository root : /path/to/your/codebase
Indexing files  ... (cache warm)
Index ready     : 1 234 files loaded  |  watcher active  |  git-watcher active

First run takes 5–15 seconds depending on codebase size. After that the .sourceindex.cache.gz file makes restarts near-instant.

Transport modes

• sourceintelligence --stdio --repo /path/to/your/codebase forces MCP stdio mode.
• sourceintelligence --service --repo /path/to/your/codebase runs HTTP mode as a Windows Service.
• sourceintelligence --repo /path/to/your/codebase auto-selects stdio when launched by an MCP client and HTTP when launched from a terminal.

In stdio mode, stdout must remain protocol-clean. SourceIntelligence writes diagnostics to stderr so the MCP JSON-RPC stream is never polluted.

Configuration

Command-line (highest priority)

Flag	Description
--repo <path>	Absolute path to the repository to index
--service	Run as a Windows Service (HTTP transport)
--stdio	Force stdio transport even when running from a terminal

Environment variable

# Linux / macOS
export SOURCEINTELLIGENCE_REPO_PATH=/path/to/your/codebase

# Windows (PowerShell)
$env:SOURCEINTELLIGENCE_REPO_PATH = "C:\path\to\your\codebase"

appsettings.json

Place an appsettings.json alongside the executable (or in the working directory) to configure defaults:

{
  "Index": {
    "RepositoryPath": "/path/to/your/codebase",
    "ProjectName": "MyApp",
    "Port": 5200,
    "EnableEditTools": false,
    "HttpAccessToken": "optional-shared-token",
    "AllowedOrigins": ["https://your-client.example"],
    "EnforceLoopbackHttp": true,
    "MaxFileSizeBytes": 524288,
    "FileWatcherDebounceMs": 500,
    "GitWatcherDebounceMs": 2000,
    "EnableSemanticSearch": false,
    "EmbeddingModelPath": null,
    "EmbeddingDimension": 384
  }
}

Setting	Default	Description
RepositoryPath	CWD	Absolute path to the repository root to index
ProjectName	Folder name	Friendly name shown in tool output headers
Port	5200	HTTP port (HTTP / Windows Service mode only)
EnableEditTools	true in stdio, false in HTTP	Enables mutating edit tools (write_file, patch_lines, replace_in_file)
HttpAccessToken	unset	Optional shared token for HTTP requests (Authorization: Bearer ... or X-SourceIntelligence-Token)
AllowedOrigins	empty	Optional allow-list of HTTP Origin values for browser-based clients
EnforceLoopbackHttp	true	Reject HTTP requests not arriving from a loopback address
MaxFileSizeBytes	524288 (512 KB)	Files larger than this are skipped during indexing
FileWatcherDebounceMs	500	Debounce window (ms) before flushing file-system changes to the index
GitWatcherDebounceMs	2000	Debounce window (ms) before triggering a git-aware incremental refresh
EnableSemanticSearch	false	Enable hybrid lexical + semantic search (requires ONNX embedding model)
EmbeddingModelPath	unset	Path to an ONNX embedding model for semantic search
EmbeddingDimension	384	Embedding vector dimension for semantic search

Priority order: --repo flag → appsettings.json → SOURCEINTELLIGENCE_REPO_PATH env var → current working directory.

Safety defaults: edit tools are enabled by default in stdio mode, but disabled by default in HTTP mode. Enable them explicitly only when you trust the local HTTP caller and need remote edits.

Connecting an MCP Client

Visual Studio / VS Code (Copilot)

Add to your .mcp.json (user or workspace level):

Via global tool (after dotnet tool install -g SourceIntelligence):

{
  "servers": {
    "SourceIntelligence": {
      "type": "stdio",
      "command": "sourceintelligence",
      "args": ["--repo", "/path/to/your/codebase"]
    }
  }
}

Via built binary (faster startup, no .NET SDK required at runtime):

{
  "servers": {
    "SourceIntelligence": {
      "type": "stdio",
      "command": "/path/to/SourceIntelligence/bin/Release/net10.0/SourceIntelligence",
      "args": ["--repo", "/path/to/your/codebase"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "SourceIntelligence": {
      "command": "sourceintelligence",
      "args": ["--repo", "/path/to/your/codebase"]
    }
  }
}

HTTP / SSE mode

When stdin is not redirected (i.e. launched from a terminal rather than by an MCP client), the server starts in HTTP mode instead of stdio:

HTTP port       : 5200
Listening on    : http://localhost:5200/mcp

Connect any SSE-capable MCP client to that URL. The port is configurable via appsettings.json or the Port setting.

Running as a Background Service

Use the cross-platform SourceIntelligence.Installer tool to register SourceIntelligence as an auto-start background service on Windows, Linux, or macOS. Install it once:

dotnet tool install -g SourceIntelligence.Installer

Then run the installer pointing at your repository:

# Install on the default port (5200)
sourceintelligence-installer --repo /path/to/your/repo

# Install on a custom port
sourceintelligence-installer --repo /path/to/your/repo --port 5300

# Check service status
sourceintelligence-installer --status

# Uninstall
sourceintelligence-installer --uninstall

Platform details

Platform	Mechanism	Privileges required
Windows	Windows Service via sc.exe	Administrator (Run as Administrator)
Linux (root)	systemd system unit → /etc/systemd/system/	root / sudo
Linux (user)	systemd user unit → ~/.config/systemd/user/	none
macOS	launchd LaunchAgent → ~/Library/LaunchAgents/	none

The service:

• Runs HTTP on the configured port (http://localhost:5200/mcp by default)
• Starts automatically on boot / login
• Restarts automatically on failure
• On Windows: logs to the Windows Event Log under the source SourceIntelligence
• On Linux: logs to the system journal (journalctl -u sourceintelligence)
• On macOS: logs to /tmp/sourceintelligence.err.log

After installation, connect any MCP client to http://localhost:5200/mcp:

{
  "servers": {
    "SourceIntelligence": {
      "type": "http",
      "url": "http://localhost:5200/mcp"
    }
  }
}

Windows users: The legacy install-service.ps1 PowerShell script is still available as a Windows-only alternative to the cross-platform installer.

Building a Self-Contained Binary

# Windows
dotnet publish -c Release -r win-x64 --self-contained true -o ./publish

# Linux
dotnet publish -c Release -r linux-x64 --self-contained true -o ./publish

# macOS (Apple Silicon)
dotnet publish -c Release -r osx-arm64 --self-contained true -o ./publish

# macOS (Intel)
dotnet publish -c Release -r osx-x64 --self-contained true -o ./publish

The output is a single self-contained executable with no .NET runtime dependency.

Enterprise AI Knowledge Layer

Generate token-efficient architecture docs and module summaries:

dotnet run --project tools/ai-doc-generator/SourceIntelligence.AiDocGenerator.csproj -- --full --repo /path/to/repo

Incremental mode (after pull/merge):

dotnet run --project tools/ai-doc-generator/SourceIntelligence.AiDocGenerator.csproj -- --changed-only --base origin/main --head HEAD --repo /path/to/repo

Generated outputs include:

• docs/ai/system-architecture.md
• docs/ai/module-map.md
• docs/ai/event-flows.md
• docs/ai/request-flows.md
• docs/ai/common-patterns.md
• docs/ai/service-dependencies.md
• docs/ai/modules/*.md
• module-local README-AI.md files
• .mcp/config/*.json and .mcp/modules/*.json

How It Works

1. On startup, SourceIntelligence scans the repository, builds an inverted full-text index, a forward index, a regex-based code graph (callers/callees/inheritance/imports), and a cognition engine (knowledge graph, importance scores, domain ownership, summaries). A compressed cache is saved to disk outside the repository tree.
2. A file-system watcher monitors the repository for changes with a 500 ms debounce window and incrementally updates the index, code graph, and cognition engine on a background thread — no tool queries are blocked.
3. A git watcher monitors the .git directory for branch switches, pulls, and commits, triggering a git-aware incremental refresh (only changed files are re-indexed).
4. Snapshots (human-readable Markdown dumps of the index, cognition, and WAL) are written on startup and refreshed automatically 5 seconds after the last file change settles.
5. Tools block via an internal WaitUntilReadyAsync() call for up to 25 seconds on first launch, then return a "still building" message if the index hasn't warmed yet.
6. All tool calls are served from in-memory structures — no disk I/O during search.

Available Tools

Search & Symbols

Tool	Description
search_code	Full-text search with declaration-first ranking; compact mode for token-efficient results
find_symbol	Locate class / interface / method / enum / record / struct / delegate definitions by exact name
find_references	All call-sites, usages, and references to a symbol across the entire codebase
search_with_regex	Search using a full .NET regular expression pattern
search_by_attribute	Find all types / methods decorated with a specific C# attribute
search_in_file	Search within a single file by keyword, returning matching lines with context

File & Structure

Tool	Description
get_file_content	Retrieve file content with optional line range and auto-pagination (300-line pages)
get_multiple_files	Read up to 3 files in a single round-trip (adaptive cap: 2 when any file exceeds 500 lines)
list_files	Browse indexed files by extension and/or directory (capped at 200 by default)
get_file_outline	Ordered list of type and member declarations in a file
get_namespace_types	All types declared within a given namespace across the codebase
get_nuget_packages	List all PackageReference entries from every .csproj; filter by package name

Project & Dependencies

Tool	Description
get_project_structure	Solution files, all .csproj projects, and top-level directories with file counts
get_project_dependencies	All project-to-project ProjectReference edges; filter by project name

Code Graph

Tool	Description
find_callers	Find all callers of a symbol with configurable BFS depth
find_callees	Find all symbols called by a given symbol with configurable BFS depth
find_inheritors	Find all types that inherit from or implement a given type
find_imports	Find all files that import a given namespace
trace_call_chain	End-to-end call chain as a Mermaid flowchart from any entry-point method

Git

Tool	Description
get_file_diff	Unified git diff for a file (HEAD vs working tree, or between two refs)
get_file_history	Commit history for a specific file
get_git_blame	Line-by-line blame: who last modified each line, when, and in which commit
find_recently_changed	Files modified in git within the last N days
search_commits	Search git commit messages by keyword; filter by author and/or date range
compare_branches	Changed files and unique commits between two branches

Analysis & Context

Tool	Description
get_task_context	Bundles relevant files, declarations, diffs, and context for a given task (400-line budget)
find_related_tests	Discover test files for given source files or symbols (High/Medium confidence)

Diagnostics

Tool	Description
get_repository_summary	High-level stats (file counts, top dirs, sync status) with optional tool reference table
get_index_stats	Diagnostic: unique words, forward-index entries, estimated RAM footprint
get_index_health	File/git watcher status, pending changes, flush counts, and error counts
get_debug_logs	Server diagnostic logs filtered by level and category
refresh_index	Smart incremental re-index (git-aware → timestamp → full rebuild); force=true for full rebuild
export_cache_snapshot	Write human-readable Markdown snapshots of the index, cognition, and WAL to the cache directory

Edit Tools (stdio mode only by default)

Tool	Description
write_file	Create or overwrite a file with crash-safe WAL recovery
patch_lines	Replace a specific range of lines (startLine to endLine inclusive) with new content
replace_in_file	Find and replace a unique string in a file

Contributing

If you've ever run dotnet tool install -g SourceIntelligence or installed the Windows Service via install-service.ps1 on this machine, do this before iterating on the repo locally: the global tool shares this project's AssemblyName/PackageId (SourceIntelligence) and default port (5200), so a local dotnet run / dotnet <local.dll> can end up resolving assemblies from the globally-installed tool instead of your worktree, or fail to bind the port because the service is already listening on it.

Run once (elevate for the Windows Service removal step if you installed one):

.\scripts\uninstall-stale-global-tool.ps1

Or avoid the collision entirely by giving your local dev instance its own port via a local appsettings.json ({"Index":{"Port":5300}}) instead of uninstalling anything.

License

MIT