Feature/mcp #2

devZenta · 2025-12-28T16:51:02Z

This pull request introduces a new Model Context Protocol (MCP) server to the project, enabling external clients to interact with home automation features (like toggling lights, doors, and heating, as well as retrieving state and history) through a standardized protocol. It includes the MCP server implementation, tool definitions, authentication mechanisms, new dependencies, and comprehensive tests for the MCP tools. Additionally, the Docker and Compose configurations are updated to expose the new MCP server port.

The most important changes are:

MCP Server Integration:

Added a new MCP server implementation in src/mcp/server.ts, which exposes endpoints for MCP clients, registers home automation tools, handles CORS, and enforces authentication using a custom header. The server listens on port 3001 and provides /mcp and /health endpoints.
Updated the main application (index.ts) to start the MCP server alongside the main API server, and display its endpoint in the startup banner. [1] [2] [3]

Tooling and Protocol Implementation:

Implemented the MCP tools in src/mcp/tools.ts, providing handlers for toggling light/door/heat, setting temperature, retrieving home state, and fetching event history. Each tool makes authenticated API calls to the main server.
Exported the MCP tools and authorization setter in src/mcp/index.ts for use by the server.

Authentication:

Added a new authentication utility in src/utils/auth.ts to verify client credentials for MCP requests by checking a client’s ID and token against the database.

Testing:

Introduced a new test suite in tests/mcp/tools.test.ts to verify all MCP tool handlers, including their success and error cases, as well as correct header usage.
Adjusted mocks and minor test structure in other files to support the new testing approach. [1] [2] [3] [4] [5]

Configuration and Dependencies:

Updated Dockerfile and Compose files to expose and map the new MCP server port (3001). [1] [2]
Added new dependencies for MCP protocol support (@modelcontextprotocol/sdk) and input validation (zod) in package.json, and provided a script for running the MCP server. [1] [2]

These changes collectively enable secure, protocol-driven automation control and monitoring, and provide a solid foundation for future MCP-based integrations.

…tion

…ng clarity

codecov · 2025-12-28T16:51:32Z

Codecov Report

❌ Patch coverage is 96.93487% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/mcp/server.ts	95.55%	4 Missing ⚠️
index.ts	25.00%	3 Missing ⚠️
src/mcp/tools.ts	99.25%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This pull request introduces a Model Context Protocol (MCP) server to enable external clients to interact with home automation features through a standardized protocol. The implementation includes authentication, tool definitions for controlling home devices, and comprehensive test coverage for the new functionality.

Key changes:

Added MCP server with authentication-protected endpoints for home automation control
Implemented six MCP tools for toggling lights/doors/heating, setting temperature, retrieving state, and fetching history
Added client authentication utility with database-backed credential verification
Included comprehensive test suites for authentication and MCP tools

Reviewed changes

Copilot reviewed 16 out of 17 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
`src/utils/auth.ts`	New authentication utility for verifying client credentials against database
`src/mcp/tools.ts`	MCP tool handlers for home automation operations with API call integration
`src/mcp/server.ts`	MCP server implementation with authentication, CORS, and endpoint routing
`src/mcp/index.ts`	Export module for MCP tools and authorization setter
`tests/utils/auth.test.ts`	Comprehensive test suite for authentication utility
`tests/mcp/tools.test.ts`	Test suite covering all MCP tool handlers and error scenarios
`index.ts`	Main application updated to start MCP server and display endpoint in banner
`package.json`	Added MCP SDK and zod dependencies, plus MCP server run script
`Dockerfile`	Exposed port 3001 for MCP server
`compose.yaml`	Mapped MCP server port 3001
`prisma/db.ts`	Removed explanatory comments
`tests/rules/engine.test.ts`	Removed French comment
`tests/routes/ws.test.ts`	Removed French comments
`tests/routes/features.test.ts`	Removed French comments
`tests/mocks/prisma.ts`	Removed explanatory comments
`tests/integration/e2e.test.ts`	Removed comment
`bun.lock`	Updated lock file with new dependencies

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-28T16:57:29Z

src/mcp/server.ts

