AI 지식 / / 2025. 6. 28. 21:05

Desktop Extensions - Claude Desktop용 원클릭 MCP 서버 설치 (Desktop Extensions: One-click MCP server installation for Claude Desktop)

Desktop Extensions는 MCP 서버 설치를 버튼 클릭만큼 쉽게 만듭니다. 기술 아키텍처와 좋은 확장 프로그램을 만들기 위한 팁을 공유합니다.

작년에 Model Context Protocol(MCP)을 출시했을 때, 개발자들이 Claude에게 파일 시스템부터 데이터베이스까지 모든 것에 대한 액세스를 제공하는 놀라운 로컬 서버를 구축하는 것을 보았습니다. 하지만 계속해서 같은 피드백을 들었습니다: 설치가 너무 복잡하다는 것이었습니다. 사용자들은 개발자 도구가 필요했고, 구성 파일을 수동으로 편집해야 했으며, 종종 종속성 문제에서 막혔습니다.

오늘, 우리는 MCP 서버 설치를 버튼 클릭만큼 간단하게 만드는 새로운 패키징 형식인 Desktop Extensions를 소개합니다.

MCP 설치 문제 해결

로컬 MCP 서버는 Claude Desktop 사용자에게 강력한 기능을 제공합니다. 로컬 애플리케이션과 상호작용하고, 개인 데이터에 액세스하며, 개발 도구와 통합할 수 있습니다—모든 데이터를 사용자의 머신에 보관하면서 말입니다. 하지만 현재 설치 프로세스는 상당한 장벽을 만듭니다:

  • 개발자 도구 필요: 사용자들은 Node.js, Python, 또는 다른 런타임이 설치되어 있어야 합니다
  • 수동 구성: 각 서버는 JSON 구성 파일을 편집해야 합니다
  • 종속성 관리: 사용자들은 패키지 충돌과 버전 불일치를 해결해야 합니다
  • 발견 메커니즘 없음: 유용한 MCP 서버를 찾으려면 GitHub를 검색해야 합니다
  • 업데이트 복잡성: 서버를 최신 상태로 유지하려면 수동 재설치가 필요합니다

이러한 마찰 요소들은 MCP 서버가 강력함에도 불구하고 비기술 사용자들에게는 대부분 접근 불가능하게 만들었습니다.

Desktop Extensions 소개

Desktop Extensions(.dxt 파일)는 전체 MCP 서버를 모든 종속성을 포함하여 단일 설치 가능한 패키지로 번들링함으로써 이러한 문제들을 해결합니다. 사용자에게 바뀌는 것은 다음과 같습니다:

이전:

# 먼저 Node.js 설치
npm install -g @example/mcp-server
# ~/.claude/claude_desktop_config.json을 수동으로 편집
# Claude Desktop 재시작
# 작동하기를 기대

이후:

  1. .dxt 파일 다운로드
  2. 더블클릭하여 Claude Desktop으로 열기
  3. "설치" 클릭

그게 전부입니다. 터미널도, 구성 파일도, 종속성 충돌도 없습니다.

아키텍처 개요

Desktop Extension은 로컬 MCP 서버와 Claude Desktop 및 desktop extensions를 지원하는 다른 앱들이 알아야 할 모든 것을 설명하는 manifest.json을 포함하는 zip 아카이브입니다.

extension.dxt (ZIP 아카이브)
├── manifest.json         # 확장 프로그램 메타데이터 및 구성
├── server/               # MCP 서버 구현
│   └── [서버 파일들]    
├── dependencies/         # 모든 필요한 패키지/라이브러리
└── icon.png             # 선택사항: 확장 프로그램 아이콘

# 예시: Node.js Extension
extension.dxt
├── manifest.json         # 필수: 확장 프로그램 메타데이터 및 구성
├── server/               # 서버 파일들
│   └── index.js          # 메인 진입점
├── node_modules/         # 번들된 종속성
├── package.json          # 선택사항: NPM 패키지 정의
└── icon.png              # 선택사항: 확장 프로그램 아이콘

