MCP Builder 完整指南

// ❌ 仅提供高级工作流（不灵活）
server.registerTool({
  name: 'github_setup_project',
  description: '创建仓库、添加协作者、创建 README',
  async handler({ project_name, collaborators }) {
    // 一次性完成所有操作
    // 问题：如果只想创建仓库呢？
  }
})

// ✅ 提供底层 API（推荐）
server.registerTool({
  name: 'github_create_repo',
  // ...
})

server.registerTool({
  name: 'github_add_collaborator',
  // ...
})

server.registerTool({
  name: 'github_create_file',
  // ...
})

// ✅ 好的命名
github_create_issue       // 清晰、一致
github_list_repos
github_merge_pull_request
github_close_issue

// ❌ 不好的命名
create                   // 太模糊
issue                    // 不是动作
createIssue             // 驼峰式不一致
gh_create_iss           // 缩写不清晰

server.registerTool({
  name: 'github_create_issue',
  description: `在指定的 GitHub 仓库中创建新的 issue。
  
  用途：
  - 报告 bug
  - 提出功能请求
  - 创建任务追踪
  
  注意：需要仓库的写权限`,
  // ...
})

const ListReposSchema = z.object({
  username: z.string(),
  page: z.number().default(1).describe("页码，从 1 开始"),
  per_page: z.number().default(30).max(100).describe("每页数量，最多 100")
})

server.registerTool({
  name: 'github_list_repos',
  inputSchema: zodToJsonSchema(ListReposSchema),
  async handler(args) {
    const { username, page, per_page } = ListReposSchema.parse(args)
    
    const repos = await client.listRepos(username, { page, per_page })
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          repos: repos.map(r => ({
            name: r.name,
            description: r.description,
            stars: r.stargazers_count,
            url: r.html_url
          })),
          pagination: {
            page,
            per_page,
            total: repos.length,
            has_more: repos.length === per_page
          }
        }, null, 2)
      }]
    }
  }
})

// ❌ 不好的错误
throw new Error('Repository not found')

// ✅ 好的错误
throw new Error(`
仓库 '${owner}/${repo}' 未找到

可能原因：
1. 仓库名称拼写错误
2. 仓库是私有的，但使用了公开 token
3. 仓库已被删除或重命名
4. 您没有访问权限

解决步骤：
1. 检查仓库名称：确保格式为 'owner/repo'
2. 验证权限：使用 github_list_repos 查看可访问的仓库
3. 检查 token 范围：确保 token 具有 'repo' 权限

示例：
github_list_repos(username="${owner}")
`.trim())

async function handleGitHubError(error: any, context: string) {
  if (error.status === 404) {
    throw new Error(`
${context} - 资源未找到

${error.message}

请检查：
1. 资源名称是否正确
2. 是否有访问权限
3. 资源是否存在
    `.trim())
  }
  
  if (error.status === 401) {
    throw new Error(`
${context} - 身份验证失败

请确保：
1. API token 有效且未过期
2. Token 具有必要的权限范围
3. 环境变量已正确设置

当前 token 范围可能不足。
    `.trim())
  }
  
  if (error.status === 403) {
    throw new Error(`
${context} - 权限不足

${error.message}

可能原因：
1. Token 缺少必要的权限范围
2. 达到 API 速率限制
3. 资源需要更高级别的权限

如果是速率限制，请稍后重试。
    `.trim())
  }
  
  // 通用错误
  throw new Error(`${context} - ${error.message || '未知错误'}`)
}

import { z } from 'zod'

const ConfigSchema = z.object({
  token: z.string().min(1, "GITHUB_TOKEN 是必需的"),
  apiUrl: z.string().url().default("https://api.github.com"),
  rateLimitThreshold: z.number().default(100)
})

const config = ConfigSchema.parse({
  token: process.env.GITHUB_TOKEN,
  apiUrl: process.env.GITHUB_API_URL,
  rateLimitThreshold: parseInt(process.env.GITHUB_RATE_LIMIT_THRESHOLD || '100')
})

import { z } from 'zod'

export class GitHubClient {
  private baseURL: string
  private token: string
  
  constructor(token: string, baseURL: string = 'https://api.github.com') {
    this.token = token
    this.baseURL = baseURL
  }
  