+
+				const authResult = await verifyClientAuth(authorization);
+				if (!authResult.valid) {
+					return new Response(JSON.stringify({ error: authResult.error }), {


The error response from the MCP server exposes the specific error message from the authentication failure. This could leak information about the authentication system to potential attackers. Consider returning a generic error message like "Authentication failed" without exposing the specific reason (e.g., "Authorization header missing" vs "Invalid credentials").

Suggested change

return new Response(JSON.stringify({ error: authResult.error }), {

console.warn(

`MCP authentication failed for request from ${req.headers.get("x-forwarded-for") || "unknown IP"}: ${

authResult.error || "Unknown authentication error"

}`,

);

return new Response(JSON.stringify({ error: "Authentication failed" }), {

Copilot · 2025-12-28T16:57:30Z

index.ts


 if (import.meta.main) {
 	initRuleEngine();
+	startMcpServer();


The MCP server is started without error handling. If startMcpServer() throws an error or fails to start, it could crash the entire application or leave it in an inconsistent state. Consider wrapping the call in a try-catch block and handling potential startup failures gracefully, possibly with fallback behavior or proper error logging.

Suggested change

startMcpServer();

try {

startMcpServer();

} catch (error) {

console.error("Failed to start MCP server", error);

}

Copilot · 2025-12-28T16:57:30Z

src/mcp/server.ts

+				}
+				console.log(`MCP request from authenticated client: ${authResult.clientId}`);
+
+				setAuthorization(authorization || "");


The authorization header is stored in a module-level variable via setAuthorization before being used in tool handlers. This creates a race condition where concurrent requests could overwrite each other's authorization values. Since the MCP server can handle multiple requests concurrently, one client's credentials could be used for another client's request. The authorization should be passed through the request context or as a parameter to the tool handlers.

Copilot · 2025-12-28T16:57:30Z

src/mcp/server.ts

+						headers: { ...corsHeaders, "Content-Type": "application/json" },
+					});
+				}
+				console.log(`MCP request from authenticated client: ${authResult.clientId}`);


Logging the authenticated client ID on every MCP request could create excessive log entries and make it difficult to identify actual security issues. Consider using a different log level (e.g., debug) for routine successful authentications, or only log authentication events on first connection or failures.

Suggested change

console.log(`MCP request from authenticated client: ${authResult.clientId}`);

console.debug(`MCP request from authenticated client: ${authResult.clientId}`);

Copilot · 2025-12-28T16:57:30Z

src/mcp/server.ts

+export async function startMcpServer() {
+	const MCP_PORT = Number(process.env.MCP_PORT) || 3001;
+
+	const server = new McpServer({
+		name: "myhouse-os",
+		version: "1.0.0",
+	});
+
+	for (const [name, tool] of Object.entries(tools)) {
+		server.tool(name, tool.description, tool.inputSchema.shape, async (args) => {
+			try {
+				const result = await tool.handler(args as Parameters<typeof tool.handler>[0]);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: JSON.stringify(result, null, 2),
+						},
+					],
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : "Unknown error";
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: JSON.stringify({ error: message }, null, 2),
+						},
+					],
+					isError: true,
+				};
+			}
+		});
+	}
+
+	const transport = new WebStandardStreamableHTTPServerTransport();
+
+	await server.connect(transport);
+
+	Bun.serve({
+		port: MCP_PORT,
+		async fetch(req) {
+			const url = new URL(req.url);
+
+			if (req.method === "OPTIONS") {
+				return new Response(null, { status: 204, headers: corsHeaders });
+			}
+
+			if (url.pathname === "/health") {
+				return new Response(JSON.stringify({ status: "ok", server: "myhouse-os-mcp" }), {
+					headers: { ...corsHeaders, "Content-Type": "application/json" },
+				});
+			}
+
+			if (url.pathname === "/mcp") {
+				const authorization = req.headers.get("authorization");
+
+				const authResult = await verifyClientAuth(authorization);
+				if (!authResult.valid) {
+					return new Response(JSON.stringify({ error: authResult.error }), {
+						status: 401,
+						headers: { ...corsHeaders, "Content-Type": "application/json" },
+					});
+				}
+				console.log(`MCP request from authenticated client: ${authResult.clientId}`);
+
+				setAuthorization(authorization || "");
+
+				const response = await transport.handleRequest(req);
+
+				const newHeaders = new Headers(response.headers);
+				for (const [key, value] of Object.entries(corsHeaders)) {
+					newHeaders.set(key, value);
+				}
+
+				return new Response(response.body, {
+					status: response.status,
+					statusText: response.statusText,
+					headers: newHeaders,
+				});
+			}
+
+			return new Response("Not Found", { status: 404, headers: corsHeaders });
+		},
+	});
+
+	console.log(`MCP server running on http://localhost:${MCP_PORT}`);
+	console.log(`MCP endpoint: http://localhost:${MCP_PORT}/mcp`);
+	console.log(`Health check: http://localhost:${MCP_PORT}/health`);
+}


