@arii/boomtick-mcp 0.6.1 → 0.7.0

package/src/mcp/definitions.ts

@@ -1,35 +1,70 @@
 import { Tool, Prompt, Resource, ResourceTemplate } from "@modelcontextprotocol/sdk/types.js";
 import {
   HealthCheckInputJsonSchema,
+  HealthCheckResponseJsonSchema,
   SearchPRsInputJsonSchema,
+  SearchPRsResponseJsonSchema,
   GetPrDiffInputJsonSchema,
+  PrDiffResponseJsonSchema,
   CheckoutBranchInputJsonSchema,
+  CheckoutBranchResponseJsonSchema,
   GetMergeConflictFilesInputJsonSchema,
+  GetMergeConflictFilesResponseJsonSchema,
   GetChangedFilesInputJsonSchema,
+  GetChangedFilesResponseJsonSchema,
   GetPackageScriptsInputJsonSchema,
+  GetPackageScriptsResponseJsonSchema,
   ReadCiLogsInputJsonSchema,
+  ReadCiLogsResponseJsonSchema,
   RepoLogsInputJsonSchema,
+  RepoLogsResponseJsonSchema,
   CreateBranchInputJsonSchema,
+  CreateBranchResponseJsonSchema,
   CreateRepairBranchInputJsonSchema,
+  CreateRepairBranchResponseJsonSchema,
+  CheckJulesStatusResponseJsonSchema,
   RunTestsInputJsonSchema,
+  RunTestsResponseJsonSchema,
   CommitPatchInputJsonSchema,
+  CommitPatchResponseJsonSchema,
   OpenReplacementPrInputJsonSchema,
+  OpenReplacementPrResponseJsonSchema,
   CreatePullRequestInputJsonSchema,
+  CreatePullRequestResponseJsonSchema,
   CommentTriageSummaryInputJsonSchema,
+  CommentTriageSummaryResponseJsonSchema,
   GetPrInputJsonSchema,
+  GetPrResponseJsonSchema,
   IssueViewInputJsonSchema,
+  IssueViewResponseJsonSchema,
   IssueUpdateInputJsonSchema,
+  IssueUpdateResponseJsonSchema,
   IssueCommentInputJsonSchema,
+  IssueCommentResponseJsonSchema,
   CreateIssueInputJsonSchema,
+  CreateIssueResponseJsonSchema,
   GetCommandSchemaInputJsonSchema,
+  GetCommandSchemaResponseJsonSchema,
   ReadAgentContextInputJsonSchema as ReadAgentContextSchema,
+  ReadAgentContextResponseJsonSchema,
+  MultiExecInputJsonSchema,
+  MultiExecResponseJsonSchema,
   CreateJulesSessionInputJsonSchema,
   JulesSessionIdInputJsonSchema,
   JulesSendMessageInputJsonSchema,
+  JulesSendMessageResponseJsonSchema,
+  JulesGetMessagesResponseJsonSchema,
   JulesListSessionsInputJsonSchema,
+  JulesListSessionsResponseJsonSchema,
+  JulesSessionResponseJsonSchema,
+  JulesGetPrResponseJsonSchema,
+  JulesTriggerFeedbackResponseJsonSchema,
   GetPrReviewsInputJsonSchema,
+  GetPrReviewsResponseJsonSchema,
   GetPrCommitsInputJsonSchema,
+  GetPrCommitsResponseJsonSchema,
   GetWorkflowRunsInputJsonSchema,
+  GetWorkflowRunsResponseJsonSchema,
 } from "../tools/contract.js";
 
 export const MCP_PROMPTS: Prompt[] = [
@@ -72,12 +107,30 @@ export const MCP_RESOURCES: Resource[] = [
     mimeType: "text/markdown",
     description: "The agent contract specification file (.agents/AGENT_CONTRACT.md).",
   },
+  {
+    uri: "mcp://workspace/project-config",
+    name: "Project Configuration",
+    mimeType: "application/json",
+    description: "The project configuration (project_config.json).",
+  },
   {
     uri: "mcp://git/changed-files",
     name: "Git Changed Files",
     mimeType: "application/json",
     description: "List of changed files in the repository.",
   },
+  {
+    uri: "mcp://git/status",
+    name: "Git Status",
+    mimeType: "application/json",
+    description: "Current working directory git status.",
+  },
+  {
+    uri: "mcp://ci/latest-run",
+    name: "Latest CI Run",
+    mimeType: "application/json",
+    description: "Recent CI exit statuses, workflow runs, and annotations.",
+  },
   {
     uri: "repo://package-json",
     name: "package.json",
@@ -113,216 +166,232 @@ export const MCP_RESOURCE_TEMPLATES: ResourceTemplate[] = [
   },
 ];
 
-const DEFAULT_OUTPUT_SCHEMA = {
-  type: "object",
-  properties: {},
-  additionalProperties: true,
-} as const;
-
 const BASE_MCP_TOOLS: Tool[] = [
   {
     name: "boomtick.health",
     description: "Check the health and configuration of the MCP server.",
     inputSchema: HealthCheckInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: HealthCheckResponseJsonSchema as any,
   },
   {
     name: "github.search_open_prs",
     description: "Search for open pull requests in the repository.",
     inputSchema: SearchPRsInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: SearchPRsResponseJsonSchema as any,
   },
   {
     name: "repo.read_agent_context",
-    description: "Read the full repository index including file tree, CLI schema, and MCP tools.",
+    description: "Read the repository index including metadata, model review chains, or multi-repo ecosystem status.",
     inputSchema: ReadAgentContextSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: ReadAgentContextResponseJsonSchema as any,
+  },
+  {
+    name: "repo.multi_exec",
+    description: "Execute a shell command sequentially across ecosystem repositories (or a filtered subset).",
+    inputSchema: MultiExecInputJsonSchema as any,
+    outputSchema: MultiExecResponseJsonSchema as any,
   },
   {
     name: "github.get_pr_diff",
     description: "Get the diff and changed files for a pull request.",
     inputSchema: GetPrDiffInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: PrDiffResponseJsonSchema as any,
   },
   {
     name: "github.checkout_branch",
     description: "Checkout a specific branch in the repository or worktree.",
     inputSchema: CheckoutBranchInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: CheckoutBranchResponseJsonSchema as any,
   },
   {
     name: "github.get_merge_conflict_files",
     description: "Detect files that conflict when a PR is merged with the base branch.",
     inputSchema: GetMergeConflictFilesInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: GetMergeConflictFilesResponseJsonSchema as any,
   },
   {
     name: "repo.get_changed_files",
     description: "Get the list of changed files between two refs.",
     inputSchema: GetChangedFilesInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: GetChangedFilesResponseJsonSchema as any,
   },
   {
     name: "repo.get_command_schema",
     description: "Retrieve a lightweight, targeted schema for a specific td subcommand. Use this instead of reading the entire cli-schema.json to save tokens.",
     inputSchema: GetCommandSchemaInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: GetCommandSchemaResponseJsonSchema as any,
   },
   {
     name: "repo.get_package_scripts",
     description: "Get the scripts defined in package.json.",
     inputSchema: GetPackageScriptsInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: GetPackageScriptsResponseJsonSchema as any,
   },
   {
     name: "repo.read_ci_logs",
     description: "Read CI logs for a given pull request.",
     inputSchema: ReadCiLogsInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: ReadCiLogsResponseJsonSchema as any,
   },
   {
     name: "repo.logs",
     description: "Stream or grep combined CI logs for all jobs in a pull request.",
     inputSchema: RepoLogsInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: RepoLogsResponseJsonSchema as any,
   },
   {
     name: "repo.create_branch",
     description: "Creates a new clean git branch from a target base branch.",
     inputSchema: CreateBranchInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: CreateBranchResponseJsonSchema as any,
   },
   {
     name: "repo.create_repair_branch",
     description: "Creates a fresh worktree and a new repair branch for an existing PR. This isolates the repair work from the main codebase.",
     inputSchema: CreateRepairBranchInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: CreateRepairBranchResponseJsonSchema as any,
+  },
+  {
+    name: "repo.check_jules_status",
+    description: "Check or poll the status of a Jules remediation session and verify its branch or PR status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "The unique ID or task ID of the Jules session." },
+        commitSha: { type: "string", description: "Commit SHA for idempotency key verification." },
+        failureLog: { type: "string", description: "Failure log content for idempotency key calculation." },
+        poll: { type: "boolean", description: "Whether to poll until session completion or timeout." },
+        timeoutMs: { type: "integer", description: "Timeout in milliseconds when polling." },
+        intervalMs: { type: "integer", description: "Polling interval in milliseconds." },
+      },
+    } as any,
+    outputSchema: CheckJulesStatusResponseJsonSchema as any,
   },
   {
     name: "repo.run_tests",
     description: "Run repository tests and checks.",
     inputSchema: RunTestsInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: RunTestsResponseJsonSchema as any,
   },
   {
     name: "repo.commit_patch",
     description: "Commit verified repair changes in a worktree.",
     inputSchema: CommitPatchInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: CommitPatchResponseJsonSchema as any,
   },
   {
     name: "github.open_replacement_pr",
     description: "Open a new PR that replaces or repairs the original PR.",
     inputSchema: OpenReplacementPrInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: OpenReplacementPrResponseJsonSchema as any,
   },
   {
     name: "github.create_pull_request",
     description: "Creates a pull request on GitHub using the MCP server's integrated credentials. Bypasses terminal CLI constraints.",
     inputSchema: CreatePullRequestInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: CreatePullRequestResponseJsonSchema as any,
   },
   {
     name: "github.comment_triage_summary",
     description: "Comment on the original PR with a diagnosis and replacement link.",
     inputSchema: CommentTriageSummaryInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: CommentTriageSummaryResponseJsonSchema as any,
   },
   {
     name: "github.get_pr",
     description: "Get details of a GitHub PR including title, state, and URLs.",
     inputSchema: GetPrInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: GetPrResponseJsonSchema as any,
   },
   {
     name: "github.get_pr_reviews",
     description: "Get top-level reviews, verdicts, states, and bodies for a GitHub PR.",
     inputSchema: GetPrReviewsInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: GetPrReviewsResponseJsonSchema as any,
   },
   {
     name: "github.get_pr_commits",
     description: "List commits and commit metadata (SHAs, authors, messages) for a GitHub PR.",
     inputSchema: GetPrCommitsInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: GetPrCommitsResponseJsonSchema as any,
   },
   {
     name: "repo.get_workflow_runs",
     description: "List recent GitHub Actions workflow runs for the repository.",
     inputSchema: GetWorkflowRunsInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: GetWorkflowRunsResponseJsonSchema as any,
   },
   {
     name: "github.issue_view",
     description: "View details of a GitHub issue including title, body, and state.",
     inputSchema: IssueViewInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: IssueViewResponseJsonSchema as any,
   },
   {
     name: "github.issue_update",
     description: "Update a GitHub issue's body, labels, and/or state.",
     inputSchema: IssueUpdateInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: IssueUpdateResponseJsonSchema as any,
   },
   {
     name: "github.issue_comment",
     description: "Add a new comment to a GitHub issue.",
     inputSchema: IssueCommentInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: IssueCommentResponseJsonSchema as any,
   },
   {
     name: "github.create_issue",
     description: "Create a new GitHub issue.",
     inputSchema: CreateIssueInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: CreateIssueResponseJsonSchema as any,
   },
   {
     name: "jules.create_session",
     description: "Create a Jules session that performs work externally and may generate a GitHub pull request.",
     inputSchema: CreateJulesSessionInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: JulesSessionResponseJsonSchema as any,
   },
   {
     name: "jules.get_session",
     description: "Get the status and details of a Jules session.",
     inputSchema: JulesSessionIdInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: JulesSessionResponseJsonSchema as any,
   },
   {
     name: "jules.send_message",
     description: "Send a message to an active Jules session.",
     inputSchema: JulesSendMessageInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: JulesSendMessageResponseJsonSchema as any,
   },
   {
     name: "jules.get_messages",
     description: "Get the message history of a Jules session.",
     inputSchema: JulesSessionIdInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: JulesGetMessagesResponseJsonSchema as any,
   },
   {
     name: "jules.list_sessions",
     description: "List all Jules sessions.",
     inputSchema: JulesListSessionsInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: JulesListSessionsResponseJsonSchema as any,
   },
   {
     name: "jules.cancel_session",
     description: "Cancel an ongoing Jules session.",
     inputSchema: JulesSessionIdInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: JulesSessionResponseJsonSchema as any,
   },
   {
     name: "jules.get_pr",
     description: "Get the generated pull request url associated with an active Jules agent session.",
     inputSchema: JulesSessionIdInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: JulesGetPrResponseJsonSchema as any,
   },
   {
     name: "jules.trigger_feedback",
     description: "Automatically collect CI status/logs for the PR associated with a Jules session and send them back as feedback.",
     inputSchema: JulesSessionIdInputJsonSchema as any,
-    outputSchema: DEFAULT_OUTPUT_SCHEMA as any,
+    outputSchema: JulesTriggerFeedbackResponseJsonSchema as any,
   },
 ];
 

