1
┌──────────────┐                  ┌──────────────┐
2
│   Client     │  1. GET /sse     │    Server    │
3
│ (Claude      │ ──────────────►  │  (Express.js)│
4
│  Desktop,    │                  │              │
5
│  Inspector)  │  2. POST /msg    │  Node.js     │
6
│              │ ◄──────────────  │              │
7
│              │  3. Event stream │              │
8
│              │ ◄══════════════  │              │
9
└──────────────┘                  └──────────────┘

1
// src/sse-server.ts — Manages SSE transport for multiple concurrent clients
2

3
import express from "express";
4
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
5
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
6

7
export function createSSEServer(mcpServer: McpServer, port: number = 3001) {
8
  const app = express();
9

10
  // ──── Track active sessions ────
11
  // Each SSE connection gets a unique session ID.
12
  // The transport stores the response object for streaming events back.
13
  const transports: Map<string, SSEServerTransport> = new Map();
14

15
  // ──── SSE connection endpoint ────
16
  // The client opens a GET /sse stream. The server keeps this connection
17
  // alive and pushes events (tool results, resource content, etc.) over it.
18
  app.get("/sse", async (req: express.Request, res: express.Response) => {
19
    console.error(`[SSE] New connection from ${req.ip}`);
20

21
    // Create a transport for this connection.
22
    // The first argument is the path where the client will POST messages.
23
    // The SDK appends ?sessionId=xxx automatically.
24
    const transport = new SSEServerTransport("/messages", res);
25

26
    // Store it by session ID so POST /messages can find it.
27
    transports.set(transport.sessionId, transport);
28
    console.error(`[SSE] Session created: ${transport.sessionId}`);
29
    console.error(`[SSE] Active connections: ${transports.size}`);
30

31
    // When the client disconnects or the stream closes, clean up.
32
    res.on("close", () => {
33
      transports.delete(transport.sessionId);
34
      console.error(`[SSE] Session closed: ${transport.sessionId}`);
35
      console.error(`[SSE] Active connections: ${transports.size}`);
36
    });
37

38
    try {
39
      // Connect the MCP server to this transport.
40
      // This triggers the initialization handshake:
41
      //   Client sends initialize → Server responds with capabilities
42
      //   Client sends initialized notification
43
      //   Client sends tools/list → Server responds
44
      await mcpServer.connect(transport);
45
    } catch (error) {
46
      console.error(`[SSE] Failed to connect transport: ${error}`);
47
      res.status(500).end();
48
    }
49
  });
50

51
  // ──── Message endpoint ────
52
  // The client sends JSON-RPC messages as HTTP POST requests here.
53
  // The session ID (from the SSE endpoint event) tells us which transport to use.
54
  app.post("/messages", express.json(), async (req: express.Request, res: express.Response) => {
55
    const sessionId = req.query.sessionId as string;
56
    console.error(`[MSG] POST from session: ${sessionId}`);
57

58
    const transport = transports.get(sessionId);
59

60
    if (!transport) {
61
      console.error(`[MSG] Session not found: ${sessionId}`);
62
      res.status(404).json({ error: "Session not found. Make sure you connect to /sse first." });
63
      return;
64
    }
65

66
    try {
67
      // Forward the POST body as an MCP protocol message.
68
      // The transport handles parsing JSON-RPC and sending the response
69
      // back through the SSE stream.
70
      await transport.handlePostMessage(req, res);
71
      console.error(`[MSG] Handled successfully for session: ${sessionId}`);
72
    } catch (error) {
73
      console.error(`[MSG] Error handling message: ${error}`);
74
      // Don't send another response — handlePostMessage already did
75
    }
76
  });
77

78
  // ──── Health check endpoint ────
79
  // Useful for Docker HEALTHCHECK, load balancers, and monitoring.
80
  app.get("/health", (req: express.Request, res: express.Response) => {
81
    res.json({
82
      status: "ok",
83
      uptime: process.uptime(),
84
      activeConnections: transports.size,
85
      serverName: "github-issue-manager",
86
      serverVersion: "1.0.1",
87
      timestamp: new Date().toISOString(),
88
    });
89
  });
90

91
  // ──── Start listening ────
92
  return app.listen(port, () => {
93
    console.error(`✅ MCP SSE server listening on port ${port}`);
94
    console.error(`   SSE endpoint: http://localhost:${port}/sse`);
95
    console.error(`   Message endpoint: http://localhost:${port}/messages`);
96
    console.error(`   Health check: http://localhost:${port}/health`);
97
  });
98
}

