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

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
  }
}

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

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

File & Structure

Project & Dependencies

Code Graph

Git

Analysis & Context

Diagnostics

Edit Tools (stdio mode only by default)

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