# HandMirror MCP Server
A Model Context Protocol (MCP) server for .NET assembly and NuGet package inspection. HandMirror helps AI coding agents understand .NET APIs accurately and resolve build errors by providing direct access to assembly metadata and NuGet package information.
## ๐ฏ Purpose
AI coding assistants often hallucinate or guess API details, leading to build errors and wasted development iterations. HandMirror solves this by:
- Providing **accurate, version-specific API information** directly from assemblies
- Enabling **verification of method signatures, types, and namespaces** before writing code
- Helping **diagnose and fix .NET build errors** quickly
- Supporting analysis of **native interop** (P/Invoke, COM) dependencies
## โจ Features
### Assembly Inspection
- **`inspect_assembly`** - Full analysis of all public types, members, and attributes with XML documentation
- **`list_namespaces`** - List all namespaces in an assembly
- **`get_type_info`** - Get detailed information about a specific type
### NuGet Package Exploration
- **`search_nuget_packages`** - Search for packages by keyword
- **`get_nuget_package_info`** - Get package metadata and dependencies
- **`get_nuget_package_versions`** - List all available versions
- **`inspect_nuget_package`** - Analyze assemblies in a package
- **`inspect_nuget_package_type`** - Get detailed type info from a package
- **`list_nuget_sources`** - List configured NuGet package sources
- **`clear_nuget_cache`** - Clear the local NuGet package cache
- **`get_nuget_vulnerabilities`** - Check for known security vulnerabilities
- **`inspect_nupkg_contents`** - Inspect contents of a .nupkg file
- **`extract_nupkg_file`** - Extract specific files from a .nupkg
### Native Interop Analysis
- **`inspect_native_dependencies`** - Find P/Invoke (DllImport/LibraryImport) and COM types in an assembly
### Project Analysis
- **`analyze_csproj`** - Analyze .NET project files and identify issues
- **`analyze_solution`** - Analyze solution files
- **`explain_build_error`** - Get explanations for common build errors
- **`analyze_file_based_app`** - Analyze file-based apps
- **`analyze_config_file`** - Analyze configuration files
- **`analyze_packages_config`** - Analyze packages.config files
### System Information
- **`get_system_info`** - Get system information (OS, .NET runtime, hardware)
- **`get_dotnet_info`** - Get detailed .NET installation information
## ๐ Prerequisites
- [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or later
- MCP-compatible client (e.g., Claude Desktop, VS Code with Copilot)
## ๐ Installation
### Build from Source
```bash
git clone https://github.com/rkttu/HandMirrorMcp.git
cd HandMirrorMcp
dotnet build
```
### Run the Server
```bash
dotnet run --project HandMirrorMcp
```
## โ๏ธ Configuration
### Claude Desktop
Add the following to your Claude Desktop configuration file:
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"handmirror": {
"command": "dotnet",
"args": ["run", "--project", "C:\\path\\to\\HandMirrorMcp"]
}
}
}
```
Or if you've built the project:
```json
{
"mcpServers": {
"handmirror": {
"command": "C:\\path\\to\\HandMirrorMcp\\bin\\Debug\\net8.0\\HandMirrorMcp.exe"
}
}
}
```
### VS Code with GitHub Copilot
Add to your VS Code settings or workspace settings:
```json
{
"servers": {
"handmirror": {
"command": "dotnet",
"args": ["run", "--project", "/path/to/HandMirrorMcp"]
}
}
}
```
## ๐ Usage Examples
### Verify API Before Writing Code
When you need to use an unfamiliar .NET API:
```text
Use inspect_nuget_package_type to show me the HttpClient class from System.Net.Http
```
### Diagnose Build Errors
When you encounter errors like `CS0246`, `CS1061`, or `CS7036`:
```text
I'm getting CS1061 error. Use inspect_nuget_package to check the Newtonsoft.Json package
and show me the available methods on JObject
```
### Explore NuGet Packages
```text
Search for packages related to "json serialization" and show me the top results
```
### Check Package Vulnerabilities
```text
Check if there are any known vulnerabilities in System.Text.Json version 6.0.0
```
### Analyze Project Issues
```text
Analyze my .csproj file at C:\MyProject\MyProject.csproj and identify any issues
```
## ๐๏ธ Architecture
```text
HandMirrorMcp/
โโโ Constants/
โ โโโ Emoji.cs # Unicode emoji constants for output formatting
โโโ Prompts/
โ โโโ AssemblyInspectorPrompts.cs
โ โโโ NuGetInspectorPrompts.cs
โโโ Services/
โ โโโ NuGetService.cs # NuGet package operations
โ โโโ PeAnalyzerService.cs # PE file analysis
โ โโโ RepositoryService.cs # Repository operations
โ โโโ XmlDocService.cs # XML documentation parsing
โโโ Tools/
โ โโโ AssemblyInspectorTool.cs
โ โโโ InteropInspectorTool.cs
โ โโโ NuGetInspectorTool.cs
โ โโโ ProjectAnalyzerTool.cs
โ โโโ SystemInfoTool.cs
โโโ Program.cs
```
## ๐งช Testing
Run the test suite:
```bash
dotnet test
```
The tests use MSTest and connect to the actual MCP server for integration testing.
## ๐ฆ Dependencies
- **[ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol)** - MCP server implementation
- **[Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting)** - .NET hosting abstractions
- **[Mono.Cecil](https://www.nuget.org/packages/Mono.Cecil)** - .NET assembly inspection
- **[NuGet.Protocol](https://www.nuget.org/packages/NuGet.Protocol)** - NuGet package operations
## ๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## ๐ License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## ๐ Acknowledgments
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- [Mono.Cecil](https://github.com/jbevain/cecil) for .NET assembly inspection capabilities
- The .NET community for continuous inspiration
## ๐ Support This Project
If you find HandMirror helpful in your development workflow, please consider supporting the project!
Your sponsorship helps maintain and improve this project, add new features, and keep it free for everyone. Every contribution, no matter how small, is greatly appreciated! โญ
---
**HandMirror** - *Look before you code* ๐ช