feat: streamline module compare guidance

Author: EdmondLu

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project are documented here.
 
+## 1.15.0 - 2026-06-29
+
+- Added `changedLineSummary` to module/file comparison results so callers do not need to parse summary text for changed and returned line counts.
+- Added first-body-difference next actions that point directly to the database and local file lines to inspect.
+- Added `compare.repoExcludePatterns` config defaults, merged with per-call `excludePatterns`, for routinely ignoring historical or backup SQL folders during repository module discovery.
+
 ## 1.14.0 - 2026-06-29
 
 - Added `firstBodyDifference` to module/file comparison results, mapping the first SQL-normalized body difference back to database and file line numbers.

README.md

@@ -83,6 +83,7 @@ See [`docs/sqlserver_mcp.example.json`](docs/sqlserver_mcp.example.json) for a c
 | `security.allowSystemDatabases` | `false` | Allow system databases |
 | `textSearch.targets` | `[]` | Allow-listed text columns for `search_config_text` |
 | `textSearch.snippetLength` | `240` | Snippet length for configured text searches |
+| `compare.repoExcludePatterns` | `[]` | Default repository glob patterns to exclude in `compare_module_to_repo` |
 | `logging.logSql` | `false` | Include submitted SQL text in file logs |
 | `connection.encrypt` | `true` | Encrypt SQL connections |
 | `connection.trustServerCertificate` | `false` | Skip certificate-chain validation |
@@ -120,7 +121,7 @@ Relative `logs`, `cache`, and `tmp` directories are created beside the config fi
 
 Search, definition-slice, configuration-text, usage, and read-only query tools expose `resultInfo` for consistent returned-count, limit, truncation, reason, and hint metadata.
 
-Module/file comparison returns a readable top-level summary, `differenceKind`, `firstBodyDifference`, ignored wrapper-difference labels, and multi-hunk diffs with truncation metadata. Use `diffMode=summary` for ranges only, `compact` for the default focused diff, or `full` with larger `maxHunks` / `maxDiffLinesPerSide` caps. Repository comparison also accepts `excludePatterns` such as `backup/**` and returns `suggestedPatterns` for ambiguous candidates. It reports `sqlNormalizedMatch` and SQL-normalized hashes to ignore common deployment-script wrapper differences such as `CREATE OR ALTER`, leading `SET ANSI_NULLS` / `SET QUOTED_IDENTIFIER`, and trailing `GO`, while `firstBodyDifference` maps the first SQL-normalized body change back to database and file line numbers.
+Module/file comparison returns a readable top-level summary, `changedLineSummary`, `differenceKind`, `firstBodyDifference`, ignored wrapper-difference labels, and multi-hunk diffs with truncation metadata. Use `diffMode=summary` for ranges only, `compact` for the default focused diff, or `full` with larger `maxHunks` / `maxDiffLinesPerSide` caps. Repository comparison accepts per-call `excludePatterns`, merges them with `compare.repoExcludePatterns` defaults such as `backup/**`, and returns `suggestedPatterns` for ambiguous candidates. It reports `sqlNormalizedMatch` and SQL-normalized hashes to ignore common deployment-script wrapper differences such as `CREATE OR ALTER`, leading `SET ANSI_NULLS` / `SET QUOTED_IDENTIFIER`, and trailing `GO`, while `firstBodyDifference` maps the first SQL-normalized body change back to database and file line numbers. When a body difference exists, `nextActions` points directly to the database and local file lines to inspect.
 
 `describe_query_result` accepts optional `templateValues` for UI SQL placeholders, for example `{ "0": "1=1" }` replaces `{0}` before describing columns. Replacements are raw SQL fragments, and the final SQL is still parsed by the read-only guard.
 

README.zh-CN.md