1
// src/server.ts — SSE-based MCP server entry point
2
// This replaces src/index.ts as the main entry point when running in SSE mode.
3

4
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
5
import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
6
import { z } from "zod";
7
import { GitHubClient } from "./github-client.js";
8
import { createSSEServer } from "./sse-server.js";
9

10
// ════════════════════════════════════════════════════════════
11
// CONFIGURATION
12
// ════════════════════════════════════════════════════════════
13

14
const GITHUB_TOKEN = process.env.GITHUB_TOKEN;
15
if (!GITHUB_TOKEN) {
16
  console.error("❌ GITHUB_TOKEN environment variable is required");
17
  console.error("   Get one at: https://github.com/settings/tokens");
18
  console.error("   Required scopes: issues:read, issues:write");
19
  process.exit(1);
20
}
21

22
const PORT = parseInt(process.env.PORT || "3001", 10);
23

24
// ════════════════════════════════════════════════════════════
25
// INITIALIZE
26
// ════════════════════════════════════════════════════════════
27

28
const server = new McpServer({
29
  name: "github-issue-manager",
30
  version: "1.0.1",
31
});
32

33
const github = new GitHubClient(GITHUB_TOKEN);
34
const GITHUB_API_BASE = "https://api.github.com";
35

36
// Mask token for logging — show first 8 + last 4 chars only
37
const maskedToken = `${GITHUB_TOKEN.slice(0, 8)}...${GITHUB_TOKEN.slice(-4)}`;
38
console.error(`🚀 Starting GitHub Issue Manager v1.0.1`);
39
console.error(`   Token: ${maskedToken}`);
40
console.error(`   Port: ${PORT}`);
41

42
// ════════════════════════════════════════════════════════════
43
// HELPERS
44
// ════════════════════════════════════════════════════════════
45

46
function parseLinkHeader(link: string | null) {
47
  if (!link) return {};
48
  const result: Record<string, string> = {};
49
  const parts = link.split(", ");
50
  for (const part of parts) {
51
    const match = part.match(/<([^>]+)>;\s*rel="([^"]+)"/);
52
    if (match) result[match[2]] = match[1];
53
  }
54
  return result;
55
}
56

57
async function githubFetch(url: string) {
58
  const response = await fetch(url, {
59
    headers: {
60
      Authorization: `Bearer ${GITHUB_TOKEN}`,
61
      Accept: "application/vnd.github+json",
62
      "User-Agent": "github-issue-mcp-server/1.0",
63
      "X-GitHub-Api-Version": "2022-11-28",
64
    },
65
  });
66
  return response;
67
}
68

69
// ════════════════════════════════════════════════════════════
70
// TOOLS (7 tools from Day 1 + Day 2)
71
// ════════════════════════════════════════════════════════════
72

73
// Tool 1: List issues
74
server.tool(
75
  "list_issues",
76
  "List issues from a GitHub repository, filtered by state",
77
  {
78
    owner: z.string().describe("Repository owner (user or organization)"),
79
    repo: z.string().describe("Repository name"),
80
    state: z.enum(["open", "closed", "all"]).default("open").describe("Issue state filter"),
81
    limit: z.number().min(1).max(100).default(20).describe("Maximum issues to return"),
82
  },
83
  async ({ owner, repo, state, limit }) => {
84
    try {
85
      const issues = await github.listIssues(owner, repo, state, limit);
86
      if (issues.length === 0) {
87
        return { content: [{ type: "text", text: `No ${state} issues found in ${owner}/${repo}.` }] };
88
      }
89
      const formatted = issues.map((issue) => {
90
        const labels = issue.labels.map((l) => `[${l.name}]`).join(" ");
91
        const assignees = issue.assignees.map((a) => `@${a.login}`).join(", ");
92
        return [
93
          `#${issue.number}: ${issue.title}`,
94
          `  State: ${issue.state} | Created: ${issue.created_at.slice(0, 10)} | Comments: ${issue.comments}`,
95
          `  Labels: ${labels || "(none)"}`,
96
          `  Assignees: ${assignees || "(none)"}`,
97
          `  URL: ${issue.html_url}`,
98
        ].join("\n");
99
      });
100
      return { content: [{ type: "text", text: `## Issues in ${owner}/${repo} (${state})\n\n${formatted.join("\n\n")}` }] };
101
    } catch (error) {
102
      return { content: [{ type: "text", text: `Error listing issues: ${error}` }], isError: true };
103
    }
104
  },
105
);
106