There are no tests for the MCP server implementation in src/mcp/server.ts. This file contains critical authentication logic, request handling, and server initialization code that should have test coverage. Consider adding integration tests that verify the authentication flow, CORS headers, endpoint routing, and error handling.

Copilot · 2025-12-28T16:57:31Z

index.ts


 	const PORT_BUN_SERVER = process.env.PORT_BUN_SERVER || 3000;
 	const PORT_WEB_SERVER = process.env.PORT_WEB_SERVER || 8080;
+	const PORT_MCP_SERVER = process.env.MCP_PORT || 3001;


The environment variable name is inconsistent. The code reads process.env.MCP_PORT but the banner displays PORT_MCP_SERVER which suggests there might be confusion about the correct variable name. Either both should use MCP_PORT or both should use PORT_MCP_SERVER to avoid confusion when configuring the application.

Suggested change

const PORT_MCP_SERVER = process.env.MCP_PORT || 3001;

const PORT_MCP_SERVER = process.env.PORT_MCP_SERVER || 3001;

Copilot · 2025-12-28T16:57:32Z

src/utils/auth.ts

+		console.log(`Unauthorized access attempt by unknown client: ${clientId}`);
+		return { valid: false, error: "Invalid credentials" };
+	}
+
+	try {
+		const decryptedToken = decrypt(client.ClientToken);
+		if (decryptedToken !== clientToken) {
+			console.log(`Invalid token provided for client: ${clientId}`);
+			return { valid: false, error: "Invalid credentials" };
+		}
+	} catch (error) {
+		console.error(`Token verification failed for ${clientId}:`, error);


Logging sensitive information (client ID) on failed authentication attempts could facilitate enumeration attacks. An attacker could use this to determine which client IDs exist in the system. Consider using a generic log message that doesn't reveal whether the client ID exists or the token is invalid.

Suggested change

console.log(`Unauthorized access attempt by unknown client: ${clientId}`);

return { valid: false, error: "Invalid credentials" };

}

try {

const decryptedToken = decrypt(client.ClientToken);

if (decryptedToken !== clientToken) {

console.log(`Invalid token provided for client: ${clientId}`);

return { valid: false, error: "Invalid credentials" };

}

} catch (error) {

console.error(`Token verification failed for ${clientId}:`, error);

console.log("Unauthorized access attempt with unknown client credentials");

return { valid: false, error: "Invalid credentials" };

}

try {

const decryptedToken = decrypt(client.ClientToken);

if (decryptedToken !== clientToken) {

console.log("Invalid token provided for client authentication");

return { valid: false, error: "Invalid credentials" };

}

} catch (error) {

console.error("Token verification failed during client authentication:", error);

Copilot · 2025-12-28T16:57:32Z

src/utils/auth.ts

+		console.log(`Unauthorized access attempt by unknown client: ${clientId}`);
+		return { valid: false, error: "Invalid credentials" };
+	}
+
+	try {
+		const decryptedToken = decrypt(client.ClientToken);
+		if (decryptedToken !== clientToken) {
+			console.log(`Invalid token provided for client: ${clientId}`);
+			return { valid: false, error: "Invalid credentials" };
+		}
+	} catch (error) {
+		console.error(`Token verification failed for ${clientId}:`, error);


Logging sensitive information (client ID) on failed token verification could facilitate enumeration attacks. Similar to the previous issue, this allows attackers to determine which client IDs are valid. Consider using a generic error log message instead.

Suggested change

console.log(`Unauthorized access attempt by unknown client: ${clientId}`);

return { valid: false, error: "Invalid credentials" };

}

try {

const decryptedToken = decrypt(client.ClientToken);

if (decryptedToken !== clientToken) {

console.log(`Invalid token provided for client: ${clientId}`);

return { valid: false, error: "Invalid credentials" };

}

} catch (error) {

console.error(`Token verification failed for ${clientId}:`, error);

console.log("Unauthorized access attempt by unknown client");

return { valid: false, error: "Invalid credentials" };

}

