SourceIntelligence 1.0.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
• 🔁 Live file watcher — incremental re-index within 5 seconds of any file change
• 💾 Warm cache — .sourceindex.cache.gz makes subsequent starts near-instant
• 🌐 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.

Configuration

Command-line (highest priority)

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,
    "MaxFileSizeBytes": 524288,
    "FileWatcherDebounceMs": 5000,
    "GitWatcherDebounceMs": 2000,
    "DefaultContextLines": 2
  }
}

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

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 Windows Service

Use the included install-service.ps1 script to install SourceIntelligence as an auto-start Windows Service. Requires the global tool to be installed first (dotnet tool install -g SourceIntelligence).

# Install on default port 5200
.\install-service.ps1 -RepoPath "C:\path\to\your\repo"

# Install on a custom port
.\install-service.ps1 -RepoPath "C:\path\to\your\repo" -Port 5300

# Uninstall
.\install-service.ps1 -Uninstall

The service:

• Runs HTTP on the configured port (http://localhost:5200/mcp)
• Starts automatically on boot
• Restarts automatically on failure (up to 3 times, with increasing backoff)
• Logs to the Windows Event Log under the source SourceIntelligence

Connect your MCP client to http://localhost:5200/mcp after installation.

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.

How It Works

1. On startup, SourceIntelligence scans the repository, builds an inverted full-text index and a forward index, then saves a compressed cache (.sourceindex.cache.gz) to disk.
2. A file-system watcher monitors the repository for changes and incrementally updates the index within 5 seconds of any file change.
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. 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.
5. All tool calls are served from in-memory structures — no disk I/O during search.

Available Tools

License

MIT