107
// Tool 2: Get single issue
108
server.tool(
109
  "get_issue",
110
  "Get detailed information about a single GitHub issue by number",
111
  {
112
    owner: z.string().describe("Repository owner"),
113
    repo: z.string().describe("Repository name"),
114
    issue_number: z.number().int().positive().describe("Issue number (e.g., 42)"),
115
  },
116
  async ({ owner, repo, issue_number }) => {
117
    try {
118
      const issue = await github.getIssue(owner, repo, issue_number);
119
      const labels = issue.labels.map((l) => `[${l.name}]`).join(" ");
120
      const assignees = issue.assignees.map((a) => `@${a.login}`).join(", ");
121
      const details = [
122
        `# ${issue.title}`,
123
        `**Issue #${issue.number}** | **State:** ${issue.state}`,
124
        `**Author:** @${issue.user.login} | **Created:** ${issue.created_at} | **Updated:** ${issue.updated_at}`,
125
        `**Labels:** ${labels || "(none)"}`,
126
        `**Assignees:** ${assignees || "(none)"}`,
127
        `**Comments:** ${issue.comments}`,
128
        `**URL:** ${issue.html_url}`,
129
        ``,
130
        `---`,
131
        issue.body || "*No description provided*",
132
      ].join("\n");
133
      return { content: [{ type: "text", text: details }] };
134
    } catch (error) {
135
      return { content: [{ type: "text", text: `Error fetching issue: ${error}` }], isError: true };
136
    }
137
  },
138
);
139

140
// Tool 3: Create issue
141
server.tool(
142
  "create_issue",
143
  "Create a new issue in a GitHub repository",
144
  {
145
    owner: z.string().describe("Repository owner"),
146
    repo: z.string().describe("Repository name"),
147
    title: z.string().min(1).max(256).describe("Issue title"),
148
    body: z.string().optional().describe("Issue body (Markdown supported)"),
149
    labels: z.array(z.string()).optional().describe("Labels to apply (e.g., ['bug', 'priority'])"),
150
    assignees: z.array(z.string()).optional().describe("Usernames to assign (e.g., ['user1'])"),
151
  },
152
  async ({ owner, repo, title, body, labels, assignees }) => {
153
    try {
154
      const issue = await github.createIssue(owner, repo, { title, body, labels, assignees });
155
      return { content: [{ type: "text", text: `✅ Issue created!\n**#${issue.number}:** ${issue.title}\n**URL:** ${issue.html_url}` }] };
156
    } catch (error) {
157
      return { content: [{ type: "text", text: `Error: ${error}` }], isError: true };
158
    }
159
  },
160
);
161

162
// Tool 4: Update issue
163
server.tool(
164
  "update_issue",
165
  "Update an existing issue — change title, body, labels, assignees, or close/reopen",
166
  {
167
    owner: z.string().describe("Repository owner"),
168
    repo: z.string().describe("Repository name"),
169
    issue_number: z.number().int().positive(),
170
    title: z.string().max(256).optional(),
171
    body: z.string().optional(),
172
    state: z.enum(["open", "closed"]).optional().describe("Close or reopen the issue"),
173
    labels: z.array(z.string()).optional(),
174
    assignees: z.array(z.string()).optional(),
175
  },
176
  async ({ owner, repo, issue_number, title, body, state, labels, assignees }) => {
177
    try {
178
      const issue = await github.updateIssue(owner, repo, issue_number, { title, body, state, labels, assignees });
179
      return { content: [{ type: "text", text: `✅ Issue #${issue_number} updated!\n**#${issue.number}:** ${issue.title}\n**State:** ${issue.state}\n**URL:** ${issue.html_url}` }] };
180
    } catch (error) {
181
      return { content: [{ type: "text", text: `Error: ${error}` }], isError: true };
182
    }
183
  },
184
);
185

