Building an MCP Server from Scratch — Day 1: Project Setup & Architecture (Node.js + TypeScript)

MCP servers are the hot new infrastructure. Every week there’s a new one: GitHub MCP, Figma MCP, PostgreSQL MCP, Playwright MCP. But most developers use them. Few build them.

This series changes that.

Over 5 posts, you’ll build a production-grade MCP server from absolute zero. Not a weather demo — a real server that does something useful. Each post ends with running code. By day 5, you’ll have a deployed, authenticated MCP server that you can plug into Claude Desktop, Cursor, or any MCP client.

What We’re Building#

A GitHub Issue Manager MCP server that an AI agent can use to:

List issues in a repository
Create issues with labels and assignees
Search issues by query
Get issue details and comments
Update issue status

Why this? Because every developer needs it, and it’s complex enough to demonstrate all three MCP capabilities: Tools, Resources, and Prompts.

Prerequisites#

Node.js 18+ and npm installed
TypeScript basics
A GitHub personal access token (fine-grained, issues:read, issues:write)
A terminal

That’s it. No prior MCP experience needed.

Part 1: Understanding the MCP Architecture#

Before writing code, understand what we’re building.

The Protocol#

MCP is built on JSON-RPC 2.0 — a lightweight protocol where the client sends requests and the server responds. Messages flow over a transport. The two standard transports are:

Three Capabilities#

An MCP server can expose three things:

Capability	Analogy	JSON-RPC Method
Tools	Functions the LLM can call	`tools/call`
Resources	Data the LLM can read	`resources/read`
Prompts	Templates the user can invoke	`prompts/get`

Server Lifecycle#

1
1. Client starts server process (or connects via SSE)
2
2. Client sends `initialize` → server responds with capabilities
3
3. Client sends `initialized` notification
4
4. Client sends `tools/list` → server responds with tool list
5
5. Client sends `tools/call` with tool name + args → server executes
6
6. Client terminates → server shuts down

That’s the protocol. You don’t need to implement it manually — the SDK handles JSON-RPC. But understanding it helps when things go wrong.

Part 2: Project Setup#

Step 1: Create the project#

1
# Create project directory
2
mkdir github-issue-mcp
3
cd github-issue-mcp
4

5
# Initialize npm
6
npm init -y
7

8
# Install the MCP SDK and dependencies
9
npm install @modelcontextprotocol/sdk zod
10
npm install -D typescript @types/node
11

12
# Create source directory
13
mkdir src

Step 2: Configure TypeScript#

Create tsconfig.json:

1
{
2
  "compilerOptions": {
3
    "target": "ES2022",
4
    "module": "Node16",
5
    "moduleResolution": "Node16",
6
    "outDir": "./build",
7
    "rootDir": "./src",
8
    "strict": true,
9
    "esModuleInterop": true,
10
    "skipLibCheck": true,
11
    "forceConsistentCasingInFileNames": true,
12
    "resolveJsonModule": true,
13
    "declaration": true
14
  },
15
  "include": ["src/**/*"],
16
  "exclude": ["node_modules", "build"]
17
}

Step 3: Update package.json#

1
{
2
  "name": "github-issue-mcp",
3
  "version": "1.0.0",
4
  "type": "module",
5
  "bin": {
6
    "github-issue-mcp": "./build/index.js"
7
  },
8
  "scripts": {
9
    "build": "tsc",
10
    "start": "node build/index.js",
11
    "dev": "tsc --watch"
12
  },
13
  "files": ["build"]
14
}

Part 3: Writing the Server#

Step 4: The entry point#

Create src/index.ts:

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

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

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

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

Critical: Notice console.error() not console.log(). For stdio servers, stdout carries the JSON-RPC protocol. Writing to stdout breaks everything. Always use console.error() or a logging library configured to stderr.

Step 5: Add the GitHub client#

Create src/github-client.ts:

1
const GITHUB_API_BASE = "https://api.github.com";
2

3
export interface GitHubIssue {
4
  number: number;
5
  title: string;
6
  state: "open" | "closed";
7
  body: string | null;
8
  labels: { name: string; color: string }[];
9
  assignees: { login: string }[];
10
  created_at: string;
11
  updated_at: string;
12
  html_url: string;
13
  user: { login: string };
14
  comments: number;
15
}
16