# 예시: Python Extension
extension.dxt (ZIP 파일)
├── manifest.json         # 필수: 확장 프로그램 메타데이터 및 구성
├── server/               # 서버 파일들
│   ├── main.py           # 메인 진입점
│   └── utils.py          # 추가 모듈들
├── lib/                  # 번들된 Python 패키지들
├── requirements.txt      # 선택사항: Python 종속성 목록
└── icon.png              # 선택사항: 확장 프로그램 아이콘

Desktop Extension에서 유일한 필수 파일은 manifest.json입니다. Claude Desktop이 모든 복잡성을 처리합니다:

  • 내장 런타임: Claude Desktop과 함께 Node.js를 제공하여 외부 종속성을 제거합니다
  • 자동 업데이트: 새 버전이 사용 가능할 때 확장 프로그램이 자동으로 업데이트됩니다
  • 보안 비밀: API 키와 같은 민감한 구성은 OS 키체인에 저장됩니다

매니페스트는 사람이 읽을 수 있는 정보(이름, 설명, 작성자 등), 기능 선언(도구, 프롬프트), 사용자 구성, 런타임 요구사항을 포함합니다. 대부분의 필드는 선택사항이므로 최소 버전은 꽤 짧지만, 실제로는 지원되는 세 가지 확장 프로그램 유형(Node.js, Python, 클래식 바이너리/실행 파일) 모두 파일을 포함할 것으로 예상합니다:

{
  "dxt_version": "0.1",                     // 이 매니페스트가 준수하는 DXT 스펙 버전
  "name": "my-extension",                   // 기계 판독 가능한 이름 (CLI, API용)
  "version": "1.0.0",                       // 확장 프로그램의 시맨틱 버전
  "description": "A simple MCP extension",  // 확장 프로그램이 하는 일에 대한 간단한 설명
  "author": {                               // 작성자 정보 (필수)
    "name": "Extension Author"              // 작성자 이름 (필수 필드)
  },
  "server": {                               // 서버 구성 (필수)
    "type": "node",                         // 서버 유형: "node", "python", 또는 "binary"
    "entry_point": "server/index.js",       // 메인 서버 파일 경로
    "mcp_config": {                         // MCP 서버 구성
      "command": "node",                    // 서버를 실행할 명령어
      "args": [                             // 명령어에 전달되는 인수들
        "${__dirname}/server/index.js"      // ${__dirname}은 확장 프로그램 디렉토리로 교체됨
      ]                              
    }
  }
}

매니페스트 스펙에는 로컬 MCP 서버의 설치와 구성을 더 쉽게 만들기 위한 다양한 편의 옵션들이 있습니다. 서버 구성 객체는 템플릿 리터럴 형태의 사용자 정의 구성과 플랫폼별 재정의 모두를 위한 공간을 만드는 방식으로 정의할 수 있습니다. 확장 프로그램 개발자들은 사용자로부터 어떤 종류의 구성을 수집하고 싶은지 자세히 정의할 수 있습니다.

매니페스트가 구성에 어떻게 도움이 되는지 구체적인 예를 살펴보겠습니다. 아래 매니페스트에서 개발자는 사용자가 api_key를 제공해야 한다고 선언합니다. Claude는 사용자가 그 값을 제공할 때까지 확장 프로그램을 활성화하지 않고, 운영 체제의 비밀 저장소에 자동으로 보관하며, 서버를 시작할 때 ${user_config.api_key}를 사용자가 제공한 값으로 투명하게 교체합니다. 마찬가지로 ${__dirname}은 확장 프로그램의 압축 해제된 디렉토리의 전체 경로로 교체됩니다.

{
  "dxt_version": "0.1",
  "name": "my-extension",
  "version": "1.0.0",
  "description": "A simple MCP extension",
  "author": {
    "name": "Extension Author"
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "API_KEY": "${user_config.api_key}"
      }
    }
  },
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "API Key",
      "description": "Your API key for authentication",
      "sensitive": true,
      "required": true
    }
  }
}

