pzalutski-pixel/sharplens-mcp

# SharpLensMcp [](https://www.nuget.org/packages/SharpLensMcp) [](https://www.npmjs.com/package/sharplens-mcp) [](LICENSE) 一个模型上下文协议（MCP）服务器，使用 Microsoft Roslyn 提供用于 .NET/C# 语义代码分析、导航、重构和代码生成的 **67 个 AI 优化工具**。 专为 AI 编程代理构建 - 提供 AI 仅通过阅读源代码文件无法推断出的、编译器般准确的代码理解能力。 ## 安装 ### 通过 NuGet（推荐） ``` dotnet tool install -g SharpLensMcp ``` 然后运行： ``` sharplens ``` ### 通过 npm ``` npx -y sharplens-mcp ``` ### 从源码构建 ``` dotnet build -c Release dotnet publish -c Release -o ./publish ``` ## Claude Code 设置 1. **安装工具**（任选其一）： ``` dotnet tool install -g SharpLensMcp # 或 npx -y sharplens-mcp ``` 2. **在您的项目根目录下创建 `.mcp.json`**： ``` { "mcpServers": { "sharplens": { "type": "stdio", "command": "npx", "args": ["-y", "sharplens-mcp"], "env": { "DOTNET_SOLUTION_PATH": "/path/to/your/Solution.sln (or .slnx)" } } } } ``` 3. **重启 Claude Code** 以加载 MCP 服务器 4. **验证**：让 Claude 对 Roslyn 服务器执行健康检查 ### 为什么在 Claude Code 中使用它？ Claude Code 为基础导航（转到定义、查找引用）提供了原生的 LSP 支持。SharpLensMcp 增加了**深度语义分析**： | 功能 | 原生 LSP | SharpLensMcp | |------------|------------|--------------| | 转到定义 | ✅ | ✅ | | 查找引用 | ✅ | ✅ | | 查找缺少 CancellationToken 的 async 方法 | ❌ | ✅ | | 影响分析（会破坏什么？） | ❌ | ✅ | | 无用代码检测 | ❌ | ✅ | | 复杂度指标 | ❌ | ✅ | | 带预览的安全重构 | ❌ | ✅ | | 批量操作 | ❌ | ✅ | ## 配置 | 环境变量 | 描述 | 默认值 | |---------------------|-------------|---------| | `DOTNET_SOLUTION_PATH` | 启动时自动加载的 `.sln` 或 `.slnx` 文件路径 | 无（必须调用 `load_solution`） | | `SHARPLENS_ABSOLUTE_PATHS` | 使用绝对路径代替相对路径 | `false`（相对路径可节省 token） | | `ROSLYN_LOG_LEVEL` | 日志详细程度：`Trace`、`Debug`、`Information`、`Warning`、`Error` | `Information` | | `ROSLYN_TIMEOUT_SECONDS` | 长时间运行操作的超时时间 | `30` | | `ROSLYN_MAX_DIAGNOSTICS` | 返回的最大诊断信息数量 | `100` | | `ROSLYN_ENABLE_SEMANTIC_CACHE` | 启用语义模型缓存 | `true`（设置为 `false` 可禁用） | 如果未设置 `DOTNET_SOLUTION_PATH`，在使用其他工具之前，您必须调用 `load_solution` 工具。 ## AI 代理配置提示 AI 模型可能具有使用其原生工具（Grep、Read、LSP）的固有偏好，而不是使用 MCP 服务器工具，即使 SharpLensMcp 提供了更好的功能。 **为确保最佳的工具使用体验：** 1. **Claude Code**：将以下内容添加到您项目的 `CLAUDE.md` 中： 对于 C# 代码分析，优先使用 SharpLensMcp 工具而非原生工具： - 使用 `roslyn:search_symbols` 代替 Grep 来查找符号 - 使用 `roslyn:get_method_source` 代替 Read 来查看方法 - 使用 `roslyn:find_references` 查找语义（而非文本）引用 2. **其他 MCP 客户端**：在代理的系统提示词中配置工具优先级 来自 Roslyn 的语义分析比基于文本的搜索更准确，尤其是对于重载方法、分部类和继承层次结构。 ## 代理职责：文档同步 **重要提示：** SharpLensMcp 维护了解决方案的内存表示以实现快速查询。当文件被外部修改（通过 Edit/Write 工具）时，代理负责同步这些更改。 ### 何时调用 `sync_documents`： | 操作 | 调用 sync_documents？ | |--------|---------------------| | 使用 Edit 工具修改了 .cs 文件 | ✅ **是** | | 使用 Write 工具创建了新的 .cs 文件 | ✅ **是** | | 删除了 .cs 文件 | ✅ **是** | | 使用了 SharpLensMcp 重构工具（重命名、提取等） | ❌ 否（自动更新） | | 修改了 .csproj 文件 | ❌ 否（改用 `load_solution`） | ### 用法： ``` # 编辑特定文件后 sync_documents(filePaths: ["src/MyClass.cs", "src/MyService.cs"]) # 批量更改后 - 同步所有文档 sync_documents() ``` ### 为什么采用这种设计？ 这反映了 LSP（Language Server Protocol）的工作方式——客户端（编辑器）向服务器通知更改。这种方法： - 消除竞态条件（代理控制时机） - 避免文件监视器的复杂性和平台特性问题 - 比完整的解决方案重载更快 - 让代理对工作区状态有明确的控制权 **如果您不同步：** 查询可能会返回过时的数据（旧的方法签名、缺少新文件等） ## 功能 - **67 个语义分析工具** - 导航、重构、代码生成、诊断、发现、审计/质量 - **AI 优化的描述** - 清晰的 USAGE/OUTPUT/WORKFLOW 模式 - **结构化响应** - 一致的 `success/error/data` 格式，包含 `suggestedNextTools` - **从零开始的坐标 (Zero-Based Coordinates)** - 明确的警告以防止 off-by-one 错误 - **预览模式** - 应用前带预览的安全重构 - **批量操作** - 一次调用进行多次查找，以减少上下文使用 ## 工具分类 ### 导航与发现（19 个工具） | 工具 | 描述 | |------|-------------| | `get_symbol_info` | 位置处的语义信息 | | `go_to_definition` | 跳转到符号定义 | | `find_references` | 所有引用；每个引用都分类为 read/write/invocation/cast/typeof/nameof/attribute；可选 `kind` 过滤器 | | `find_implementations` | 接口/抽象类实现 | | `find_callers` | 影响分析 - 谁调用了这个？ | | `get_call_graph` | 带有深度边界 + 循环检测的多跳调用者/被调用者图 | | `get_type_hierarchy` | 继承链 | | `search_symbols` | Glob 模式搜索（`*Handler`, `Get*`） | | `semantic_query` | 多条件过滤器搜索（async, public 等） | | `get_type_members` | 按类型名称获取所有成员 | | `get_type_members_batch` | 一次调用获取多个类型 | | `get_method_signature` | 按名称获取详细签名 | | `get_derived_types` | 查找所有子类 | | `get_base_types` | 完整继承链 | | `get_attributes` | 列出符号上的 attribute | | `get_containing_member` | 位置处的包含符号 | | `get_method_overloads` | 方法的所有重载 | | `find_attribute_usages` | 按 attribute 查找类型/成员 | | `get_external_type_info` | 检查 NuGet/BCL/外部程序集类型 — 成员 + XML 文档 | ### 分析（11 个工具） | 工具 | 描述 | |------|-------------| | `get_diagnostics` | 编译器错误/警告 + 配置的分析器（StyleCop, Roslynator, NetAnalyzers）发现的问题；与 CI 匹配 | | `analyze_data_flow` | 变量赋值与使用情况 | | `analyze_control_flow` | 分支/可达性 | | `analyze_change_impact` | 如果更改会破坏什么？ | | `check_type_compatibility` | A 可以赋值给 B 吗？ | | `get_outgoing_calls` | 此方法调用了什么？ | | `find_unused_code` | 无用代码检测 | | `validate_code` | 不写入文件进行编译检查 | | `get_complexity_metrics` | 圈复杂度、嵌套、LOC、认知复杂度 | | `find_circular_dependencies` | 项目和命名空间循环检测 | | `get_missing_members` | 未实现的接口/抽象成员 | ### 重构（14 个工具） | 工具 | 描述 | |------|-------------| | `rename_symbol` | 跨解决方案安全重命名 | | `change_signature` | 添加/删除/重新排序参数 | | `extract_method` | 带有数据流分析的提取 | | `extract_interface` | 从类生成接口 | | `generate_constructor` | 从字段/属性生成 | | `organize_usings` | 排序并移除未使用的引用 | | `organize_usings_batch` | 批量整理多个文件 | | `format_document_batch` | 批量格式化项目中的文件 | | `get_code_actions_at_position` | 位置处所有 Roslyn 重构 | | `apply_code_action_by_title` | 按标题应用任何重构 | | `implement_missing_members` | 生成接口存根 | | `encapsulate_field` | 字段转属性 | | `inline_variable` | 内联临时变量 | | `extract_variable` | 提取表达式到变量 | ### 代码生成（2 个工具） | 工具 | 描述 | |------|-------------| | `add_null_checks` | 生成 ArgumentNullException 防护 | | `generate_equality_members` | 生成 Equals/GetHashCode/operators | ### 复合工具（7 个工具） | 工具 | 描述 | |------|-------------| | `get_type_overview` | 一次调用获取完整类型信息 | | `analyze_method` | 签名 + 调用者 + 传出调用 + 位置 | | `get_file_overview` | 带有诊断的文件摘要 | | `get_method_source` | 按名称获取源代码 | | `get_method_source_batch` | 一次调用获取多个方法源码 | | `get_instantiation_options` | 如何创建类型 | | `get_project_health` | 综合审计面板：每个项目的诊断 + 未使用代码 + 耦合度 + 覆盖率 | ### 审计与质量（2 个工具） | 工具 | 描述 | |------|-------------| | `find_god_objects` | 通过传出 + 传入耦合 + 成员数阈值检测过度耦合的类型 | | `find_untested_code` | 查找未被任何 [Fact]/[Theory]/[Test]/[TestMethod] 覆盖的公共接口 | ### 发现（2 个工具） | 工具 | 描述 | |------|-------------| | `get_di_registrations` | 扫描 DI 服务注册 | | `find_reflection_usage` | 检测反射/动态用法 | ### 基础设施（10 个工具） | 工具 | 描述 | |------|-------------| | `health_check` | 服务器状态 | | `load_solution` | 加载 .sln/.slnx 进行分析 | | `sync_documents` | 将文件更改同步到已加载的解决方案中 | | `get_project_structure` | 解决方案结构 | | `dependency_graph` | 项目依赖项 | | `get_code_fixes` | 诊断的可用修复 | | `apply_code_fix` | 应用特定的代码修复 | | `get_nuget_dependencies` | 每个项目的 NuGet 包列表 | | `get_source_generators` | 列出活跃的源生成器 | | `get_generated_code` | 查看生成的源代码 | ## 其他 MCP 客户端 对于 Claude Code 以外的 MCP 客户端，请添加到您的配置中： ``` { "mcpServers": { "sharplens": { "command": "sharplens", "args": [], "env": { "DOTNET_SOLUTION_PATH": "/path/to/your/Solution.sln (or .slnx)" } } } } ``` ## 用法 1. **加载解决方案**：使用 `.sln` 或 `.slnx` 文件路径调用 `roslyn:load_solution`（或设置 `DOTNET_SOLUTION_PATH`） 2. **分析代码**：使用 67 个工具中的任何一个进行导航、分析、重构和审计 3. **安全重构**：在应用前使用 `preview: true` 预览更改 ## 架构 ``` MCP Client (AI Agent) | stdin/stdout (JSON-RPC 2.0) v SharpLensMcp - Protocol handling - 67 AI-optimized tools | v Microsoft.CodeAnalysis (Roslyn) - MSBuildWorkspace - SemanticModel - SymbolFinder ``` ## 要求 - **.NET 8.0 SDK 或更高版本** — 兼容 .NET 8、9、10 及未来版本。可分析任何 .NET 8+ 的项目/解决方案。 - 兼容 MCP 的 AI 代理 ## 开发 ### 添加新工具 1. **在 `src/RoslynService.cs` 中添加方法**： ``` public async Task