최근 AI 코딩 에이전트(Claude, Cursor 등)와 함께 코딩하는 이른바 ‘바이브코딩’ 이 유행하면서 생산성이 많이 높아졌지만, 동시에 한계도 명확히 느끼고 있습니다. 특히 .NET 환경에서 AI가 API 이름을 대충 짐작해서(Hallucination) 알려주거나, 네임스페이스 대소문자를 틀려 빌드 에러를 뿜어낼 때면 결국 손으로 고쳐야 하는 불편한 경험을 반복해야 했습니다.
이런 문제를 해결하기 위해, AI가 짐작이 아닌 실제 컴파일된 어셈블리와 NuGet 패키지 정보를 직접 조회하여 정확한 정보를 바탕으로 코딩할 수 있게 돕는 HandMirror MCP 서버를 개발하게 되었습니다.
왜 HandMirror가 필요한가요?
AI 모델의 학습 데이터는 종종 오래되었거나, 확장 메서드의 정확한 위치, 버전별 API 차이를 완벽히 파악하지 못합니다. HandMirror는 다음 상황에서 강력한 힘을 발휘합니다.
정확한 API 조회:SQLite인지 Sqlite인지 헷갈리는 대소문자 문제, 확장 메서드가 숨어 있는 네임스페이스 등을 실제 어셈블리 검사를 통해 100% 정확하게 찾아냅니다.
빌드 에러 해결사:CS0246, NU1605 같은 에러 코드를 분석하여 구체적인 해결책과 함께 필요한 NuGet 패키지 설치를 추천합니다.
버전 간 차이 분석: 패키지 업데이트 전후의 API 변경점(Breaking Changes)을 비교 분석해 줍니다.
네이티브 분석: P/Invoke나 COM interop 같은 복잡한 네이티브 의존성도 손쉽게 파악할 수 있습니다.
주요 기능
NuGet 패키지 탐색: 패키지 내 모든 네임스페이스, 타입, 메서드 시그니처를 버전별로 즉시 확인합니다.
프로젝트 및 솔루션 분석:.csproj 파일의 설정 문제나 패키지 버전 충돌을 진단합니다.
로컬 어셈블리 검사: 로컬에 있는 .dll이나 .exe 파일을 분석하여 공개된 모든 정보를 덤프합니다.
파일 기반 앱 지원: .NET 10+의 새로운 기능인 파일 기반 앱(#:package 등) 분석도 지원합니다.
시작하기
Claude Desktop이나 VS Code(Copilot) 등 MCP를 지원하는 클라이언트에서 바로 연동하여 사용할 수 있습니다.
User: 이 폴더에 SQLite 기반으로 DbUp을 사용해서 Todolist 데이터베이스를 만들어 콘솔 프로그램으로 할 일 목록을 관리하는 프로그램을 만들려고해.
GitHub Copilot: SQLite와 DbUp을 사용하는 Todolist 콘솔 프로그램을 만들어 드리겠습니다.
Created 5 todos
Ran terminal command: cd "d:\Projects\HandMirrorMcp\TestFlight\Scenario1" ; dotnet new console -n TodolistApp -o .
Starting: *NuGet 패키지 추가* (2/5)
Ran terminal command: dotnet add package dbup-sqlite ; dotnet add package Microsoft.Data.Sqlite
Starting: *DbUp 마이그레이션 스크립트 작성* (3/5)
이제 프로젝트 구조와 코드 파일들을 생성하겠습니다.
Created [](file:///d%3A/Projects/HandMirrorMcp/TestFlight/Scenario1/Scripts)
Created [](file:///d%3A/Projects/HandMirrorMcp/TestFlight/Scenario1/Scripts/001_CreateTodoTable.sql)
Created [](file:///d%3A/Projects/HandMirrorMcp/TestFlight/Scenario1/Models/TodoItem.cs)
Created [](file:///d%3A/Projects/HandMirrorMcp/TestFlight/Scenario1/Repositories/TodoRepository.cs)
Starting: *콘솔 UI 및 메인 프로그램 구현* (5/5)
Created [](file:///d%3A/Projects/HandMirrorMcp/TestFlight/Scenario1/Database/DatabaseMigrator.cs)
Created [](file:///d%3A/Projects/HandMirrorMcp/TestFlight/Scenario1/Program.cs)
Read [](file:///d%3A/Projects/HandMirrorMcp/TestFlight/Scenario1/Program.cs)
Using "Replace String in File"
```
```
이제 프로젝트 파일을 수정하여 SQL 스크립트 파일을 출력 디렉토리에 복사하도록 설정하겠습니다.
Read [](file:///d%3A/Projects/HandMirrorMcp/TestFlight/Scenario1/TodolistApp.csproj)
Using "Replace String in File"
```
```
이제 빌드하여 오류가 없는지 확인하겠습니다.
Ran terminal command: dotnet build
DbUp SQLite API를 확인하겠습니다.
Ran `inspect_nuget_package`
Completed with input: {
"packageId": "dbup-sqlite",
"version": "6.0.4"
}
Ran `search_nuget_types`
Completed with input: {
"packageId": "dbup-sqlite",
"pattern": "*",
"version": "6.0.4"
}
Ran `inspect_nuget_package_type`
Completed with input: {
"packageId": "dbup-sqlite",
"typeName": "SqliteExtensions",
"version": "6.0.4"
}
SQLite에는 `EnsureDatabase.For.SQLiteDatabase`가 없네요. SQLite는 연결 시 자동으로 파일이 생성되므로 해당 부분을 수정하겠습니다.
Using "Replace String in File"
```
```
Ran terminal command: dotnet build
Completed: *콘솔 UI 및 메인 프로그램 구현* (5/5)
빌드가 성공했습니다! SQLite + DbUp 기반 Todolist 콘솔 프로그램이 완성되었습니다.
## 생성된 프로젝트 구조
```
TestFlight/Scenario1/
├── TodolistApp.csproj # 프로젝트 파일
├── Program.cs # 메인 프로그램 (콘솔 UI)
├── Database/
│ └── DatabaseMigrator.cs # DbUp 마이그레이션 실행
├── Models/
│ └── TodoItem.cs # 할 일 모델
├── Repositories/
│ └── TodoRepository.cs # 데이터 액세스 레이어
└── Scripts/
└── 001_CreateTodoTable.sql # DB 스키마 생성 스크립트
```
## 주요 기능
| 메뉴 | 기능 |
|------|------|
| 1 | ➕ 할 일 추가 (제목/설명) |
| 2 | 📜 전체 목록 보기 |
| 3 | ○ 미완료 목록 보기 |
| 4 | ✓ 완료 목록 보기 |
| 5 | ✅ 할 일 완료 처리 |
| 6 | ↩️ 완료 취소 |
| 7 | ✏️ 할 일 수정 |
| 8 | 🗑️ 할 일 삭제 |
| 9 | 🧹 완료된 항목 모두 삭제 |
| 0 | 🚪 종료 |
## 실행 방법
```
cd d:\Projects\HandMirrorMcp\TestFlight\Scenario1
dotnet run
```
데이터베이스는 `todolist.db` 파일로 출력 디렉토리에 자동 생성됩니다. DbUp이 마이그레이션 스크립트를 관리하므로 새 스크립트(예: `002_AddPriorityColumn.sql`)를 추가하면 자동으로 적용됩니다.
Made changes.
User: 좋아. 지금 대화에서 #handmirror 도구가 쓰였나?
GitHub Copilot: 아니요, 이 대화에서 `mcp_handmirror_get_type_info` 도구는 사용되지 않았습니다.
DbUp SQLite API를 확인할 때 사용한 도구들은:
1. **`mcp_handmirror_inspect_nuget_package`** - dbup-sqlite 패키지의 어셈블리와 네임스페이스 목록 확인
2. **`mcp_handmirror_search_nuget_types`** - 패키지 내 타입 검색
3. **`mcp_handmirror_inspect_nuget_package_type`** - `SqliteExtensions` 타입의 메서드 시그니처 확인
`mcp_handmirror_get_type_info`는 **로컬 어셈블리 파일**(.dll/.exe)의 타입 정보를 조회할 때 사용하는 도구이고, NuGet 패키지 내 타입은 `mcp_handmirror_inspect_nuget_package_type`을 사용합니다.
User: 아, 내 말은 handmirror 도구를 일부라도 사용해서 문제가 해결된 것인지 궁금해서 물어본거야.
GitHub Copilot: 네, 맞습니다! **handmirror 도구가 빌드 오류 해결에 직접적으로 기여했습니다.**
## 문제 상황
처음 빌드할 때 두 가지 오류가 발생했습니다:
- `CS1061`: `SupportedDatabasesForEnsureDatabase`에 `SQLiteDatabase` 정의 없음
- `CS1061`: `SupportedDatabases`에 `SQLiteDatabase` 정의 없음
## handmirror 도구 사용
1. **`mcp_handmirror_inspect_nuget_package`** → dbup-sqlite 패키지에 어떤 네임스페이스/타입이 있는지 확인
2. **`mcp_handmirror_search_nuget_types`** → `SqliteExtensions` 클래스 발견
3. **`mcp_handmirror_inspect_nuget_package_type`** → 실제 메서드 시그니처 확인:
```csharp
// 실제 API (소문자 'l')
SqliteDatabase(SupportedDatabases supported, String connectionString)
```
## 발견한 문제
| 내가 작성한 코드 | 실제 API |
|-----------------|----------|
| `EnsureDatabase.For.SQLiteDatabase()` | ❌ 존재하지 않음 |
| `DeployChanges.To.SQLiteDatabase()` | `DeployChanges.To.SqliteDatabase()` (소문자 l) |
handmirror로 실제 API를 확인해서 코드를 수정하고 빌드에 성공했습니다.
왜 HandMirror가 필요한가요?
주요 기능
시작하기
마치며