186
// Tool 5: Search issues
187
server.tool(
188
  "search_issues",
189
  "Search GitHub issues across repositories using GitHub search syntax",
190
  {
191
    query: z.string().min(1).describe("GitHub search query (e.g., 'repo:owner/name is:open bug')"),
192
    limit: z.number().min(1).max(50).default(10),
193
  },
194
  async ({ query, limit }) => {
195
    try {
196
      const result = await github.searchIssues(query, limit);
197
      if (result.issues.length === 0) return { content: [{ type: "text", text: `No issues found for: "${query}"` }] };
198
      const formatted = result.issues.map((issue) => {
199
        const repoHint = issue.html_url.replace("https://github.com/", "").replace(/\/issues\/\d+/, "");
200
        return `#${issue.number} (${repoHint}): ${issue.title}\n  ${issue.state} | ${issue.html_url}`;
201
      }).join("\n\n");
202
      return { content: [{ type: "text", text: `## Results (${result.total_count} total)\n\n${formatted}` }] };
203
    } catch (error) {
204
      return { content: [{ type: "text", text: `Error: ${error}` }], isError: true };
205
    }
206
  },
207
);
208

209
// Tool 6: Paginated listing
210
server.tool(
211
  "list_issues_paginated",
212
  "Browse issues with pagination — useful for repositories with many issues",
213
  {
214
    owner: z.string(), repo: z.string(),
215
    state: z.enum(["open", "closed", "all"]).default("open"),
216
    page: z.number().int().min(1).default(1),
217
    per_page: z.number().int().min(1).max(100).default(30),
218
    sort: z.enum(["created", "updated", "comments"]).default("updated"),
219
    direction: z.enum(["asc", "desc"]).default("desc"),
220
  },
221
  async ({ owner, repo, state, page, per_page, sort, direction }) => {
222
    try {
223
      const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/issues?${new URLSearchParams({ state, page: String(page), per_page: String(per_page), sort, direction })}`;
224
      const response = await githubFetch(url);
225
      if (!response.ok) throw new Error(`GitHub API: ${response.status}`);
226
      const issues: any[] = await response.json() as any[];
227
      const pagination = parseLinkHeader(response.headers.get("link"));
228
      if (issues.length === 0) return { content: [{ type: "text", text: `No issues on page ${page} of ${owner}/${repo}.` }] };
229
      const formatted = issues.map((i: any) => `#${i.number}: ${i.title}\n  ${i.state} | 💬 ${i.comments}\n  ${i.html_url}`).join("\n\n");
230
      let header = `## Issues in ${owner}/${repo} (page ${page})`;
231
      if (pagination.last) {
232
        const lastPage = parseInt(new URL(pagination.last).searchParams.get("page") || "1");
233
        header += `\n📄 Page ${page} of ${lastPage}`;
234
      }
235
      return { content: [{ type: "text", text: `${header}\n\n${formatted}` }] };
236
    } catch (error) {
237
      return { content: [{ type: "text", text: `Error: ${error}` }], isError: true };
238
    }
239
  },
240
);
241

242
// Tool 7: Batch label
243
server.tool(
244
  "batch_label_issues",
245
  "Apply labels to multiple issues at once — useful during triage sessions",
246
  {
247
    owner: z.string(), repo: z.string(),
248
    issue_numbers: z.array(z.number().int().positive()).min(1).max(25),
249
    labels: z.array(z.string()).min(1).max(10),
250
  },
251
  async ({ owner, repo, issue_numbers, labels }) => {
252
    const results = [];
253
    for (const n of issue_numbers) {
254
      try { await github.updateIssue(owner, repo, n, { labels }); results.push(`  ✅ #${n}`); }
255
      catch (e) { results.push(`  ❌ #${n}: ${e}`); }
256
    }
257
    return { content: [{ type: "text", text: `## Batch Label: ${labels.join(", ")}\n${results.join("\n")}` }] };
258
  },
259
);
260

261
// ════════════════════════════════════════════════════════════
262
// RESOURCES (3 resources from Day 2)
263
// ════════════════════════════════════════════════════════════
264

265
server.resource(
266
  "issue-detail",
267
  new ResourceTemplate("issue://{owner}/{repo}/{number}", { list: undefined }),
268
  async (uri, { owner, repo, number }) => {
269
    const issue = await github.getIssue(owner as string, repo as string, parseInt(number as string));
270
    const labels = issue.labels.map((l) => `\`${l.name}\``).join(" ");
271
    const markdown = [
272
      `# ${issue.title}`,
273
      `**Status:** ${issue.state === "open" ? "🟢 Open" : "🔴 Closed"}`,
274
      `**Author:** @${issue.user.login} | **Labels:** ${labels || "*none*"}`,
275
      `**URL:** ${issue.html_url}`,
276
      `---`,
277
      issue.body || "*No description*",
278
    ].join("\n");
279
    return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: markdown }] };