17
export interface CreateIssueInput {
18
  title: string;
19
  body?: string;
20
  labels?: string[];
21
  assignees?: string[];
22
}
23

24
export interface UpdateIssueInput {
25
  title?: string;
26
  body?: string;
27
  state?: "open" | "closed";
28
  labels?: string[];
29
  assignees?: string[];
30
}
31

32
export interface SearchResult {
33
  issues: GitHubIssue[];
34
  total_count: number;
35
}
36

37
export class GitHubClient {
38
  private token: string;
39
  private headers: Record<string, string>;
40

41
  constructor(token: string) {
42
    this.token = token;
43
    this.headers = {
44
      Authorization: `Bearer ${token}`,
45
      Accept: "application/vnd.github+json",
46
      "User-Agent": "github-issue-mcp-server/1.0",
47
      "X-GitHub-Api-Version": "2022-11-28",
48
    };
49
  }
50

51
  // GET request
52
  private async get<T>(url: string): Promise<T> {
53
    const response = await fetch(url, { headers: this.headers });
54
    if (!response.ok) {
55
      throw new Error(`GitHub API error: ${response.status} ${response.statusText}`);
56
    }
57
    return response.json() as Promise<T>;
58
  }
59

60
  // POST request
61
  private async post<T>(url: string, body: unknown): Promise<T> {
62
    const response = await fetch(url, {
63
      method: "POST",
64
      headers: { ...this.headers, "Content-Type": "application/json" },
65
      body: JSON.stringify(body),
66
    });
67
    if (!response.ok) {
68
      const errorBody = await response.text();
69
      throw new Error(`GitHub API error ${response.status}: ${errorBody}`);
70
    }
71
    return response.json() as Promise<T>;
72
  }
73

74
  // PATCH request
75
  private async patch<T>(url: string, body: unknown): Promise<T> {
76
    const response = await fetch(url, {
77
      method: "PATCH",
78
      headers: { ...this.headers, "Content-Type": "application/json" },
79
      body: JSON.stringify(body),
80
    });
81
    if (!response.ok) {
82
      const errorBody = await response.text();
83
      throw new Error(`GitHub API error ${response.status}: ${errorBody}`);
84
    }
85
    return response.json() as Promise<T>;
86
  }
87

88
  // Get issues for a repository
89
  async listIssues(owner: string, repo: string, state: "open" | "closed" | "all" = "open", limit = 20): Promise<GitHubIssue[]> {
90
    const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/issues?state=${state}&per_page=${limit}&sort=updated&direction=desc`;
91
    const data = await this.get<GitHubIssue[]>(url);
92
    return data;
93
  }
94

95
  // Create an issue
96
  async createIssue(owner: string, repo: string, input: CreateIssueInput): Promise<GitHubIssue> {
97
    const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/issues`;
98
    return this.post<GitHubIssue>(url, input);
99
  }
100

101
  // Get a single issue
102
  async getIssue(owner: string, repo: string, issueNumber: number): Promise<GitHubIssue> {
103
    const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/issues/${issueNumber}`;
104
    return this.get<GitHubIssue>(url);
105
  }
106

107
  // Update an issue
108
  async updateIssue(owner: string, repo: string, issueNumber: number, input: UpdateIssueInput): Promise<GitHubIssue> {
109
    const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/issues/${issueNumber}`;
110
    return this.patch<GitHubIssue>(url, input);
111
  }
112

113
  // Search issues
114
  async searchIssues(query: string, limit = 10): Promise<SearchResult> {
115
    const url = `${GITHUB_API_BASE}/search/issues?q=${encodeURIComponent(query)}&per_page=${limit}`;
116
    const data = await this.get<{ items: GitHubIssue[]; total_count: number }>(url);
117
    return { issues: data.items, total_count: data.total_count };
118
  }
119
}

Step 6: Register the tools#

Back in src/index.ts, add the tool registrations:

1
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
import { z } from "zod";
4
import { GitHubClient } from "./github-client.js";
5