대부분의 선택적 필드가 포함된 전체 manifest.json은 다음과 같을 수 있습니다:

{
  "dxt_version": "0.1",
  "name": "My MCP Extension",
  "display_name": "My Awesome MCP Extension",
  "version": "1.0.0",
  "description": "A brief description of what this extension does",
  "long_description": "A detailed description that can include multiple paragraphs explaining the extension's functionality, use cases, and features. It supports basic markdown.",
  "author": {
    "name": "Your Name",
    "email": "yourname@example.com",
    "url": "https://your-website.com"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/your-username/my-mcp-extension"
  },
  "homepage": "https://example.com/my-extension",
  "documentation": "https://docs.example.com/my-extension",
  "support": "https://github.com/your-username/my-extension/issues",
  "icon": "icon.png",
  "screenshots": [
    "assets/screenshots/screenshot1.png",
    "assets/screenshots/screenshot2.png"
  ],
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"
      }
    }
  },
  "tools": [
    {
      "name": "search_files",
      "description": "Search for files in a directory"
    }
  ],
  "prompts": [
    {
      "name": "poetry",
      "description": "Have the LLM write poetry",
      "arguments": ["topic"]
    }
  ]
}

첫 번째 확장 프로그램 만들기

간단한 파일 시스템 확장 프로그램을 만들어보겠습니다:

1단계: 프로젝트 설정

mkdir my-file-extension
cd my-file-extension
npm init -y
npm install @modelcontextprotocol/sdk

2단계: MCP 서버 구현

server/index.js를 만듭니다:

#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import fs from 'fs/promises';
import path from 'path';

