TypeScript で MCP サーバーを自作して GitHub Copilot を拡張する

flowchart TD
  A[VS Code Copilot Agent] -->|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（1 つで済む）
Cursor         ┘

sequenceDiagram
  participant U as ユーザー
  participant L as LLM（Copilot）
  participant S as MCP サーバー
  participant A as 外部 API

  U->>L: 「open 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 -->|No| C[指示ベースのカスタマイズで解決できる]
  B -->|Yes| D{Copilot が結果を<br/>受け取って推論する必要がある?}
  D -->|No — コード生成だけでよい| C
  D -->|Yes| E{認証・副作用・<br/>動的データが絡む?}
  E -->|No| F[既存の MCP サーバー<br/>で代替できないか確認]
  E -->|Yes| 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" に関する open Issue を調べて」
  → Copilot が search_github_issues ツールを自動呼び出し

#my-custom-tools owner/my-repo の "authentication" に関する open 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))
)