6
// Initialize
7
const GITHUB_TOKEN = process.env.GITHUB_TOKEN;
8
if (!GITHUB_TOKEN) {
9
  console.error("GITHUB_TOKEN environment variable is required");
10
  process.exit(1);
11
}
12

13
const server = new McpServer({
14
  name: "github-issue-manager",
15
  version: "1.0.0",
16
});
17

18
const github = new GitHubClient(GITHUB_TOKEN);
19

20
// ============================================================
21
// Tool 1: List issues in a repository
22
// ============================================================
23
server.tool(
24
  "list_issues",
25
  "List issues from a GitHub repository, filtered by state",
26
  {
27
    owner: z.string().describe("Repository owner (user or organization)"),
28
    repo: z.string().describe("Repository name"),
29
    state: z.enum(["open", "closed", "all"]).default("open").describe("Issue state filter"),
30
    limit: z.number().min(1).max(100).default(20).describe("Maximum issues to return"),
31
  },
32
  async ({ owner, repo, state, limit }) => {
33
    try {
34
      const issues = await github.listIssues(owner, repo, state, limit);
35

36
      if (issues.length === 0) {
37
        return {
38
          content: [{ type: "text", text: `No ${state} issues found in ${owner}/${repo}.` }],
39
        };
40
      }
41

42
      const formatted = issues.map((issue) => {
43
        const labels = issue.labels.map((l) => `[${l.name}]`).join(" ");
44
        const assignees = issue.assignees.map((a) => `@${a.login}`).join(", ");
45
        return [
46
          `#${issue.number}: ${issue.title}`,
47
          `  State: ${issue.state} | Created: ${issue.created_at.slice(0, 10)} | Comments: ${issue.comments}`,
48
          `  Labels: ${labels || "(none)"}`,
49
          `  Assignees: ${assignees || "(none)"}`,
50
          `  URL: ${issue.html_url}`,
51
        ].join("\n");
52
      });
53

54
      return {
55
        content: [
56
          {
57
            type: "text",
58
            text: `## Issues in ${owner}/${repo} (${state})\n\n${formatted.join("\n\n")}`,
59
          },
60
        ],
61
      };
62
    } catch (error) {
63
      return {
64
        content: [{ type: "text", text: `Error listing issues: ${error}` }],
65
        isError: true,
66
      };
67
    }
68
  },
69
);
70

71
// ============================================================
72
// Tool 2: Get issue details
73
// ============================================================
74
server.tool(
75
  "get_issue",
76
  "Get detailed information about a single GitHub issue",
77
  {
78
    owner: z.string().describe("Repository owner"),
79
    repo: z.string().describe("Repository name"),
80
    issue_number: z.number().int().positive().describe("Issue number"),
81
  },
82
  async ({ owner, repo, issue_number }) => {
83
    try {
84
      const issue = await github.getIssue(owner, repo, issue_number);
85

86
      const labels = issue.labels.map((l) => `[${l.name}]`).join(" ");
87
      const assignees = issue.assignees.map((a) => `@${a.login}`).join(", ");
88

89
      const details = [
90
        `# ${issue.title}`,
91
        `**Issue #${issue.number}** | **State:** ${issue.state}`,
92
        `**Author:** @${issue.user.login} | **Created:** ${issue.created_at} | **Updated:** ${issue.updated_at}`,
93
        `**Labels:** ${labels || "(none)"}`,
94
        `**Assignees:** ${assignees || "(none)"}`,
95
        `**Comments:** ${issue.comments}`,
96
        `**URL:** ${issue.html_url}`,
97
        "",
98
        `---`,
99
        issue.body || "*No description provided*",
100
      ].join("\n");
101

102
      return {
103
        content: [{ type: "text", text: details }],
104
      };
105
    } catch (error) {
106
      return {
107
        content: [{ type: "text", text: `Error fetching issue: ${error}` }],
108
        isError: true,
109
      };
110
    }
111
  },
112
);
113