package/src/mcp/http.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import http from "node:http";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { createMcpHttpServer } from "./http.js";
+import { BoomtickMCPServer } from "./server.js";
 
 describe("createMcpHttpServer", () => {
   let mcpServer: Server;
@@ -18,19 +18,58 @@ describe("createMcpHttpServer", () => {
     }
   });
 
-  it("should respond with OAuth protected resource metadata on /.well-known/oauth-protected-resource", async () => {
+  it("should respond with 200 on GET /health endpoint", async () => {
+    httpServerObj = createMcpHttpServer({ port: 0, mcpServer });
+    port = await httpServerObj.listen(0);
+
+    const res = await fetch(`http://localhost:${port}/health`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ status: "ok", transport: "http" });
+  });
+
+  it("should respond with RFC 9728 OAuth protected resource metadata on /.well-known/oauth-protected-resource", async () => {
     httpServerObj = createMcpHttpServer({ port: 0, mcpServer });
     port = await httpServerObj.listen(0);
 
     const res = await fetch(`http://localhost:${port}/.well-known/oauth-protected-resource`);
     expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/json");
+
     const body = await res.json();
     expect(body.resource).toBe("mcp://boomtick-mcp");
-    expect(body.authorization_servers).toBeDefined();
+    expect(body.authorization_servers).toEqual(["https://auth.boomtick.dev"]);
     expect(body.scopes_supported).toEqual(["mcp:read", "mcp:write"]);
+    expect(body.bearer_methods_supported).toEqual(["header"]);
+    expect(body.resource_documentation).toBe("https://github.com/arii/boomtick");
   });
 
-  it("should reject requests when Bearer token is missing or invalid", async () => {
+  it("should handle HEAD requests for /.well-known/oauth-protected-resource", async () => {
+    httpServerObj = createMcpHttpServer({ port: 0, mcpServer });
+    port = await httpServerObj.listen(0);
+
+    const res = await fetch(`http://localhost:${port}/.well-known/oauth-protected-resource`, {
+      method: "HEAD",
+    });
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    expect(text).toBe("");
+  });
+
+  it("should handle OPTIONS preflight CORS requests", async () => {
+    httpServerObj = createMcpHttpServer({ port: 0, mcpServer });
+    port = await httpServerObj.listen(0);
+
+    const res = await fetch(`http://localhost:${port}/sse`, {
+      method: "OPTIONS",
+    });
+    expect(res.status).toBe(204);
+    expect(res.headers.get("access-control-allow-origin")).toBe("*");
+    expect(res.headers.get("access-control-allow-methods")).toContain("GET");
+    expect(res.headers.get("access-control-allow-headers")).toContain("Authorization");
+  });
+
+  it("should reject protected requests when Bearer token is missing or invalid", async () => {
     httpServerObj = createMcpHttpServer({ port: 0, bearerToken: "secret123", mcpServer });
     port = await httpServerObj.listen(0);
 
@@ -38,6 +77,7 @@ describe("createMcpHttpServer", () => {
     const res1 = await fetch(`http://localhost:${port}/sse`);
     expect(res1.status).toBe(401);
     expect(res1.headers.get("www-authenticate")).toContain('Bearer realm="boomtick-mcp"');
+    expect(res1.headers.get("www-authenticate")).toContain('error="invalid_token"');
 
     // Request with wrong token
     const res2 = await fetch(`http://localhost:${port}/sse`, {
@@ -45,7 +85,7 @@ describe("createMcpHttpServer", () => {
     });
     expect(res2.status).toBe(401);
 
-    // Request with valid token
+    // Public resource metadata accessible with or without token
     const res3 = await fetch(`http://localhost:${port}/.well-known/oauth-protected-resource`, {
       headers: { Authorization: "Bearer secret123" },
     });
@@ -69,4 +109,34 @@ describe("createMcpHttpServer", () => {
     const body = await res.json();
     expect(body.error).toContain("Server misconfiguration");
   });
+
+  it("should return 400 for message requests without session or invalid session", async () => {
+    httpServerObj = createMcpHttpServer({ port: 0, bearerToken: "secret123", mcpServer });
+    port = await httpServerObj.listen(0);
+
+    const res = await fetch(`http://localhost:${port}/messages?sessionId=invalid_session`, {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer secret123",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ jsonrpc: "2.0", method: "ping", id: 1 }),
+    });
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("Session not found or expired");
+  });
+
+  it("should allow BoomtickMCPServer to start HTTP server via run() when transport is http", async () => {
+    process.env.MCP_TRANSPORT = "http";
+    process.env.PORT = "0";
+    process.env.BOOMTICK_MCP_BEARER_TOKEN = "test-token";
+
+    const boomtickServer = new BoomtickMCPServer();
+    await boomtickServer.run();
+
+    // Verify instance initialized properly
+    expect(boomtickServer).toBeInstanceOf(BoomtickMCPServer);
+  });
 });

package/src/mcp/http.ts

@@ -21,7 +21,7 @@ export function createMcpHttpServer(options: HttpServerOptions) {
   const server = http.createServer(async (req, res) => {
     // CORS Headers
     res.setHeader("Access-Control-Allow-Origin", "*");
-    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS, HEAD");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
 
     if (req.method === "OPTIONS") {
@@ -32,22 +32,35 @@ export function createMcpHttpServer(options: HttpServerOptions) {
 
     const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
 
-    // Endpoint 1: OAuth Protected Resource metadata
-    if (url.pathname === "/.well-known/oauth-protected-resource" && req.method === "GET") {
+    // Endpoint 0: Health check endpoint for readiness probes / load balancers
+    if (url.pathname === "/health" && req.method === "GET") {
       res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(
-        JSON.stringify({
-          resource: "mcp://boomtick-mcp",
-          "authorization_servers": [
-            process.env.MCP_OAUTH_AUTH_SERVER || "https://auth.boomtick.dev",
-          ],
-          scopes_supported: ["mcp:read", "mcp:write"],
-        })
-      );
+      res.end(JSON.stringify({ status: "ok", transport: "http" }));
       return;
     }
 
-    // Bearer Token Validation for SSE & Messages endpoints
+    // Endpoint 1: RFC 9728 OAuth Protected Resource Metadata Discovery
+    if (url.pathname === "/.well-known/oauth-protected-resource" && (req.method === "GET" || req.method === "HEAD")) {
+      const metadata = {
+        resource: process.env.MCP_RESOURCE_URI || process.env.BOOMTICK_RESOURCE_URI || "mcp://boomtick-mcp",
+        authorization_servers: [
+          process.env.MCP_OAUTH_AUTH_SERVER || "https://auth.boomtick.dev",
+        ],
+        scopes_supported: ["mcp:read", "mcp:write"],
+        bearer_methods_supported: ["header"],
+        resource_documentation: process.env.MCP_RESOURCE_DOCS || "https://github.com/arii/boomtick",
+      };
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      if (req.method === "HEAD") {
+        res.end();
+      } else {
+        res.end(JSON.stringify(metadata, null, 2));
+      }
+      return;
+    }
+
+    // Bearer Token / OAuth 2.1 Validation for Protected Routes (/sse & /messages)
     if (url.pathname === "/sse" || url.pathname === "/messages") {
       if (!bearerToken) {
         res.writeHead(500, { "Content-Type": "application/json" });
@@ -67,7 +80,7 @@ export function createMcpHttpServer(options: HttpServerOptions) {
       if (!isMatch) {
         res.writeHead(401, {
           "Content-Type": "application/json",
-          "WWW-Authenticate": 'Bearer realm="boomtick-mcp", error="invalid_token"',
+          "WWW-Authenticate": 'Bearer realm="boomtick-mcp", error="invalid_token", error_description="Invalid or missing Bearer token"',
         });
         res.end(JSON.stringify({ error: "unauthorized", message: "Invalid or missing Bearer token" }));
         return;
@@ -76,11 +89,24 @@ export function createMcpHttpServer(options: HttpServerOptions) {
 
     // Endpoint 2: SSE stream setup
     if (url.pathname === "/sse" && req.method === "GET") {
+      res.setHeader("Cache-Control", "no-cache");
+      res.setHeader("Content-Type", "text/event-stream");
+      res.setHeader("Connection", "keep-alive");
+
       const transport = new SSEServerTransport("/messages", res);
       transports.set(transport.sessionId, transport);
+
+      const keepAliveInterval = setInterval(() => {
+        if (!res.writableEnded) {
+          res.write(": keep-alive\n\n");
+        }
+      }, 15000);
+
       transport.onclose = () => {
+        clearInterval(keepAliveInterval);
         transports.delete(transport.sessionId);
       };
+
       await mcpServer.connect(transport);
       return;
     }