const server = new Server(
  {
    name: 'file-system-server',
    version: '0.1.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === 'read_file') {
    try {
      const content = await fs.readFile(args.path, 'utf-8');
      return {
        content: [
          {
            type: 'text',
            text: content,
          },
        ],
      };
    } catch (error) {
      throw new Error(`Failed to read file: ${error.message}`);
    }
  }

  throw new Error(`Unknown tool: ${name}`);
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

이것은 또한 인수가 될 수 있습니다.

"server": {
   "type": "node",
   "entry_point": "server/index.js",
   "mcp_config": {
   "command": "node",
   "args": ["${__dirname}/server/index.js"],
   "env": {
      "ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"
   }
   }
}

3단계: 확장 프로그램 패키징

모든 것을 .dxt 파일로 번들링합니다:

npx @anthropic-ai/dxt pack

이 명령어는:

  1. 매니페스트를 검증합니다
  2. .dxt 아카이브를 생성합니다

4단계: 로컬 테스트

.dxt 파일을 Claude Desktop의 설정 창으로 드래그합니다. 다음을 볼 수 있습니다:

  • 확장 프로그램에 대한 사람이 읽을 수 있는 정보
  • 필요한 권한과 구성
  • 간단한 "설치" 버튼

고급 기능

크로스 플랫폼 지원

확장 프로그램은 다양한 운영 체제에 적응할 수 있습니다:

"server": {
  "type": "node",
  "entry_point": "server/index.js",
  "mcp_config": {
    "command": "node",
    "args": ["${__dirname}/server/index.js"],
    "platforms": {
      "win32": {
        "command": "node.exe",
        "env": {
          "TEMP_DIR": "${TEMP}"
        }
      },
      "darwin": {
        "env": {
          "TEMP_DIR": "${TMPDIR}"
        }
      }
    }
  }
}

동적 구성

런타임 값을 위한 템플릿 리터럴 사용:

  • ${__dirname}: 확장 프로그램의 설치 디렉토리
  • ${user_config.key}: 사용자 제공 구성
  • ${HOME}, ${TEMP}: 시스템 환경 변수

기능 선언

사용자가 기능을 미리 이해할 수 있도록 도움:

"tools": [
  {
    "name": "read_file",
    "description": "Read contents of a file"
  }
],
"prompts": [
  {
    "name": "code_review",
    "description": "Review code for best practices",
    "arguments": ["file_path"]
  }
]

확장 프로그램 디렉토리

Claude Desktop에 내장된 큐레이션된 확장 프로그램 디렉토리로 시작합니다. 사용자들은 원클릭으로 탐색, 검색, 설치할 수 있습니다—GitHub를 검색하거나 코드를 검토할 필요가 없습니다.

Desktop Extension 스펙과 macOS 및 Windows용 Claude의 구현 모두 시간이 지남에 따라 발전할 것으로 예상하지만, 확장 프로그램이 Claude의 기능을 창의적인 방식으로 확장하는 데 사용될 수 있는 다양한 방법들을 보기를 기대합니다.

확장 프로그램을 제출하려면:

  1. 제출 양식에서 찾을 수 있는 가이드라인을 따르는지 확인
  2. Windows와 macOS에서 테스트
  3. 확장 프로그램 제출
  4. 우리 팀이 품질과 보안을 검토

개방형 생태계 구축

우리는 MCP 서버 주변의 개방형 생태계에 전념하며, 여러 애플리케이션과 서비스에 의해 보편적으로 채택될 수 있는 능력이 커뮤니티에 도움이 되었다고 믿습니다. 이러한 약속에 따라, 우리는 Desktop Extension 스펙, 도구체인, 그리고 macOS 및 Windows용 Claude가 Desktop Extensions에 대한 자체 지원을 구현하는 데 사용하는 스키마와 핵심 기능들을 오픈소스로 공개하고 있습니다. dxt 형식이 Claude용 로컬 MCP 서버를 더 이식 가능하게 만들 뿐만 아니라 다른 AI 데스크톱 애플리케이션에도 도움이 되기를 바랍니다.

우리가 오픈소스로 공개하는 것들:

  • 완전한 DXT 스펙
  • 패키징 및 검증 도구
  • 참조 구현 코드
  • TypeScript 타입과 스키마

이는 다음을 의미합니다:

  • MCP 서버 개발자들을 위해: 한 번 패키징하면 DXT를 지원하는 어디서든 실행
  • 앱 개발자들을 위해: 처음부터 구축하지 않고도 확장 프로그램 지원 추가
  • 사용자들을 위해: 모든 MCP 지원 애플리케이션에서 일관된 경험

스펙과 도구체인은 의도적으로 0.1 버전으로 지정되었습니다. 더 큰 커뮤니티와 함께 형식을 발전시키고 변경하는 작업을 기대하고 있기 때문입니다. 여러분의 의견을 듣기를 기대합니다.

보안 및 엔터프라이즈 고려사항

확장 프로그램이 특히 기업에 새로운 보안 고려사항을 도입한다는 것을 이해합니다. Desktop Extensions의 프리뷰 릴리스에 여러 보안 장치를 구축했습니다:

사용자를 위해

  • 민감한 데이터는 OS 키체인에 보관
  • 자동 업데이트
  • 설치된 확장 프로그램을 감사할 수 있는 능력

기업을 위해

  • 그룹 정책(Windows) 및 MDM(macOS) 지원
  • 승인된 확장 프로그램을 사전 설치할 수 있는 능력
  • 특정 확장 프로그램이나 게시자를 차단 목록에 추가
  • 확장 프로그램 디렉토리를 완전히 비활성화
  • 프라이빗 확장 프로그램 디렉토리 배포

조직 내에서 확장 프로그램을 관리하는 방법에 대한 자세한 정보는 우리 문서를 참조하세요.

시작하기

자신만의 확장 프로그램을 구축할 준비가 되셨나요? 시작하는 방법은 다음과 같습니다:

MCP 서버 개발자들을 위해: 개발자 문서를 검토하거나 로컬 MCP 서버 디렉토리에서 다음 명령어를 실행하여 바로 시작하세요:

npm install -g @anthropic-ai/dxt
dxt init
dxt pack

Claude Desktop 사용자들을 위해: 최신 버전으로 업데이트하고 설정에서 Extensions 섹션을 찾아보세요

기업을 위해: 배포 옵션에 대한 엔터프라이즈 문서를 검토하세요

Claude Code로 구축하기

Anthropic 내부에서 우리는 Claude가 최소한의 개입으로 확장 프로그램을 구축하는 데 뛰어나다는 것을 발견했습니다. 여러분도 Claude Code를 사용하고 싶다면, 확장 프로그램이 하기를 원하는 일을 간단히 설명한 다음 프롬프트에 다음 컨텍스트를 추가하는 것을 권장합니다:

I want to build this as a Desktop Extension, abbreviated as "DXT". Please follow these steps:

1. **Read the specifications thoroughly:**
   - https://github.com/anthropics/dxt/blob/main/README.md - DXT architecture overview, capabilities, and integration patterns
   - https://github.com/anthropics/dxt/blob/main/MANIFEST.md - Complete extension manifest structure and field definitions
   - https://github.com/anthropics/dxt/tree/main/examples - Reference implementations including a "Hello World" example

2. **Create a proper extension structure:**
   - Generate a valid manifest.json following the MANIFEST.md spec
   - Implement an MCP server using @modelcontextprotocol/sdk with proper tool definitions
   - Include proper error handling and timeout management

3. **Follow best development practices:**
   - Implement proper MCP protocol communication via stdio transport
   - Structure tools with clear schemas, validation, and consistent JSON responses
   - Make use of the fact that this extension will be running locally
   - Add appropriate logging and debugging capabilities
   - Include proper documentation and setup instructions

4. **Test considerations:**
   - Validate that all tool calls return properly structured responses
   - Verify manifest loads correctly and host integration works

Generate complete, production-ready code that can be immediately tested. Focus on defensive programming, clear error messages, and following the exact
DXT specifications to ensure compatibility with the ecosystem.

결론

Desktop Extensions는 사용자가 로컬 AI 도구와 상호작용하는 방식의 근본적인 변화를 나타냅니다. 설치 마찰을 제거함으로써, 우리는 강력한 MCP 서버를 개발자뿐만 아니라 모든 사람이 접근할 수 있게 만들고 있습니다.

내부적으로, 우리는 desktop extensions를 사용하여 매우 실험적인 MCP 서버들을 공유하고 있습니다 - 일부는 재미있고, 일부는 유용합니다. 한 팀은 우리 모델들이 GameBoy에 직접 연결되었을 때 얼마나 멀리 갈 수 있는지 실험했습니다. 이는 우리의 "Claude plays Pokémon" 연구와 유사합니다. 우리는 Desktop Extensions를 사용하여 인기 있는 PyBoy GameBoy 에뮬레이터를 열고 Claude가 제어할 수 있게 하는 단일 확장 프로그램을 패키지했습니다. 모델의 기능을 사용자들이 이미 로컬 머신에 가지고 있는 도구, 데이터, 애플리케이션에 연결할 수 있는 무수한 기회가 존재한다고 믿습니다.

PyBoy MCP with Super Mario Land start screen

여러분이 무엇을 구축할지 기대됩니다. 수천 개의 MCP 서버를 가져다준 동일한 창의성이 이제 단 한 번의 클릭으로 수백만 명의 사용자에게 도달할 수 있습니다. MCP 서버를 공유할 준비가 되셨나요? 검토를 위해 확장 프로그램을 제출하세요.

출처: https://www.anthropic.com/engineering/desktop-extensions

관련 태그: #MCP #DesktopExtensions #Claude #AI도구 #확장프로그램 #개발도구

반응형
저작자표시 (새창열림)
  • 네이버 블로그 공유
  • 네이버 밴드 공유
  • 페이스북 공유
  • 카카오스토리 공유
AI 지식 관련 글
글 더보기

티스토리툴바