@@ -83,7 +83,7 @@ SQL 文本可能包含敏感数据，仅在确有需要时启用 `logging.logSql
 
 `compare_module_to_file` 适合已知道本地 SQL 文件路径时确认“仓库 SQL 是否已执行到数据库”；`compare_module_to_repo` 可按对象名在本地仓库/目录下自动发现 `.sql` 候选文件，唯一高分候选会直接比较，并列候选会返回列表让调用方收窄路径。
 
-模块/文件对比会返回顶层可读摘要、`differenceKind`、`firstBodyDifference`、被忽略的脚本包装差异标签，以及带截断信息的多 hunk diff。`diffMode=summary` 只返回差异范围，`compact` 是默认紧凑输出，`full` 可配合更大的 `maxHunks` / `maxDiffLinesPerSide` 查看更多行；仓库对比还支持 `excludePatterns` 排除 `backup/**` 等历史目录，并在候选并列时返回 `suggestedPatterns` 便于收窄。工具同时返回 `sqlNormalizedMatch` 和 SQL 归一化 hash，用于忽略常见部署脚本包装差异，例如 `CREATE OR ALTER`、开头 `SET ANSI_NULLS` / `SET QUOTED_IDENTIFIER`、结尾 `GO`；`firstBodyDifference` 会把第一处 SQL 归一化后的正文差异映射回数据库和本地文件行号。
+模块/文件对比会返回顶层可读摘要、`changedLineSummary`、`differenceKind`、`firstBodyDifference`、被忽略的脚本包装差异标签，以及带截断信息的多 hunk diff。`diffMode=summary` 只返回差异范围，`compact` 是默认紧凑输出，`full` 可配合更大的 `maxHunks` / `maxDiffLinesPerSide` 查看更多行；仓库对比支持调用参数 `excludePatterns`，并会和配置项 `compare.repoExcludePatterns` 合并，用于默认排除 `backup/**`、`domain2/**` 等历史目录，候选并列时返回 `suggestedPatterns` 便于收窄。工具同时返回 `sqlNormalizedMatch` 和 SQL 归一化 hash，用于忽略常见部署脚本包装差异，例如 `CREATE OR ALTER`、开头 `SET ANSI_NULLS` / `SET QUOTED_IDENTIFIER`、结尾 `GO`；`firstBodyDifference` 会把第一处 SQL 归一化后的正文差异映射回数据库和本地文件行号，存在正文差异时 `nextActions` 会直接提示要查看的数据库行和本地文件行。
 
 搜索、模块定义切片、配置文本搜索、用法搜索和只读查询工具都会返回 `resultInfo`，用于统一判断结果是否被限制、为什么被截断以及下一步该如何缩小范围。
 

docs/sqlserver_mcp.example.json

@@ -37,6 +37,12 @@
       }
     ]
   },
+  "compare": {
+    "repoExcludePatterns": [
+      "**/backup/**",
+      "**/domain2/**"
+    ]
+  },
   "logging": {
     "logSql": false,
     "maxFileSizeMb": 10,

src/SqlServerMcp/Configuration/SqlServerMcpOptions.cs

@@ -18,6 +18,8 @@ public sealed class SqlServerMcpOptions
 
     public TextSearchOptions TextSearch { get; init; } = new();
 
+    public CompareOptions Compare { get; init; } = new();
+
     public LoggingOptions Logging { get; init; } = new();
 
     public ConnectionOptions Connection { get; init; } = new();
@@ -85,6 +87,7 @@ private void Validate()
 
         Limits.Normalize();
         TextSearch.Normalize();
+        Compare.Normalize();
         Logging.Normalize();
     }
 }
@@ -211,6 +214,21 @@ public void Normalize()
     }
 }
 
+public sealed class CompareOptions
+{
+    public string[] RepoExcludePatterns { get; set; } = [];
+
+    public void Normalize()
+    {
+        RepoExcludePatterns = RepoExcludePatterns
+            .Where(pattern => !string.IsNullOrWhiteSpace(pattern))
+            .Select(pattern => pattern.Trim().Replace('\\', '/'))
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+    }
+}
+
 public sealed class LoggingOptions
 {
     public bool LogSql { get; set; }

src/SqlServerMcp/Sql/SqlMetadataService.cs

@@ -236,6 +236,10 @@ public async Task<object> HealthCheckAsync(CancellationToken cancellationToken)
             },
             limits = _options.Limits,
             security = _options.Security,
+            compare = new
+            {
+                repoExcludePatterns = _options.Compare.RepoExcludePatterns
+            },
             textSearch = new
             {
                 snippetLength = _options.TextSearch.SnippetLength,
@@ -778,7 +782,8 @@ public async Task<object> CompareModuleToRepoAsync(
         CancellationToken cancellationToken)
     {
         var module = await GetModuleDefinitionCoreAsync(schema, name, cancellationToken);
-        var discovery = FindModuleSqlFileDiscovery(root, module.Schema, module.Name, patterns, excludePatterns, maxCandidates);
+        var effectiveExcludePatterns = MergeRepoCompareExcludePatterns(_options.Compare.RepoExcludePatterns, excludePatterns);
+        var discovery = FindModuleSqlFileDiscovery(root, module.Schema, module.Name, patterns, effectiveExcludePatterns, maxCandidates);
         if (discovery.SelectedCandidate is null)
         {
             return new
@@ -821,7 +826,8 @@ public async Task<object> CompareModuleToRepoAsync(
             sqlNormalizedMatch = comparison.SqlNormalizedMatch,
             differenceKind = comparison.DifferenceKind,
             firstBodyDifference = comparison.FirstBodyDifference,
-            nextActions = ModuleCompareNextActions
+            changedLineSummary = comparison.ChangedLineSummary,
+            nextActions = comparison.NextActions
         };
     }
 
@@ -2464,14 +2470,17 @@ private async Task<ModuleFileComparisonResult> BuildModuleFileComparisonAsync(
         var differenceKind = ClassifyModuleFileDifference(exactMatch, normalizedMatch, sqlNormalizedMatch);
         var ignoredWrapperDifferences = DetectIgnoredWrapperDifferences(module.Definition, fileText);
         var firstBodyDifference = FindFirstBodyDifference(module.Definition, fileText);
+        var changedLineSummary = BuildChangedLineSummary(diff);
         var summary = BuildModuleFileComparisonSummary(
             file,
             diff,
+            changedLineSummary,
             exactMatch,
             normalizedMatch,
             sqlNormalizedMatch,
             differenceKind,
             firstBodyDifference);
+        var nextActions = BuildModuleCompareNextActions(firstBodyDifference, diff);
 
         return new ModuleFileComparisonResult(
             module.Schema,
@@ -2501,9 +2510,10 @@ private async Task<ModuleFileComparisonResult> BuildModuleFileComparisonAsync(
             differenceKind,
             ignoredWrapperDifferences,
             firstBodyDifference,
+            changedLineSummary,
             summary,
             diff,
-            ModuleCompareNextActions);
+            nextActions);
     }
 
     internal static ModuleSqlFileDiscovery FindModuleSqlFileDiscovery(
@@ -2581,6 +2591,13 @@ internal static ModuleSqlFileDiscovery FindModuleSqlFileDiscovery(
             hint);
     }
 
+    internal static string[] MergeRepoCompareExcludePatterns(string[] configuredPatterns, string[]? requestedPatterns)
+    {
+        return NormalizeRepoComparePatterns(
+            configuredPatterns.Concat(requestedPatterns ?? []).ToArray(),
+            []);
+    }
+
     private static string[] NormalizeRepoComparePatterns(string[]? patterns)
     {
         return NormalizeRepoComparePatterns(patterns, DefaultRepoComparePatterns);
@@ -2643,6 +2660,32 @@ private static string[] BuildRepoCompareSuggestedPatterns(ModuleSqlFileCandidate
             .ToArray();
     }
 
+    internal static ModuleChangedLineSummary BuildChangedLineSummary(ModuleFileDiff diff)
+    {
+        return new ModuleChangedLineSummary(
+            diff.DatabaseChangedLineCount,
+            diff.FileChangedLineCount,
+            diff.Hunks.Sum(hunk => hunk.DatabaseLines.Length + hunk.FileLines.Length));
+    }
+
+    internal static string[] BuildModuleCompareNextActions(ModuleBodyDifference? firstBodyDifference, ModuleFileDiff diff)
+    {
+        var nextActions = new List<string>();
+        if (firstBodyDifference is not null)
+        {
+            nextActions.Add(
+                $"Inspect first SQL body difference at database line {FormatNullableInt(firstBodyDifference.DatabaseLine)} and local file line {FormatNullableInt(firstBodyDifference.FileLine)}.");
+        }
+
+        nextActions.AddRange(ModuleCompareNextActions);
+        if (!diff.Equal && diff.Mode == "summary")
+        {
+            nextActions.Add("Use diffMode=compact to include surrounding line text for changed hunks.");
+        }
+
+        return nextActions.ToArray();
+    }
+
     private static string ClassifyModuleFileDifference(bool exactMatch, bool normalizedMatch, bool sqlNormalizedMatch)
     {
         if (exactMatch)
@@ -2700,18 +2743,18 @@ private static string[] DetectIgnoredWrapperDifferences(string databaseDefinitio
     private static string BuildModuleFileComparisonSummary(
         FileInfo file,
         ModuleFileDiff diff,
+        ModuleChangedLineSummary changedLineSummary,
         bool exactMatch,
         bool normalizedMatch,
         bool sqlNormalizedMatch,
         string differenceKind,
         ModuleBodyDifference? firstBodyDifference)
     {
-        var returnedDiffLineCount = diff.Hunks.Sum(hunk => hunk.DatabaseLines.Length + hunk.FileLines.Length);
         var truncatedText = diff.Truncated ? "truncated" : "not truncated";
         var firstBodyText = firstBodyDifference is null
             ? "firstBodyDifference=none"
             : $"firstBodyDifference=body:{firstBodyDifference.BodyLine},db:{FormatNullableInt(firstBodyDifference.DatabaseLine)},file:{FormatNullableInt(firstBodyDifference.FileLine)}";
-        return $"{differenceKind}; selected {file.Name}; exactMatch={FormatBool(exactMatch)}; normalizedMatch={FormatBool(normalizedMatch)}; sqlNormalizedMatch={FormatBool(sqlNormalizedMatch)}; {diff.Hunks.Length} hunks; changedLines=db:{diff.DatabaseChangedLineCount},file:{diff.FileChangedLineCount}; returnedDiffLines={returnedDiffLineCount}; {firstBodyText}; {truncatedText}";
+        return $"{differenceKind}; selected {file.Name}; exactMatch={FormatBool(exactMatch)}; normalizedMatch={FormatBool(normalizedMatch)}; sqlNormalizedMatch={FormatBool(sqlNormalizedMatch)}; {diff.Hunks.Length} hunks; changedLines=db:{changedLineSummary.Database},file:{changedLineSummary.File}; returnedDiffLines={changedLineSummary.Returned}; {firstBodyText}; {truncatedText}";
     }
 
     private static string FormatBool(bool value)
@@ -5340,10 +5383,16 @@ private sealed record ModuleFileComparisonResult(
         string DifferenceKind,
         string[] IgnoredWrapperDifferences,
         ModuleBodyDifference? FirstBodyDifference,
+        ModuleChangedLineSummary ChangedLineSummary,
         string Summary,
         ModuleFileDiff Diff,
         string[] NextActions);
 
+    internal sealed record ModuleChangedLineSummary(
+        int Database,
+        int File,
+        int Returned);
+
     internal sealed record ModuleBodyDifference(
         int BodyLine,
         int? DatabaseLine,

src/SqlServerMcp/SqlServerMcp.csproj

@@ -7,10 +7,10 @@
     <RootNamespace>SqlServerMcp</RootNamespace>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>1.14.0</Version>
-    <AssemblyVersion>1.14.0.0</AssemblyVersion>
-    <FileVersion>1.14.0.0</FileVersion>
-    <InformationalVersion>1.14.0</InformationalVersion>
+    <Version>1.15.0</Version>
+    <AssemblyVersion>1.15.0.0</AssemblyVersion>
+    <FileVersion>1.15.0.0</FileVersion>
+    <InformationalVersion>1.15.0</InformationalVersion>
     <Description>A read-only Model Context Protocol server for exploring and querying SQL Server.</Description>
     <RepositoryUrl>https://github.com/EdmondLu/sqlserver-mcp</RepositoryUrl>
     <RepositoryType>git</RepositoryType>

src/SqlServerMcp/Tools/SqlServerMcpTools.cs

@@ -164,7 +164,7 @@ public static Task<string> CompareModuleToRepo(
         [Description("Module name.")] string name,
         [Description("Optional repository/folder root. Defaults to the MCP process current directory.")] string? root = null,
         [Description("Optional path glob patterns such as **/*.sql, procedures/*.sql, or *proc*.sql. Defaults to **/*.sql.")] string[]? patterns = null,
