TypeScript로 커스텀 MCP 서버를 만들어 GitHub Copilot 확장하기

flowchart TD
  A[VS Code Copilot 에이전트] -->|MCP| B[MCP 서버]
  B --> C[외부 도구]
  B --> D[API]
  B --> E[데이터베이스]

[MCP 이전]
GitHub Copilot -> 독자적 연동 A -> 사내 API
Claude         -> 독자적 연동 B -> 사내 API (중복)
Cursor         -> 독자적 연동 C -> 사내 API (중복)

[MCP 도입 후]
GitHub Copilot -+
Claude         +-> MCP 서버 -> 사내 API (한 번만 구현)
Cursor         -+

sequenceDiagram
  participant U as 사용자
  participant L as LLM (Copilot)
  participant S as MCP 서버
  participant A as 외부 API

  U->>L: "열린 Issue를 확인해 줘"
  L->>S: tools/call search_github_issues
  S->>A: GET /search/issues
  A-->>S: 결과 JSON
  S-->>L: 도구 실행 결과
  L-->>U: 정리된 응답

// 요청
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_github_issues",
    "arguments": {
      "query": "authentication",
      "repo": "owner/my-repo",
      "state": "open"
    }
  }
}

// 응답
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"number\": 42, \"title\": \"Fix OAuth token refresh\", ...}]"
      }
    ]
  }
}

<!-- SKILL.md 예시 -->
내부 상태 API의 엔드포인트는 https://api.internal/status 입니다.
인증 시 Authorization 헤더에 Bearer 토큰을 지정합니다.
curl 호출 예시: curl -H "Authorization: Bearer $TOKEN" https://api.internal/status

flowchart TD
  A[하고 싶은 일이 있다] --> B{외부 시스템에<br/>접근해야 하는가?}
  B -->|아니요| C[지침 기반 사용자 지정으로 해결 가능]
  B -->|예| D{Copilot이 결과를 받아<br/>추론해야 하는가?}
  D -->|아니요 - 코드 생성만으로 충분| C
  D -->|예| E{인증, 부작용,<br/>동적 데이터가 관련되는가?}
  E -->|아니요| F[기존 MCP 서버로<br/>대체할 수 있는지 확인]
  E -->|예| G[MCP 서버 구현]
  F -->|없다면| G

mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D typescript @types/node tsx

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "strict": true
  },
  "include": ["src/**/*"]
}