  /**
   * 发送 HTTP 请求到 GitHub API
   */
  async request<T = any>(
    endpoint: string,
    options: RequestInit = {}
  ): Promise<T> {
    const url = `${this.baseURL}${endpoint}`
    
    const response = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Accept': 'application/vnd.github.v3+json',
        'Content-Type': 'application/json',
        ...options.headers
      }
    })
    
    // 检查速率限制
    const remaining = response.headers.get('X-RateLimit-Remaining')
    if (remaining && parseInt(remaining) < 100) {
      console.warn(`⚠️  API 速率限制剩余: ${remaining}`)
    }
    
    if (!response.ok) {
      await this.handleError(response, endpoint)
    }
    
    return response.json()
  }
  
  /**
   * 处理 API 错误
   */
  private async handleError(response: Response, endpoint: string) {
    const errorBody = await response.json().catch(() => ({}))
    
    const context = `GitHub API ${response.status} - ${endpoint}`
    
    if (response.status === 404) {
      throw new Error(`
${context}

资源未找到: ${errorBody.message || '未知错误'}

可能原因：
1. 资源名称拼写错误
2. 资源不存在或已被删除
3. 您没有访问权限
      `.trim())
    }
    
    if (response.status === 401) {
      throw new Error(`
${context}

身份验证失败

请检查：
1. GITHUB_TOKEN 环境变量是否设置
2. Token 是否有效且未过期
3. Token 格式是否正确（以 ghp_ 开头）
      `.trim())
    }
    
    if (response.status === 403) {
      if (errorBody.message?.includes('rate limit')) {
        const resetTime = response.headers.get('X-RateLimit-Reset')
        const resetDate = resetTime ? new Date(parseInt(resetTime) * 1000) : null
        
        throw new Error(`
${context}

API 速率限制已达上限

${errorBody.message}

重置时间: ${resetDate?.toLocaleString() || '未知'}

解决方案：
1. 等待速率限制重置
2. 使用已认证的 token（更高限制）
3. 减少 API 调用频率
        `.trim())
      }
      
      throw new Error(`
${context}

权限不足: ${errorBody.message || '未知错误'}

请确保 token 具有必要的权限范围。
      `.trim())
    }
    
    // 通用错误
    throw new Error(`
${context}

${errorBody.message || response.statusText || '未知错误'}
    `.trim())
  }
  
  /**
   * GET 请求
   */
  async get<T = any>(endpoint: string, params?: Record<string, any>): Promise<T> {
    const url = new URL(endpoint, this.baseURL)
    
    if (params) {
      Object.entries(params).forEach(([key, value]) => {
        if (value !== undefined && value !== null) {
          url.searchParams.append(key, String(value))
        }
      })
    }
    
    return this.request(url.pathname + url.search)
  }
  
  /**
   * POST 请求
   */
  async post<T = any>(endpoint: string, data?: any): Promise<T> {
    return this.request(endpoint, {
      method: 'POST',
      body: JSON.stringify(data)
    })
  }
  
  /**
   * PATCH 请求
   */
  async patch<T = any>(endpoint: string, data?: any): Promise<T> {
    return this.request(endpoint, {
      method: 'PATCH',
      body: JSON.stringify(data)
    })
  }
  
  /**
   * DELETE 请求
   */
  async delete(endpoint: string): Promise<void> {
    await this.request(endpoint, { method: 'DELETE' })
  }
}

import { z } from 'zod'

export const CreateIssueSchema = z.object({
  owner: z.string().describe("仓库所有者（用户名或组织名）"),
  repo: z.string().describe("仓库名称"),
  title: z.string().min(1).describe("Issue 标题"),
  body: z.string().optional().describe("Issue 内容（Markdown 格式）"),
  labels: z.array(z.string()).optional().describe("标签列表"),
  assignees: z.array(z.string()).optional().describe("指派给的用户列表")
})

export const ListIssuesSchema = z.object({
  owner: z.string().describe("仓库所有者"),
  repo: z.string().describe("仓库名称"),
  state: z.enum(['open', 'closed', 'all']).default('open').describe("Issue 状态"),
  page: z.number().default(1).describe("页码"),
  per_page: z.number().default(30).max(100).describe("每页数量")
})

export const UpdateIssueSchema = z.object({
  owner: z.string().describe("仓库所有者"),
  repo: z.string().describe("仓库名称"),
  issue_number: z.number().describe("Issue 编号"),
  title: z.string().optional().describe("新标题"),
  body: z.string().optional().describe("新内容"),
  state: z.enum(['open', 'closed']).optional().describe("新状态"),
  labels: z.array(z.string()).optional().describe("标签列表")
})

import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { zodToJsonSchema } from 'zod-to-json-schema'
import { GitHubClient } from '../client/github.js'
import { CreateIssueSchema, ListIssuesSchema, UpdateIssueSchema } from '../schemas/index.js'