try {

const decryptedToken = decrypt(client.ClientToken);

if (decryptedToken !== clientToken) {

console.log("Invalid token provided during client authentication");

return { valid: false, error: "Invalid credentials" };

}

} catch (error) {

console.error("Token verification failed during client authentication:", error);

Copilot · 2025-12-28T16:57:32Z

src/mcp/tools.ts

+				apiCall("/toggle/light", "GET"),
+				apiCall("/toggle/door", "GET"),
+				apiCall("/toggle/heat", "GET"),


The GET requests to toggle endpoints (/toggle/light, /toggle/door, /toggle/heat) in the get_home_state handler is semantically incorrect. Based on typical REST conventions, GET requests should not modify state. If these endpoints return the current state without changing it, the naming is misleading (they're called "toggle" but used to get state). If they do change state, using GET violates REST principles and could lead to unintended state changes.

Suggested change

apiCall("/toggle/light", "GET"),

apiCall("/toggle/door", "GET"),

apiCall("/toggle/heat", "GET"),

apiCall("/toggle/light", "POST"),

apiCall("/toggle/door", "POST"),

apiCall("/toggle/heat", "POST"),

Copilot · 2025-12-28T16:57:32Z

src/mcp/server.ts

+import { setAuthorization, tools } from "./tools";
+
+const corsHeaders = {
+	"Access-Control-Allow-Origin": "*",


The CORS configuration allows all origins with "*", which is overly permissive for an MCP server that handles authenticated requests. This could expose the MCP endpoints to unauthorized cross-origin requests. Consider restricting the allowed origins to specific trusted domains or making this configurable via environment variables.

…formatting test: implement tests for wrapToolHandler and enhance verifyClientAuth error handling refactor: update mockPrisma methods to use unknown type for better type safety

devZenta added 8 commits December 28, 2025 16:07

chore: update package.json to add mcp script and new dependencies

30ea8f2

feat: expose additional port 3001 for the application

f3a4a0a

feat: start MCP server and update server information in the console log

ff2d0f2

feat: add integration tests for MCP tools and authentication verifica…

27f9e1e

…tion

feat: implement client authorization verification function

6ffa519

refactor: clean up db.ts by removing unnecessary comments and improvi…

4937316

…ng clarity

feat: implement MCP server and tools for home automation control

aebc096

refactor: reorganize imports in index.ts and server.ts for clarity

f753b1c

devZenta requested review from Degalax, GARATONCODE, Copilot and francoisdotdev December 28, 2025 16:51

devZenta self-assigned this Dec 28, 2025

devZenta added documentation Improvements or additions to documentation enhancement New feature or request labels Dec 28, 2025

Copilot started reviewing on behalf of devZenta December 28, 2025 16:51 View session

Copilot AI reviewed Dec 28, 2025

View reviewed changes

devZenta added 2 commits December 28, 2025 18:01

refactor: remove unused export from mcp index.ts

ef1e042

feat: add wrapToolHandler for consistent error handling and response …

4718973

…formatting test: implement tests for wrapToolHandler and enhance verifyClientAuth error handling refactor: update mockPrisma methods to use unknown type for better type safety

devZenta merged commit a6e9393 into main Dec 28, 2025
6 checks passed

-					return new Response(JSON.stringify({ error: authResult.error }), {
+					console.warn(
+						`MCP authentication failed for request from ${req.headers.get("x-forwarded-for") || "unknown IP"}: ${
+							authResult.error || "Unknown authentication error"
+						}`,
+					);
+					return new Response(JSON.stringify({ error: "Authentication failed" }), {

	console.log(`MCP request from authenticated client: ${authResult.clientId}`);
	console.debug(`MCP request from authenticated client: ${authResult.clientId}`);

	const PORT_MCP_SERVER = process.env.MCP_PORT \|\| 3001;
	const PORT_MCP_SERVER = process.env.PORT_MCP_SERVER \|\| 3001;

Feature/mcp #2

Feature/mcp #2

Uh oh!

Conversation

devZenta commented Dec 28, 2025

Uh oh!

codecov bot commented Dec 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Dec 28, 2025 •

edited

Loading