| 1 | <!-- English translation of adr/0058-agent-roslyn-mcp-coupling-settings-toml.md. Canonical Russian: ../../adr/0058-agent-roslyn-mcp-coupling-settings-toml.md --> |
| 2 | |
| 3 | # ADR 0058: Pairing the agent and Roslyn MCP in `settings.toml` (limits, node types, timeouts, presets) |
| 4 | |
| 5 | **Status:** Proposed |
| 6 | **Date:** 2026-04-18 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | MCP contracts | |
| 13 | | [0028](0028-user-settings-toml-localappdata-and-secrets.md) | `settings.toml` | |
| 14 | | [0039](0039-workspace-navigation-affordances.md) | navigation, MCP presets; UI intent map | |
| 15 | | [0040](0040-lsp-launch-line-settings-toml-presets-and-environment.md) | TOML pattern | |
| 16 | | [0053](0053-semantic-map-control-flow-pfd.md) | intent map on PFD | |
| 17 | | [0059](0059-roslyn-mcp-profiles-manager-tactical-strategic-efb.md) | profiles, Manager, Auto-Focus/Combat/Echelon modes, EFB on third monitor - **separate ADR** | |
| 18 | |
| 19 | --- |
| 20 | ## Context |
| 21 | |
| 22 | The agent layer and **Roslyn** are connected through **MCP tools**. Without explicit rules about how much and what to give, the agent overloads the context or underreceives the structure. This needs to be changed **in the config** ([0028](0028-user-settings-toml-localappdata-and-secrets.md)), without necessarily editing C#. |
| 23 | |
| 24 | **Intuition (not the ADR norm):** agent layer - request circuit, Roslyn MCP - semantics gateway; The settings below set **volume, filter, timing**. |
| 25 | |
| 26 | **Already available (not cancelled):** |
| 27 | |
| 28 | - `[semantic_map]` - UI type/depth - [0039](0039-workspace-navigation-affordances.md), [0053](0053-semantic-map-control-flow-pfd.md). |
| 29 | - Presets **`get_code_navigation_context`** - [0039 § Agent/MCP](0039-workspace-navigation-affordances.md#adr0039-mcp-workspace-navigation). |
| 30 | |
| 31 | This ADR is **agent ↔ Roslyn MCP pairing parameters layer** in TOML. Behavior of **profiles**, **Manager**, tactics/strategy, third monitor - **[0059](0059-roslyn-mcp-profiles-manager-tactical-strategic-efb.md)**. |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ## Solution (principles) |
| 36 | |
| 37 | <a id="adr0058-p1"></a> |
| 38 | |
| 39 | ### 1. One declarative scheme - several consumers |
| 40 | |
| 41 | | Category | Example of meaning | Who is obliged to take into account | |
| 42 | |-----------|----------------|---------------------| |
| 43 | | Response volume limits | `max_nodes_per_query`, traversal depth limits | **Roslyn MCP** (or Graph Aggregation Adapter) | |
| 44 | | Filter types of nodes/symbols | `included_kinds` / exceptions | **Roslyn MCP** | |
| 45 | | Timeouts / “dirty” semantics | awaiting compilation vs stale graph | **Roslyn MCP** ± **IDE** | |
| 46 | | Query Mode Presets | conditional `ExploreMode` / `RefactoringMode` | **Roslyn MCP**; agent can override in call | |
| 47 | |
| 48 | **Priority rule:** call argument > TOML section > server default - commit in implementation and [MCP-PROTOCOL.md](../../MCP-PROTOCOL.md) when fields appear. |
| 49 | |
| 50 | <a id="adr0058-p2"></a> |
| 51 | |
| 52 | ### 2. Four groups of parameters (contract axes) |
| 53 | |
| 54 | 1. **Throttling & scoping** - volume and depth limits per request (`max_nodes_per_query`, `max_recursion_depth` or equivalents in the tool specification). |
| 55 | |
| 56 | 2. **Visibility mapping (capabilities)** - what classes of nodes/symbols are in the results. |
| 57 | |
| 58 | 3. **Timeouts and consistency** - wait for compilation; stale graph; time limits for heavy queries. |
| 59 | |
| 60 | 4. **Instrumental presets** - named sets (controlFlow / architecture / overview vs refactoring). Link to [0039](0039-workspace-navigation-affordances.md): link by name or orthogonal presets - no implicit merge. |
| 61 | |
| 62 | <a id="adr0058-p3"></a> |
| 63 | |
| 64 | ### 3. Posting in TOML |
| 65 | |
| 66 | Target section, for example **`[agent.roslyn_mcp]`**, separate from `[semantic_map]` and from **`[[code_navigation.presets]]`** ([0039](0039-workspace-navigation-affordances.md)) without explicit mapping. Exact keys - after the prototype; here the **axes** are fixed. |
| 67 | |
| 68 | <a id="adr0058-p4"></a> |
| 69 | |
| 70 | ### 4. Versioning |
| 71 | |
| 72 | Optional keys and obvious defaults; changing the required form - bump schemas ([0028](0028-user-settings-toml-localappdata-and-secrets.md)). |
| 73 | |
| 74 | <a id="adr0058-p5"></a> |
| 75 | |
| 76 | ### 5. Minimum v0 vs deferred |
| 77 | |
| 78 | **v0:** limits + one or two timeouts + one “overview vs deeper” preset without full `included_kinds`. |
| 79 | |
| 80 | **Postponed:** comprehensive directory of kinds, complex recursion, megaconfig; **automation of profiles and modes** - [0059](0059-roslyn-mcp-profiles-manager-tactical-strategic-efb.md). |
| 81 | |
| 82 | --- |
| 83 | |
| 84 | ## Consequences |
| 85 | |
| 86 | - Explicit PR contract: the key refers to the MCP server or IDE. |
| 87 | - Tests for defaults and merge priorities. |
| 88 | |
| 89 | --- |
| 90 | |
| 91 | ## Rejected alternatives |
| 92 | |
| 93 | - Only env - worse reproducibility. |
| 94 | - Only a system prompt - there is no determinism at the tool level. |
| 95 | |
| 96 | --- |
| 97 | |
| 98 | ## Open questions |
| 99 | |
| 100 | - Synchronization with the **standalone** `roslyn-mcp` config outside the IDE - one scheme or two. |
| 101 | - What tools are in the scope of the first implementation (navigation / semantic map / both). |