280
  },
281
);
282

283
server.resource(
284
  "issue-comments",
285
  new ResourceTemplate("issue://{owner}/{repo}/{number}/comments", { list: undefined }),
286
  async (uri, { owner, repo, number }) => {
287
    const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/issues/${number}/comments`;
288
    const response = await githubFetch(url);
289
    const comments: any[] = await response.json() as any[];
290
    if (comments.length === 0) return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: `# Comments\n\n*No comments yet.*` }] };
291
    const formatted = comments.map((c: any) => `---\n**@${c.user.login}** on ${new Date(c.created_at).toLocaleDateString()}\n\n${c.body || "*No text*"}`).join("\n\n");
292
    return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: `# Comments for #${number}\n\n${formatted}` }] };
293
  },
294
);
295

296
server.resource(
297
  "open-issues",
298
  new ResourceTemplate("issue://{owner}/{repo}/open", { list: undefined }),
299
  async (uri, { owner, repo }) => {
300
    const issues = await github.listIssues(owner as string, repo as string, "open");
301
    if (issues.length === 0) return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: `✨ No open issues!` }] };
302
    const list = issues.map((i) => `- [#${i.number}](${i.html_url}): ${i.title}`).join("\n");
303
    return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: `# Open Issues (${issues.length})\n\n${list}` }] };
304
  },
305
);
306

307
// ════════════════════════════════════════════════════════════
308
// PROMPTS (3 prompts from Day 2)
309
// ════════════════════════════════════════════════════════════
310

311
server.prompt(
312
  "triage-issue",
313
  "Analyze a GitHub issue: severity, labels, priority, assignee, next steps",
314
  { owner: z.string(), repo: z.string(), issue_number: z.number() },
315
  ({ owner, repo, issue_number }) => ({
316
    messages: [{
317
      role: "user",
318
      content: { type: "text", text: [
319
        `Please triage issue #${issue_number} in ${owner}/${repo}.`,
320
        `Use get_issue to fetch details, then analyze:`,
321
        `1. Severity — Bug, feature, or question? If bug: critical/major/minor?`,
322
        `2. Labels — What labels fit?`,
323
        `3. Priority — Now, this sprint, or backlog?`,
324
        `4. Assignee — Who should look?`,
325
        `5. Next steps — What info is missing?`,
326
      ].join("\n") },
327
    }],
328
  }),
329
);
330

331
server.prompt(
332
  "weekly-summary",
333
  "Summarize this week's issue activity for a repository",
334
  { owner: z.string(), repo: z.string() },
335
  ({ owner, repo }) => ({
336
    messages: [{
337
      role: "user",
338
      content: { type: "text", text: [
339
        `Weekly summary for ${owner}/${repo}.`,
340
        `1. Read open issues resource`,
341
        `2. Group: 🔥 New this week | 📝 Updated | 🧊 Stale (30d+)`,
342
        `3. Count + list for each group`,
343
      ].join("\n") },
344
    }],
345
  }),
346
);
347

348
server.prompt(
349
  "bug-report-template",
350
  "Pre-formatted bug report template for filing an issue",
351
  {},
352
  () => ({
353
    messages: [{
354
      role: "user",
355
      content: { type: "text", text: [
356
        `Use this template to create a bug report:`,
357
        `## Bug Report`,
358
        `### Describe the Bug`,
359
        `### To Reproduce`,
360
        `### Expected Behavior`,
361
        `### Screenshots`,
362
        `### Environment`,
363
      ].join("\n") },
364
    }],
365
  }),
366
);
367

368
// ════════════════════════════════════════════════════════════
369
// START SERVER
370
// ════════════════════════════════════════════════════════════
371

372
createSSEServer(server, PORT);

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

1
🚀 Starting GitHub Issue Manager v1.0.1
2
   Token: ghp_abc...xyz
3
   Port: 3001
4
✅ MCP SSE server listening on port 3001
5
   SSE endpoint: http://localhost:3001/sse
6
   Message endpoint: http://localhost:3001/messages
7
   Health check: http://localhost:3001/health

1
{
2
  "mcpServers": {
3
    "github-issue-manager": {
4
      "type": "sse",
5
      "url": "https://mcp.example.com/sse"
6
    }
7
  }
8
}