-        [Description("Optional path glob patterns to exclude from candidate discovery, such as backup/** or domain2/**.")] string[]? excludePatterns = null,
+        [Description("Optional path glob patterns to exclude from candidate discovery, such as backup/** or domain2/**. Merged with compare.repoExcludePatterns from config.")] string[]? excludePatterns = null,
         [Description("Maximum ranked candidates to return when discovery is empty or ambiguous. Defaults to 10 and is capped.")] int? maxCandidates = null,
         [Description("Context lines around the changed block after a file is selected. Defaults to 5 and is capped.")] int? contextLines = null,
         [Description("Diff output mode: summary, compact, or full. Defaults to compact.")] string? diffMode = null,

tests/SqlServerMcp.Tests/ModuleFileDiffTests.cs

@@ -85,6 +85,7 @@ CREATE PROC dbo.Sample
         Assert.Equal(5, hunk.DatabaseEndLine);
         Assert.Empty(hunk.DatabaseLines);
         Assert.Empty(hunk.FileLines);
+        Assert.Equal(new(1, 1, 0), SqlMetadataService.BuildChangedLineSummary(diff));
     }
 
     [Fact]
@@ -174,6 +175,19 @@ SELECT 2
         Assert.Equal(3, firstBodyDifference.BodyLine);
         Assert.Equal(3, firstBodyDifference.DatabaseLine);
         Assert.Equal(7, firstBodyDifference.FileLine);