// package.json(일부)
{
  "type": "module",
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

// src/index.ts
import { McpServer } from '@modelcontextprotocol/server'
import { serveStdio } from '@modelcontextprotocol/server/stdio'
import * as z from 'zod/v4'
import { fetchWeather } from './tools/weather.js'

interface GithubIssueSearchResponse {
  items: Array<{
    number: number
    title: string
    state: string
    html_url: string
  }>
}

function createServer(): McpServer {
  const server = new McpServer({
    name: 'my-custom-tools',
    version: '1.0.0',
  })

  server.registerTool(
    'get_weather',
    {
      description: '지정한 도시의 현재 날씨를 조회합니다',
      inputSchema: z.object({
        city: z.string().describe('날씨를 확인할 도시 이름(예: Tokyo, Osaka)'),
      }),
    },
    async ({ city }) => {
      const weather = await fetchWeather(city)
      return {
        content: [{
          type: 'text',
          text: `${city}의 현재 날씨: ${weather.description}, 기온: ${weather.temp}°C`,
        }],
      }
    }
  )

  server.registerTool(
    'search_github_issues',
    {
      description: 'GitHub 리포지토리에서 Issue를 검색합니다',
      inputSchema: z.object({
        query: z.string().describe('검색 쿼리'),
        repo: z.string().regex(/^[^/]+\/[^/]+$/).describe('리포지토리 이름(owner/repo 형식)'),
        state: z.enum(['open', 'closed', 'all']).default('open').describe('Issue 상태'),
      }),
    },
    async ({ query, repo, state }) => {
      const token = process.env.GITHUB_TOKEN
      if (!token) {
        return {
          content: [{ type: 'text', text: 'GITHUB_TOKEN이 설정되어 있지 않습니다' }],
          isError: true,
        }
      }

      const stateQualifier = state === 'all' ? '' : ` state:${state}`
      const url = new URL('https://api.github.com/search/issues')
      url.searchParams.set(
        'q',
        `${query} is:issue repo:${repo}${stateQualifier}`
      )

      const response = await fetch(url.toString(), {
        headers: {
          Authorization: `Bearer ${token}`,
          Accept: 'application/vnd.github.v3+json',
        },
      })

      if (!response.ok) {
        return {
          content: [{ type: 'text', text: `GitHub API error: ${response.status}` }],
          isError: true,
        }
      }

      const data = await response.json() as GithubIssueSearchResponse
      const issues = data.items.slice(0, 5).map((issue) => ({
        number: issue.number,
        title: issue.title,
        state: issue.state,
        url: issue.html_url,
      }))

      return {
        content: [{ type: 'text', text: JSON.stringify(issues, null, 2) }],
      }
    }
  )

  return server
}

void serveStdio(createServer)
console.error('MCP 서버를 시작했습니다')

// src/tools/weather.ts
interface WeatherData {
  description: string
  temp: number
  humidity: number
}

export async function fetchWeather(city: string): Promise<WeatherData> {
  const apiKey = process.env.OPENWEATHER_API_KEY
  if (!apiKey) throw new Error('OPENWEATHER_API_KEY가 설정되어 있지 않습니다')

  const url = `https://api.openweathermap.org/data/2.5/weather?q=${encodeURIComponent(city)}&appid=${apiKey}&units=metric&lang=ja`

  const response = await fetch(url)
  if (!response.ok) {
    throw new Error(`날씨 데이터를 가져오지 못했습니다: ${response.statusText}`)
  }

  const data = await response.json()
  return {
    description: data.weather[0].description,
    temp: Math.round(data.main.temp),
    humidity: data.main.humidity,
  }
}

// src/tools/docs-search.ts
import * as fs from 'fs/promises'
import * as path from 'path'
import { pathToFileURL } from 'url'

interface DocResult {
  title: string
  excerpt: string
  url: string
}

export async function searchDocs(
  query: string,
  limit: number
): Promise<DocResult[]> {
  const docsDir = process.env.DOCS_DIR ?? './docs'
  const files = await fs.readdir(docsDir)
  const results: DocResult[] = []

  for (const file of files.filter((f) => f.endsWith('.md'))) {
    const content = await fs.readFile(path.join(docsDir, file), 'utf-8')

    if (content.toLowerCase().includes(query.toLowerCase())) {
      const lines = content.split('\n')
      // frontmatter(첫 번째 --- 블록)를 건너뛴 뒤 첫 번째 H1을 제목으로 사용
      let bodyStart = 0
      if (lines[0]?.trim() === '---') {
        const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---')
        bodyStart = end >= 0 ? end + 1 : 0
      }
      const h1 = lines.slice(bodyStart).find((l) => /^#\s/.test(l))
      const title = h1 ? h1.replace(/^#\s*/, '') : path.basename(file, '.md')
      const matchIndex = content.toLowerCase().indexOf(query.toLowerCase())
      const excerpt = content.slice(
        Math.max(0, matchIndex - 50),
        matchIndex + 150
      )

      results.push({
        title,
        excerpt,
        url: pathToFileURL(path.resolve(docsDir, file)).toString(),
      })

      if (results.length >= limit) break
    }
  }

  return results
}

// src/index.ts 맨 앞에 추가
import { readFile } from 'node:fs/promises'
import path from 'node:path'

// createServer의 return server 앞에 추가
server.registerResource(
  'project-guide',
  'docs://project-guide',
  {
    title: '프로젝트 안내서',
    description: '개발 중 참고할 프로젝트 안내서',
    mimeType: 'text/markdown',
  },
  async (uri) => {
  const docsDir = process.env.DOCS_DIR ?? path.join(process.cwd(), 'docs')
  const content = await readFile(
    path.join(docsDir, 'project-guide.md'),
    'utf-8'
  )

  return {
    contents: [
      {
        uri: uri.href,
        mimeType: 'text/markdown',
        text: content,
      },
    ],
  }
  }
)

// .vscode/mcp.json
{
  "servers": {
    "my-custom-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}",
        "OPENWEATHER_API_KEY": "${env:OPENWEATHER_API_KEY}"
      }
    }
  }
}

{
  "servers": {
    "my-custom-tools-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "${workspaceFolder}/src/index.ts"]
    }
  }
}

"Tokyo의 날씨를 알려 줘"
  -> Copilot이 get_weather 도구를 자동으로 호출

"\"memory leak\"과 관련된 열린 Issue를 찾아 줘"
  -> Copilot이 search_github_issues 도구를 자동으로 호출

#my-custom-tools owner/my-repo에서 "authentication"과 관련된 열린 Issue를 나열해 줘
  -> 이 서버를 통해 search_github_issues 도구 호출

# MCP Inspector로 도구를 대화형으로 테스트한다
npx @modelcontextprotocol/inspector npx tsx src/index.ts

const updateIssueInput = {
  type: 'object',
  properties: {
    repo: { type: 'string', pattern: '^[^/]+/[^/]+$' },
    issueNumber: { type: 'integer', minimum: 1 },
    labels: {
      type: 'array',
      items: { type: 'string' },
      maxItems: 10,
    },
  },
  required: ['repo', 'issueNumber', 'labels'],
  additionalProperties: false,
}

case 'update_issue': {
  // JSON Schema로 모델에 보여 줄 형식을 정의하고,
  // Zod로 실제로 허용할 값을 검증한다
  const input = z.object({
    repo: z.string().regex(/^[^/]+\/[^/]+$/),
    issueNumber: z.number().int().positive(),
    labels: z.array(z.string()).max(10),
  }).parse(args)
  // ...
}

function toToolErrorMessage(error: unknown): string {
  if (error instanceof z.ZodError) {
    return '입력값이 올바르지 않습니다. 필수 항목과 값의 형식을 확인하세요.'
  }

  if (error instanceof Error) {
    return `도구 실행에 실패했습니다: ${error.message}`
  }

  return '도구 실행에 실패했습니다.'
}

async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
  return await Promise.race([
    promise,
    new Promise<T>((_, reject) => {
      setTimeout(() => reject(new Error(`Timed out after ${ms}ms`)), ms)
    }),
  ])
}

// 비즈니스 로직을 분리해 테스트할 수 있게 한다
export async function searchGithubIssues(input: SearchIssuesInput) {
  // 실제 처리
}

server.registerTool(
  'search_github_issues',
  { inputSchema: SearchIssuesInputSchema },
  async (input) => formatResult(await searchGithubIssues(input))
)