export function registerIssueTools(server: Server, client: GitHubClient) {
  
  // 创建 Issue
  server.registerTool({
    name: 'github_create_issue',
    description: `在 GitHub 仓库中创建新的 issue。
    
用途：
- 报告 bug 或问题
- 提出功能请求
- 创建任务追踪
- 记录待办事项

注意：需要仓库的写权限`,
    inputSchema: zodToJsonSchema(CreateIssueSchema),
    annotations: {
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: false,
      openWorldHint: true
    },
    async handler(args) {
      const { owner, repo, title, body, labels, assignees } = CreateIssueSchema.parse(args)
      
      const issue = await client.post(`/repos/${owner}/${repo}/issues`, {
        title,
        body,
        labels,
        assignees
      })
      
      return {
        content: [{
          type: 'text',
          text: `✅ Issue 创建成功！

**#${issue.number}** ${issue.title}
**状态**: ${issue.state}
**URL**: ${issue.html_url}
${labels ? `**标签**: ${labels.join(', ')}` : ''}
${assignees ? `**指派给**: ${assignees.join(', ')}` : ''}`
        }],
        structuredContent: {
          number: issue.number,
          title: issue.title,
          state: issue.state,
          url: issue.html_url,
          labels: labels || [],
          assignees: assignees || []
        }
      }
    }
  })
  
  // 列出 Issues
  server.registerTool({
    name: 'github_list_issues',
    description: `列出仓库的 issues，支持状态过滤和分页。
    
用途：
- 查看所有打开的 issues
- 检查已关闭的 issues
- 分页浏览大量 issues

返回信息：
- Issue 编号、标题、状态
- 创建时间和作者
- 标签和指派信息
- 分页信息`,
    inputSchema: zodToJsonSchema(ListIssuesSchema),
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    },
    async handler(args) {
      const { owner, repo, state, page, per_page } = ListIssuesSchema.parse(args)
      
      const issues = await client.get(`/repos/${owner}/${repo}/issues`, {
        state,
        page,
        per_page
      })
      
      const issueList = issues.map((issue: any) => ({
        number: issue.number,
        title: issue.title,
        state: issue.state,
        author: issue.user.login,
        created_at: issue.created_at,
        labels: issue.labels.map((l: any) => l.name),
        assignees: issue.assignees.map((a: any) => a.login),
        url: issue.html_url
      }))
      
      const markdown = `# Issues: ${owner}/${repo}

**状态**: ${state} | **页码**: ${page} | **每页**: ${per_page}

${issueList.map((issue: any) => `
## #${issue.number} ${issue.title}
- **状态**: ${issue.state}
- **作者**: ${issue.author}
- **创建时间**: ${issue.created_at}
${issue.labels.length > 0 ? `- **标签**: ${issue.labels.join(', ')}` : ''}
${issue.assignees.length > 0 ? `- **指派**: ${issue.assignees.join(', ')}` : ''}
- **URL**: ${issue.url}
`).join('\n---\n')}

**分页信息**:
- 当前页: ${page}
- 返回数量: ${issueList.length}
- 可能有更多: ${issueList.length === per_page ? '是' : '否'}
      `.trim()
      
      return {
        content: [{
          type: 'text',
          text: markdown
        }],
        structuredContent: {
          issues: issueList,
          pagination: {
            page,
            per_page,
            count: issueList.length,
            has_more: issueList.length === per_page
          }
        }
      }
    }
  })
  
  // 更新 Issue
  server.registerTool({
    name: 'github_update_issue',
    description: `更新 GitHub issue 的信息。
    
可更新内容：
- 标题和内容
- 状态（打开/关闭）
- 标签
- 指派人

注意：需要仓库的写权限`,
    inputSchema: zodToJsonSchema(UpdateIssueSchema),
    annotations: {
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    },
    async handler(args) {
      const { owner, repo, issue_number, ...updates } = UpdateIssueSchema.parse(args)
      
      const issue = await client.patch(
        `/repos/${owner}/${repo}/issues/${issue_number}`,
        updates
      )
      
      return {
        content: [{
          type: 'text',
          text: `✅ Issue #${issue.number} 更新成功！

**标题**: ${issue.title}
**状态**: ${issue.state}
**URL**: ${issue.html_url}`
        }],
        structuredContent: {
          number: issue.number,
          title: issue.title,
          state: issue.state,
          url: issue.html_url
        }
      }
    }
  })
}