aicb-roslyn-mcp

# AIContextBuilder (`aicb`)

<!-- mcp-name: io.github.gregordadera/aicb-roslyn-mcp -->

[![NuGet Version](https://img.shields.io/nuget/v/aicb-roslyn-mcp)](https://www.nuget.org/packages/aicb-roslyn-mcp)
[![NuGet Downloads](https://img.shields.io/nuget/dt/aicb-roslyn-mcp)](https://www.nuget.org/packages/aicb-roslyn-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-1584ad)](https://registry.modelcontextprotocol.io/?q=io.github.gregordadera%2Faicb-roslyn-mcp)
[![License](https://img.shields.io/badge/license-custom%20EULA-lightgrey)](https://github.com/gregordadera/aicb-roslyn-mcp/blob/main/EULA.md)
[![M8ven Verified](https://img.shields.io/badge/M8ven%20Verified-publisher%20verified-4c1)](https://m8ven.ai/mcp/gregordadera-aicb-zb5d9e)

**Give coding agents a Roslyn-accurate map of your C#/.NET solution.** `aicb` is
a code intelligence server for C# and .NET: it answers questions about callers,
implementations, dependency injection, tests, side effects and change impact,
then packs the relevant code into compact Markdown for an LLM. It runs locally as
an MCP server and CLI; a Windows desktop app adds visual context selection,
analysis and editing.

> The software is closed source. This public repository contains its
> documentation, license and releases. It is free for individuals, education and
> organizations below the [license thresholds](#license-at-a-glance).

This page is a short tour, not the reference. It names 35 of the 54 tools an agent
sees by default; the three [manuals](#documentation) run to 35 chapters, about 40
times the length of this page.

## See it answer a code question

Ask your coding agent:

> What could be affected if I change `ColorMixerService`? Use AICB.

Or call the same tool from a terminal:

```sh
aicb call impact_of_change --sln C:/repo/App.sln --arg symbol=ColorMixerService
```

Abridged output from the bundled `ColorMixer.SelectionLab` sample:

```json
{
  "symbol": "ColorMixerService",
  "resolvedKind": "type",
  "directCount": 1,
  "transitiveCount": 2,
  "risk": "low",
  "productionImpactCount": 2,
  "directImpact": { "items": ["DemoCompositionRoot"] }
}
```

The desktop app's **MCP Usage** page records calls locally and separates guided
refusals from suspected defects:

[![AICB MCP Usage statistics showing calls, sessions, latency and the most-used tools](https://raw.githubusercontent.com/gregordadera/aicb-roslyn-mcp/main/docs/assets/aicb-mcp-usage.png)](https://www.dadera.de/en/aicb-mcp.html)

That answer comes from the Roslyn symbol graph, not a substring search. AICB
distinguishes overloads, follows interface and override relationships, understands
partial types and records DI construction paths.

## Build context that fits the task

AICB does more than answer individual symbol questions. It can assemble a focused,
task-specific context package for an agent instead of sending an unfiltered source
dump:

| Need | Tool | What it returns |
|---|---|---|
| Read one symbol in context | `get_context` | The symbol plus its direct dependencies and callees |
| Explore a named symbol with selected surroundings | `explain_symbol` | Callers, callees, implementations, tests or other requested dimensions |
| Pack context for a natural-language goal | `pack_for_task` | Goal-named symbols and their semantic neighborhood |
| Prepare to edit | `prepare_task` | The goal-focused context plus covering tests and likely siblings such as a factory or validator |
| Check the response cost first | `measure` | The exact token count of one or more planned tool answers, without returning their large payloads |

The focused context tools accept a **token budget**. Explicitly named seed symbols
stay in the package; AICB first reduces method detail and then removes less-relevant
surrounding content when the budget is tight. It does not cut text in the middle of
a block, and a leading note discloses types, tests or siblings that were omitted.
AICB can therefore tell you that a bundle was structurally reduced or capped; it
cannot certify that the remaining budget is sufficient to solve the task correctly.
Whole-document rendering can use the same budget pipeline through a pipeline profile,
including a configurable overshoot allowance and an optional trimming report.

The result is **AI-Builder-MD**: structured Markdown for an LLM, containing the
selected code together with symbol relationships, architecture graphs, semantic
metadata and provenance. It can use the established tag notation or YAML. See the
[context-document guide](https://github.com/gregordadera/aicb-roslyn-mcp/blob/main/docs/manual/general/05-the-context-document-ai-builder-md.md)
and the [task-packing tools](https://github.com/gregordadera/aicb-roslyn-mcp/blob/main/docs/manual/mcp/09-tool-reference-markup-export-review-and-insights.md#92-packing-and-exporting-context).

### Add explicit meaning with AI Tags and semantic annotations

AICB works without annotations. Where source structure and conventions are not
enough, optional `<ai>` tags in XML documentation let a developer state the intended
role of a type or method explicitly:

```csharp
/// <ai
///   role="service"
///   layer="Application"
///   responsibility="Coordinates order validation and submission."
///   stability="Stable"
/// />
public sealed class OrderService
```

Annotations can describe semantics such as role, domain, architectural layer,
priority, stability, responsibility and side effects. Explicit values take
precedence over heuristic inference; sentinel values such as `none` can deliberately
suppress inference for one field. AICB preserves provenance so an agent can
distinguish source-derived facts, author-provided meaning and inferred hints. The
[AI annotation reference](https://github.com/gregordadera/aicb-roslyn-mcp/blob/main/docs/manual/general/03-core-concepts.md#39-the-ai-annotation)
documents the supported forms and fields.

[![AIContextBuilder desktop app with a loaded solution](https://raw.githubusercontent.com/gregordadera/aicb-roslyn-mcp/main/docs/assets/aicb-main-light.png)](https://www.dadera.de/en/aicb-gui.html)

## How analysis and memory work

```text
.sln / .slnx / .slnf + C# + XAML/AXAML
                 ↓
        MSBuild + Roslyn semantic models
                 ↓
  AICB facts and consolidated semantic indexes
                 ↓
 individual answers or budgeted AI-Builder-MD
```

AICB is more than a response cache around Roslyn. During analysis it walks the
solution's C# documents, records declarations, calls, type references and other
facts, then consolidates caller and type fan-in, implementations, resolved markup
references and transitive side-effect classifications. Tools traverse or project
that warm model for a particular question; context tools select and render a
task-specific slice. This does **not** mean that every possible answer or runtime
relationship is precomputed.

An MCP session belongs to one `aicb mcp` process and pins both the analyzed graph
and its Roslyn workspace. A second server process builds its own session. The
desktop app, CLI and MCP server use the same analysis and rendering engine and can
share configuration and persisted snapshots through the local database, but they
do not share one live in-memory graph. Within one session, only one refresh runs at
a time; concurrent callers join it. A source-only edit can take the incremental
path, replaying changed document text without reloading the workspace. When that
path is unavailable, or when `force: true` is requested, AICB fully reloads it.

### Live sessions, snapshots and persistent codebase memory

These states serve different purposes and should not be treated as interchangeable:

| State | Lifetime and purpose | Important boundary |
|---|---|---|
| Live MCP session | In-memory graph and Roslyn workspace reused by one server process | Sees saved files, not unsaved editor buffers; another server process has a separate session |
| Remembered codebase | `remember_codebase` persists an analyzed model; `recall_codebase` can rehydrate it later or in another process without running Roslyn | A recalled session has no live workspace, no reliable line numbers and a reduced insight contract; use `refresh_remembered` when live precision is required |
| Saved snapshot | Named baseline used by `compare_with_previous` and public-contract comparison | A comparison baseline, not a live workspace |
| `<Solution>.aicb.json` | Git-trackable solution configuration | Contains rules and choices, never analysis results, sessions or credentials |

`remember_codebase`, `recall_codebase` and `refresh_remembered` are opt-in tools: no
MCP profile exposes them, so start the server with `AICB_MCP_TOOLS` naming them (or
`AICB_MCP_TOOLS=all`). `recall_codebase` reports whether the persisted model still matches the source,
payload schema and analyzer identity. It deliberately returns the recalled model
even when it is stale, with metadata that tells the agent when a live re-analysis
is necessary. See [sessions, recall and staleness](https://github.com/gregordadera/aicb-roslyn-mcp/blob/main/docs/manual/mcp/03-sessions-and-staleness.md).

### What the model can and cannot prove

- AICB analyzes statically visible C# and selected XAML/AXAML relationships. Code
  reached only through reflection, runtime assembly scanning, dynamic configuration
  or an external consumer can remain invisible.
- DI analysis recognizes statically readable Microsoft-DI-shaped registrations;
  runtime-produced registrations are disclosed as dynamic or unknown rather than
  invented.
- XAML binding analysis resolves paths only where the source and data type are safe
  to establish. Unknown scopes are skipped conservatively.
- A reported side effect is a conservative static contact classification propagated
  through known call edges. It is not general data-flow, taint or runtime state
  analysis.
- Responses disclose stale sessions, unresolved projects and capped result sets.
  Read `staleness`, `incompleteP