copilot-studio-code

Microsoft Copilot Studio 에이전트가 로컬 파일 시스템 및 셸에 대해 Claude-Code 스타일의 도구(읽기, 편집, 검색, 명령 실행)를 사용할 수 있게 해주는 로컬 MCP 서버입니다. Copilot Studio 테스트 캔버스에서 바로 사용할 수 있습니다. 가져오기 가능한 Copilot Studio 솔루션이 포함되어 있어 몇 분 안에 작동하는 에이전트를 구축할 수 있습니다.

노출된 도구

안전 모드 (시작 시 선택)

모드 선택 우선순위:

1. SAFETY 환경 변수 (strict / moderate / open)

2. --safety <mode> CLI 플래그

3. 시작 시 대화형 프롬프트 (10초 타임아웃 → moderate)

모든 write_file, edit_file, run_shell 호출은 <root>/.copilotstudio-mcp/audit.log에 추가됩니다.

실행 방법

npm install
npm start

서버는 다음과 같이 출력합니다:

copilot-studio-code MCP server
  workspace root : E:\Dev\projects\my-project
  safety mode    : moderate
  listening on   : http://localhost:8787/mcp
  health check   : http://localhost:8787/healthz

작업할 작업 공간을 재정의하려면:

$env:WORKSPACE_ROOT = "E:\Dev\some-other-project"; npm start

Copilot Studio에 연결하기

Copilot Studio는 클라우드 호스팅 방식이므로 localhost에 접근할 수 없습니다. Microsoft Dev Tunnels를 사용하여 HTTPS를 통해 서버를 노출하세요.

1. dev tunnels 설치 및 로그인

winget install Microsoft.devtunnel
devtunnel user login

2. 포트 8787에 대한 영구 터널 생성

devtunnel create copilotstudio-mcp --allow-anonymous
devtunnel port create copilotstudio-mcp -p 8787 --protocol http
devtunnel host copilotstudio-mcp

devtunnel host는 https://<id>-8787.usw2.devtunnels.ms와 같은 공개 URL을 출력합니다. 실행 상태로 두세요.

--allow-anonymous를 제거하면 터널은 Copilot Studio 측에서 MS 계정을 요구하게 됩니다. 작동이 확인되면 권장되는 방식입니다.

3. MCP 서버를 Copilot Studio 에이전트에 연결

두 가지 방법이 있습니다: 미리 빌드된 솔루션 가져오기(가장 빠름) 또는 에이전트 수동 구성.

경로 A — 미리 빌드된 솔루션 가져오기

solution/ 폴더에는 미리 구성된 에이전트(생성형 오케스트레이션 켜짐, 콘텐츠 조정 낮음), MCP 서버용 사용자 지정 커넥터, 플래너에 도구를 노출하는 WorkspaceMCP 토픽이 포함된 관리되지 않는 Copilot Studio 솔루션이 들어 있습니다.

1. https://make.powerapps.com → 환경 → 솔루션 → 솔루션 가져오기를 엽니다.

2. solution/CopilotStudioCode_1_0_0_0.zip을 업로드합니다. 마법사에서 기본값을 선택합니다.

3. 가져온 후 Workspace MCP 사용자 지정 커넥터 → 편집 → 일반 탭에서 자리 표시자 호스트 YOUR-TUNNEL-ID-PORT.YOUR-REGION.devtunnels.ms를 실제 dev tunnel 호스트(예: abc123-8787.usw2.devtunnels.ms)로 바꿉니다. 저장 → 커넥터 업데이트.

4. 가져온 에이전트를 열고 4단계(테스트 캔버스)로 건너뜁니다.

솔루션에는 MCP 서버 자체가 포함되어 있지 않으며, 이 저장소에서 로컬로 실행됩니다. 커넥터는 해당 서버를 가리키기만 합니다.

경로 B — 에이전트 수동 구성

1. Copilot Studio → 에이전트 → 도구 → + 도구 추가 → Model Context Protocol을 엽니다.

2. 서버 URL: https://<your-tunnel-id>-8787.usw2.devtunnels.ms/mcp

3. 인증: 없음(익명 터널의 경우) 또는 Microsoft Entra(인증된 터널의 경우).

4. 저장. Copilot Studio가 /mcp에서 도구 목록을 가져와 7개의 도구를 표시합니다. 각 도구가 에이전트에서 활성화되어 있는지 확인하세요.

5. 설정 → 생성형 AI → 오케스트레이션: 생성형; 콘텐츠 조정: 낮음. 생성형 오케스트레이션이 없으면 플래너가 MCP 도구를 전달하지 않습니다.

4. 테스트 캔버스에서 테스트

테스트 캔버스를 열고 다음과 같은 프롬프트를 시도해 보세요:

• "작업 공간 루트의 파일 목록을 나열해 줘."

• "package.json을 읽고 정의된 스크립트가 무엇인지 알려줘."

• "tsc --noEmit을 실행하는 lint라는 새 스크립트를 추가해 줘."

• "git status를 실행하고 결과를 요약해 줘."

에이전트는 src/tools.ts의 설명을 기반으로 도구를 선택합니다. 에이전트가 잘못된 도구를 선택하면 해당 설명을 더 구체적으로 수정하세요.

프로젝트 구조

src/                                  the MCP server (TypeScript)
  index.ts                            entry: safety prompt + boot
  server.ts                           express + Streamable HTTP MCP transport
  tools.ts                            the seven tool registrations
  safety.ts                           mode definitions
  paths.ts                            workspace-root path jail
  audit.ts                            JSONL audit log
solution/                             importable Copilot Studio solution
  CopilotStudioCode_1_0_0_0.zip       agent + connector + topics (unmanaged)