使用 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（只需一个）
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 -->|否| C[可采用基于指令的定制]
  B -->|是| D{Copilot 是否需要接收结果<br/>并据此推理？}
  D -->|否，仅生成代码即可| C
  D -->|是| E{是否涉及认证、副作用或<br/>动态数据？}
  E -->|否| F[评估能否使用现有 MCP 服务器]
  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 请求失败：${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))
)