114
// ============================================================
115
// Tool 3: Create an issue
116
// ============================================================
117
server.tool(
118
  "create_issue",
119
  "Create a new issue in a GitHub repository",
120
  {
121
    owner: z.string().describe("Repository owner"),
122
    repo: z.string().describe("Repository name"),
123
    title: z.string().min(1).max(256).describe("Issue title"),
124
    body: z.string().optional().describe("Issue body/description (Markdown)"),
125
    labels: z.array(z.string()).optional().describe("Labels to apply"),
126
    assignees: z.array(z.string()).optional().describe("Usernames to assign"),
127
  },
128
  async ({ owner, repo, title, body, labels, assignees }) => {
129
    try {
130
      const issue = await github.createIssue(owner, repo, {
131
        title,
132
        body,
133
        labels,
134
        assignees,
135
      });
136

137
      return {
138
        content: [
139
          {
140
            type: "text",
141
            text: [
142
              `✅ Issue created successfully!`,
143
              `**#${issue.number}:** ${issue.title}`,
144
              `**URL:** ${issue.html_url}`,
145
            ].join("\n"),
146
          },
147
        ],
148
      };
149
    } catch (error) {
150
      return {
151
        content: [{ type: "text", text: `Error creating issue: ${error}` }],
152
        isError: true,
153
      };
154
    }
155
  },
156
);
157

158
// ============================================================
159
// Tool 4: Update an issue
160
// ============================================================
161
server.tool(
162
  "update_issue",
163
  "Update an existing issue (change title, body, labels, assignees, or close)",
164
  {
165
    owner: z.string().describe("Repository owner"),
166
    repo: z.string().describe("Repository name"),
167
    issue_number: z.number().int().positive().describe("Issue number to update"),
168
    title: z.string().max(256).optional().describe("New title"),
169
    body: z.string().optional().describe("New body"),
170
    state: z.enum(["open", "closed"]).optional().describe("New state"),
171
    labels: z.array(z.string()).optional().describe("New labels"),
172
    assignees: z.array(z.string()).optional().describe("New assignees"),
173
  },
174
  async ({ owner, repo, issue_number, title, body, state, labels, assignees }) => {
175
    try {
176
      const issue = await github.updateIssue(owner, repo, issue_number, {
177
        title,
178
        body,
179
        state,
180
        labels,
181
        assignees,
182
      });
183

184
      return {
185
        content: [
186
          {
187
            type: "text",
188
            text: [
189
              `✅ Issue #${issue_number} updated!`,
190
              `**#${issue.number}:** ${issue.title}`,
191
              `**State:** ${issue.state}`,
192
              `**URL:** ${issue.html_url}`,
193
            ].join("\n"),
194
          },
195
        ],
196
      };
197
    } catch (error) {
198
      return {
199
        content: [{ type: "text", text: `Error updating issue: ${error}` }],
200
        isError: true,
201
      };
202
    }
203
  },
204
);
205

206
// ============================================================
207
// Tool 5: Search issues
208
// ============================================================
209
server.tool(
210
  "search_issues",
211
  "Search GitHub issues across repositories using a query",
212
  {
213
    query: z.string().min(1).describe("Search query (supports GitHub search syntax like repo:owner/name is:open)"),
214
    limit: z.number().min(1).max(50).default(10).describe("Maximum results"),
215
  },
216
  async ({ query, limit }) => {
217
    try {
218
      const result = await github.searchIssues(query, limit);
219

220
      if (result.issues.length === 0) {
221
        return {
222
          content: [{ type: "text", text: `No issues found for query: "${query}"` }],
223
        };
224
      }
225

226
      const formatted = result.issues.map((issue) => {
227
        // Extract repo info from URL: https://github.com/owner/repo/issues/N
228
        const repoHint = issue.html_url.replace("https://github.com/", "").replace(/\/issues\/\d+/, "");
229
        return [
230
          `#${issue.number} (${repoHint}): ${issue.title}`,
231
          `  State: ${issue.state} | Updated: ${issue.updated_at.slice(0, 10)}`,
232
          `  URL: ${issue.html_url}`,
233
        ].join("\n");
234
      });
235

236
      return {
237
        content: [
238
          {
239
            type: "text",
240
            text: `## Search Results (${result.total_count} total)\n\n${formatted.join("\n\n")}`,
241
          },
242
        ],
243
      };
244
    } catch (error) {
245
      return {
246
        content: [{ type: "text", text: `Error searching issues: ${error}` }],
247
        isError: true,
248
      };
249
    }
250
  },
251
);
252

