Build a Custom MCP Server with TypeScript to Extend GitHub Copilot

flowchart TD
  A[VS Code Copilot Agent] -->|MCP| B[MCP Server]
  B --> C[External Services]
  B --> D[API]
  B --> E[Data Store]

[Before MCP]
GitHub Copilot -> Custom integration A -> Internal API
Claude         -> Custom integration B -> Internal API (duplicate)
Cursor         -> Custom integration C -> Internal API (duplicate)

[With MCP]
GitHub Copilot -+
Claude         +-> MCP Server -> Internal API (one implementation)
Cursor         -+

sequenceDiagram
  participant U as User
  participant L as LLM (Copilot)
  participant S as MCP Server
  participant A as External API

  U->>L: "List open Issues"
  L->>S: tools/call search_github_issues
  S->>A: GET /search/issues
  A-->>S: JSON result
  S-->>L: Tool result
  L-->>U: Answer

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

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

<!-- Example: SKILL.md -->
The internal status API endpoint is https://api.internal/status.
For authentication, specify a Bearer token in the Authorization header.
curl invocation example: curl -H "Authorization: Bearer $TOKEN" https://api.internal/status

flowchart TD
  A[Task to automate] --> B{Need an<br/>external system?}
  B -->|No| C[Use instruction-based customization]
  B -->|Yes| D{Must Copilot receive the result<br/>and reason over it?}
  D -->|No - code generation is enough| C
  D -->|Yes| E{Authentication, side effects,<br/>or dynamic data involved?}
  E -->|No| F[Check for an existing<br/>MCP server]
  E -->|Yes| G[Build an MCP server]
  F -->|None available| 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 (excerpt)
{
  "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: 'Gets the current weather for the specified city',
      inputSchema: z.object({
        city: z.string().describe('City to look up the weather for (e.g., Tokyo, Osaka)'),
      }),
    },
    async ({ city }) => {
      const weather = await fetchWeather(city)
      return {
        content: [{
          type: 'text',
          text: `Current weather in ${city}: ${weather.description}, temperature: ${weather.temp}°C`,
        }],
      }
    }
  )

  server.registerTool(
    'search_github_issues',
    {
      description: 'Searches issues in a GitHub repository',
      inputSchema: z.object({
        query: z.string().describe('Search query'),
        repo: z.string().regex(/^[^/]+\/[^/]+$/).describe('Repository name (owner/repo format)'),
        state: z.enum(['open', 'closed', 'all']).default('open').describe('Issue state'),
      }),
    },
    async ({ query, repo, state }) => {
      const token = process.env.GITHUB_TOKEN
      if (!token) {
        return {
          content: [{ type: 'text', text: 'GITHUB_TOKEN is not configured' }],
          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 server started')

// 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 is not configured')

  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(`Failed to fetch weather data: ${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')
      // Skip the frontmatter (the opening --- block) and use the first H1 as the title
      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
}

// Add these imports at the top of src/index.ts
import { readFile } from 'node:fs/promises'
import path from 'node:path'

// Register before return server in createServer
server.registerResource(
  'project-guide',
  'docs://project-guide',
  {
    title: 'Project Guide',
    description: 'A project guide to reference during development',
    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"]
    }
  }
}

"Show the weather in Tokyo"
  -> Copilot automatically calls the get_weather tool

"Find open Issues about \"memory leak\""
  -> Copilot automatically calls the search_github_issues tool

#my-custom-tools List open Issues about "authentication" in owner/my-repo
  -> Calls search_github_issues through this server

# Test tools interactively with 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': {
  // Describe the model-facing shape with JSON Schema,
  // then validate the accepted values with 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 'Invalid input. Check the required fields and value formats.'
  }

  if (error instanceof Error) {
    return `Tool execution failed: ${error.message}`
  }

  return 'Tool execution failed.'
}

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)
    }),
  ])
}

// Keep business logic separate for testing
export async function searchGithubIssues(input: SearchIssuesInput) {
  // Implementation
}

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