+
+        var diff = SqlMetadataService.BuildLineDiff(
+            databaseDefinition,
+            fileText,
+            contextLines: 1,
+            diffMode: "summary",
+            maxHunks: null,
+            maxDiffLinesPerSide: null);
+        var nextActions = SqlMetadataService.BuildModuleCompareNextActions(firstBodyDifference, diff);
+
+        Assert.Contains(nextActions, action => action.Contains("database line 3", StringComparison.Ordinal)
+                                               && action.Contains("local file line 7", StringComparison.Ordinal));
+        Assert.Contains(nextActions, action => action.Contains("diffMode=compact", StringComparison.Ordinal));
     }
 
     [Fact]
@@ -255,6 +269,16 @@ public void FindModuleSqlFileDiscovery_AppliesExcludePatterns()
         }
     }
 
+    [Fact]
+    public void MergeRepoCompareExcludePatterns_CombinesConfiguredAndRequestedPatterns()
+    {
+        var patterns = SqlMetadataService.MergeRepoCompareExcludePatterns(
+            ["backup/**", "domain2/**"],
+            ["domain2/**", "archive/**"]);
+
+        Assert.Equal(["backup/**", "domain2/**", "archive/**"], patterns);
+    }
+
     [Fact]
     public void FindModuleSqlFileDiscovery_AppliesPathPatterns()
     {

tests/SqlServerMcp.Tests/OptionsDefaultsTests.cs

@@ -30,4 +30,17 @@ public void TextSearchOptions_HaveNoTargetsByDefault()
         Assert.Empty(options.Targets);
         Assert.Equal(240, options.SnippetLength);
     }
+
+    [Fact]
+    public void CompareOptions_NormalizeRepoExcludePatterns()
+    {
+        var options = new CompareOptions
+        {
+            RepoExcludePatterns = [" backup\\** ", "backup/**", "", "domain2/**"]
+        };
+
+        options.Normalize();
+
+        Assert.Equal(["backup/**", "domain2/**"], options.RepoExcludePatterns);
+    }
 }