253
// ============================================================
254
// Main
255
// ============================================================
256
async function main() {
257
  const transport = new StdioServerTransport();
258
  await server.connect(transport);
259
  console.error("✅ GitHub Issue Manager MCP Server running on stdio");
260
}
261

262
main().catch((error) => {
263
  console.error("Fatal error:", error);
264
  process.exit(1);
265
});

Part 4: Build and Test#

Step 7: Build it#

1
npm run build

This compiles TypeScript to JavaScript in the build/ directory.

Step 8: Set your token#

1
export GITHUB_TOKEN="ghp_your_token_here"

Step 9: Test locally with the MCP Inspector#

The MCP SDK includes an inspector tool — a GUI for testing your server:

1
# Run the inspector, pointing at your server
2
npx @modelcontextprotocol/inspector node build/index.js

Open http://localhost:5173 in your browser. You’ll see:

Server Info — shows your tool list
Tools tab — click any tool to test it
Request/Response — raw JSON-RPC messages

Try calling list_issues with owner: "ptminh-kmp", repo: "ptminh-kmp.github.io":

1
{
2
  "owner": "ptminh-kmp",
3
  "repo": "ptminh-kmp.github.io",
4
  "state": "open",
5
  "limit": 10
6
}

The inspector sends a JSON-RPC request, your server processes it, and the response shows up in the UI.

Step 10: Test with `curl` (SSE transport)#

If you want to get your hands dirty with the raw protocol:

1
// Add this to your server temporarily to see raw messages
2
server.connect(transport).then(() => {
3
  console.error("Server is connected and listening for messages");
4
  // The SDK handles everything automatically
5
});

The JSON-RPC messages look like this:

1
// Client → Server (initialize)
2
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}
3

4
// Server → Client (initialize result)
5
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"github-issue-manager","version":"1.0.0"}}}
6

7
// Client → Server (tools/list)
8
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
9

10
// Server → Client (tools/list result with your 5 tools)
11
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"list_issues","description":"List issues from a GitHub repository, filtered by state","inputSchema":{"type":"object","properties":{"owner":...}}}}]}}

Part 5: Connect to Claude Desktop#

Step 11: Configure Claude Desktop#

Edit ~/Library/Application\ Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop. You should see the hammer icon in the corner — that means MCP tools are loaded. Ask Claude:

“Show me the open issues in ptminh-kmp/ptminh-kmp.github.io”

Claude will call your list_issues tool and show the results.

The Result#

You’ve just built a production-ready MCP server that:

Exposes 5 tools (list, get, create, update, search — GitHub issues)
Uses the official MCP SDK with Zod schemas for type-safe parameter validation
Connects over stdio transport
Handles errors gracefully
Is testable with MCP Inspector and Claude Desktop

The entire server is about 250 lines of TypeScript. The SDK handles all the JSON-RPC protocol. You just write tool functions.

What You Learned#

Concept	In Practice
MCP Architecture	JSON-RPC over stdio/SSE
Server Lifecycle	initialize → list tools → call tools → shutdown
Tool Registration	`server.tool(name, description, schema, handler)`
Parameter Validation	Zod schemas define input types
Error Handling	Return `{ isError: true }` for failures
Testing	MCP Inspector CLI tool
Client Integration	Claude Desktop config

Prepare for Day 2#

Right now our server only communicates via stdio. That means the MCP server and the client must be on the same machine.

Tomorrow: We’ll add Resources (read issue comments as content) and Prompts (templates for common issue workflows). Then we’ll test everything with the MCP Inspector.

Day	Topic	Status
1	Setup & Architecture	✅ Done
2	Resources, Prompts & Advanced Tools	Coming next
3	SSE Transport & Remote Deployment	—
4	Authentication & Production Hardening	—
5	Testing, Publishing & Ecosystem	—

Series: Building an MCP Server from Scratch. Day 1: Project setup, architecture, first 5 tools, and testing.