Chúng Ta Sẽ Build Gì?#

GitHub Issue Manager MCP server — AI agent có thể:

• List issues trong repository
• Create issue với labels và assignees
• Search issues theo query
• Get issue details và comments
• Update issue status

Kiến Trúc MCP#

MCP dùng JSON-RPC 2.0 — protocol nhẹ, client gửi request, server trả response.

1
1. Client start server process (hoặc connect qua SSE)
2
2. Client gửi initialize → server trả capabilities
3
3. Client gửi initialized notification
4
4. Client gửi tools/list → server trả danh sách tools
5
5. Client gửi tools/call với tool name + args → server execute
6
6. Client terminate → server shutdown

Project Setup#

1
mkdir github-issue-mcp
2
cd github-issue-mcp
3

4
npm init -y
5
npm install @modelcontextprotocol/sdk zod
6
npm install -D typescript @types/node
7

8
mkdir src

tsconfig.json:

1
{
2
  "compilerOptions": {
3
    "target": "ES2022",
4
    "module": "Node16",
5
    "moduleResolution": "Node16",
6
    "outDir": "./build",
7
    "rootDir": "./src",
8
    "strict": true
9
  },
10
  "include": ["src/**/*"]
11
}

Entry Point#

src/index.ts:

1
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3

4
const server = new McpServer({
5
  name: "github-issue-manager",
6
  version: "1.0.0",
7
});
8

9
async function main() {
10
  const transport = new StdioServerTransport();
11
  await server.connect(transport);
12
  console.error("✅ Server running on stdio");
13
}
14

15
main().catch((error) => {
16
  console.error("Fatal error:", error);
17
  process.exit(1);
18
});

⚠️ Quan trọng: Dùng console.error(), không dùng console.log(). Với stdio server, stdout mang JSON-RPC protocol. console.log() làm hỏng messages.

5 Tools Chính#

1
server.tool(
2
  "list_issues",
3
  "List issues from a GitHub repo",
4
  {
5
    owner: z.string(),
6
    repo: z.string(),
7
    state: z.enum(["open", "closed", "all"]).default("open"),
8
    limit: z.number().min(1).max(100).default(20),
9
  },
10
  async ({ owner, repo, state, limit }) => {
11
    const issues = await github.listIssues(owner, repo, state, limit);
12
    return { content: [{ type: "text", text: formatted }] };
13
  },
14
);

Build & Test#

1
npm run build
2

3
export GITHUB_TOKEN="ghp_your_token_here"
4

5
# Test với MCP Inspector (GUI)
6
npx @modelcontextprotocol/inspector node build/index.js

Mở http://localhost:5173 → thấy 5 tools sẵn sàng.

1
{
2
  "mcpServers": {
3
    "github-issue-manager": {
4
      "command": "node",
5
      "args": ["/path/to/build/index.js"],
6
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
7
    }
8
  }
9
}

Kết Quả#

Bạn vừa build MCP server production-ready:

• 5 tools (list, get, create, update, search)
• MCP SDK + Zod type safety
• stdio transport
• Error handling
• Testable với Inspector và Claude Desktop

~250 dòng TypeScript. SDK handle hết JSON-RPC protocol.

Chuẩn Bị Cho Day 2#

Hiện tại server chỉ chạy stdio (cùng máy với client).

Ngày mai: Thêm Resources (đọc comments như content) và Prompts (templates cho issue workflows).

Series: Building an MCP Server from Scratch. Day 1: Setup và tools đầu tiên.