@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.3.1

package/tests/server/toolVisibility.http.test.ts

@@ -1,111 +0,0 @@
-/**
- * Regression: tools/list over the REAL HTTP path is filtered by the caller's token.
- *
- * Drives the production pieces end to end — bearer auth middleware (real HS256
- * JWTs) -> parseBody -> handleStreamRequest -> per-request McpServer — so that
- * removing the request-to-createServer permission forwarding in stream.ts fails
- * here, not just the createServer-level unit tests.
- */
-
-import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
-import { createServer as createHttpServer, type Server } from 'node:http';
-import type { AddressInfo } from 'node:net';
-import { createAuthMiddleware } from '../../src/server/auth.js';
-import { parseBody } from '../../src/server/http.js';
-import { handleStreamRequest } from '../../src/server/stream.js';
-import { createJwt } from '../../src/utils/jwt.js';
-import { parsePermissionsConfig } from '../../src/permissions/index.js';
-import type { EnvironmentConfig } from '../../src/config.js';
-
-vi.mock('../../src/utils/logger.js', () => ({
-  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
-}));
-
-const SECRET = 'test-secret-for-tool-visibility-0123456789';
-const permissions = parsePermissionsConfig(
-  JSON.stringify({
-    users: [
-      { sub: 'admin', role: 'admin' },
-      { sub: 'operator', role: 'operator' },
-      { sub: 'reader', role: 'readonly' },
-    ],
-    defaultRole: 'NONE',
-  })
-);
-
-// Only the fields the stream path reads; HA client is a registration-only stub.
-const config = { stateful: false, httpAllowedHosts: [] } as unknown as EnvironmentConfig;
-const options = { haClient: {} as never, config };
-
-let server: Server;
-let baseUrl: string;
-
-beforeAll(async () => {
-  const auth = createAuthMiddleware({ method: 'bearer', secret: SECRET, permissions });
-  server = createHttpServer(async (req, res) => {
-    if (!auth(req, res)) return;
-    const body = await parseBody(req);
-    await handleStreamRequest(options, req, res, body);
-  });
-  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
-  baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}/mcp`;
-});
-
-afterAll(async () => {
-  await new Promise<void>((resolve) => server.close(() => resolve()));
-});
-
-async function listTools(sub: string): Promise<string[]> {
-  const token = createJwt({ sub, exp: Math.floor(Date.now() / 1000) + 300 }, SECRET);
-  const res = await fetch(baseUrl, {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${token}`,
-      'Content-Type': 'application/json',
-      Accept: 'application/json, text/event-stream',
-    },
-    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }),
-  });
-  expect(res.status).toBe(200);
-  const text = await res.text();
-  const json = text.includes('data:')
-    ? JSON.parse(text.split('\n').find((l) => l.startsWith('data:'))!.slice(5))
-    : JSON.parse(text);
-  return (json.result.tools as { name: string }[]).map((t) => t.name);
-}
-
-describe('tools/list over HTTP is filtered by the bearer token', () => {
-  it('admin sees admin and control tools', async () => {
-    const tools = await listTools('admin');
-    expect(tools).toContain('restartHomeAssistant');
-    expect(tools).toContain('controlLight');
-  });
-
-  it('a READONLY token is not offered control or admin tools', async () => {
-    const tools = await listTools('reader');
-    expect(tools).toContain('getState');
-    expect(tools).not.toContain('controlLight');
-    expect(tools).not.toContain('restartHomeAssistant');
-    expect(tools).not.toContain('deleteAutomation');
-  });
-
-  it('an unmapped sub (defaultRole NONE) is offered no permission-gated tools', async () => {
-    const tools = await listTools('nobody');
-    expect(tools).not.toContain('getState');
-    expect(tools).not.toContain('controlLight');
-  });
-
-  it('interleaved callers each get their own filtered list (no shared server instance)', async () => {
-    const [reader1, admin, reader2, operator] = await Promise.all([
-      listTools('reader'),
-      listTools('admin'),
-      listTools('reader'),
-      listTools('operator'),
-    ]);
-    expect(reader1).toEqual(reader2);
-    expect(reader1).not.toContain('controlLight');
-    expect(admin).toContain('restartHomeAssistant');
-    expect(operator).toContain('controlLight');
-    expect(operator).not.toContain('restartHomeAssistant');
-  });
-});

package/tests/server/toolVisibility.test.ts

@@ -1,129 +0,0 @@
-/**
- * tools/list is filtered by the caller's permission mask.
- *
- * A caller is only offered tools it can actually use, so an LLM client does not
- * plan around (or learn about) admin tools it would be denied. Execution-time
- * RBAC in wrapToolHandler is unchanged and still enforced.
- */
-
-import { describe, it, expect } from 'vitest';
-import { Client, InMemoryTransport } from '@modelcontextprotocol/client';
-import { createServer } from '../../src/server/common.js';
-import { Role, Permission } from '../../src/permissions/index.js';
-import { getToolRequiredPermission } from '../../src/tools/common.js';
-import { canReadAnyResource } from '../../src/tools/omada/graph.js';
-
-// Registration never calls the HA client; a stub is enough to register HA tools.
-const haClient = {} as never;
-
-async function listToolNames(callerPermissions: number | undefined): Promise<string[]> {
-  const server = createServer({ haClient, callerPermissions });
-  const client = new Client({ name: 'visibility-test', version: '0' });
-  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-  await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
-  try {
-    const { tools } = await client.listTools();
-    return tools.map((t) => t.name).sort();
-  } finally {
-    await client.close();
-    await server.close();
-  }
-}
-
-describe('tools/list visibility by caller permissions', () => {
-  it('lists every tool when no caller mask is given (stdio local trust)', async () => {
-    const all = await listToolNames(undefined);
-    expect(all).toContain('restartHomeAssistant');
-    expect(all).toContain('controlLight');
-    expect(all).toContain('getState');
-  });
-
-  it('a full-permission caller sees the same list as unfiltered', async () => {
-    expect(await listToolNames(0xff)).toEqual(await listToolNames(undefined));
-  });
-
-  it('a READONLY caller sees only tools it is permitted to call', async () => {
-    const all = await listToolNames(undefined);
-    const visible = await listToolNames(Role.READONLY);
-
-    expect(visible).toContain('getState');
-    expect(visible).not.toContain('controlLight');
-    expect(visible).not.toContain('restartHomeAssistant');
-    expect(visible).not.toContain('deleteAutomation');
-    expect(visible.length).toBeLessThan(all.length);
-
-    // Every hidden tool really is one the caller would be denied, and every
-    // visible tool with a static bit is one the caller holds.
-    for (const name of all) {
-      const required = getToolRequiredPermission(name);
-      const permitted = required === undefined || (Role.READONLY & required) === required;
-      expect(visible.includes(name), `${name} visibility`).toBe(permitted);
-    }
-  });
-
-  it('an OPERATOR caller sees control tools but not admin/configure tools', async () => {
-    const visible = await listToolNames(Role.OPERATOR);
-    expect(visible).toContain('controlLight');
-    expect(visible).toContain('sendNotification');
-    expect(visible).not.toContain('restartHomeAssistant');
-    expect(visible).not.toContain('createAutomation');
-  });
-
-  it('a caller with no permissions sees no permission-gated tools', async () => {
-    const visible = await listToolNames(Role.NONE);
-    for (const name of visible) {
-      expect(getToolRequiredPermission(name), `${name} should not be listed for NONE`).toBeUndefined();
-    }
-  });
-
-  it('a hidden tool cannot be called either', async () => {
-    const server = createServer({ haClient, callerPermissions: Permission.QUERY });
-    const client = new Client({ name: 'visibility-test', version: '0' });
-    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
-    try {
-      const outcome = await client
-        .callTool({ name: 'restartHomeAssistant', arguments: {} })
-        .then((r) => (r.isError ? 'error-result' : 'success'), () => 'rejected');
-      expect(outcome).not.toBe('success');
-    } finally {
-      await client.close();
-      await server.close();
-    }
-  });
-});
-
-describe('omada_read visibility (per-path RBAC tool)', () => {
-  // Graph mode registers omada_browse + omada_read; registration never calls the client.
-  async function listOmadaTools(callerPermissions: number): Promise<string[]> {
-    const server = createServer({ omadaClient: {} as never, toolRegistrationMode: 'graph', callerPermissions });
-    const client = new Client({ name: 'visibility-test', version: '0' });
-    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
-    try {
-      const { tools } = await client.listTools();
-      return tools.map((t) => t.name).filter((n) => n.startsWith('omada_'));
-    } finally {
-      await client.close();
-      await server.close();
-    }
-  }
-
-  it('is hidden from a caller who can read no Omada resource (NONE)', async () => {
-    expect(await listOmadaTools(Role.NONE)).not.toContain('omada_read');
-  });
-
-  it('is listed for a caller who can read some resources (QUERY)', async () => {
-    expect(await listOmadaTools(Permission.QUERY)).toContain('omada_read');
-  });
-
-  it('is listed for an ADMIN-only mask, which can still read the ADMIN-gated /security nodes', async () => {
-    expect(canReadAnyResource(Permission.ADMIN)).toBe(true);
-    expect(await listOmadaTools(Permission.ADMIN)).toContain('omada_read');
-  });
-
-  it('is hidden for a mask that matches no node (e.g. NOTIFY only)', async () => {
-    expect(canReadAnyResource(Permission.NOTIFY)).toBe(false);
-    expect(await listOmadaTools(Permission.NOTIFY)).not.toContain('omada_read');
-  });
-});

package/tests/tools/ai/analyzeSensors.test.ts

@@ -1,227 +0,0 @@
-/**
- * Unit tests for AI analyzeSensors tool handler
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { LocalAIClient } from '../../../src/localAI/index.js';
-import { registerAnalyzeSensorsTool } from '../../../src/tools/ai/analyzeSensors.js';
-
-// Create mock server that captures registered handlers
-function createMockServer() {
-  const handlers = new Map<string, { config: unknown; handler: (...args: unknown[]) => unknown }>();
-  return {
-    registerTool: vi.fn((name: string, config: unknown, handler: (...args: unknown[]) => unknown) => {
-      handlers.set(name, { config, handler });
-    }),
-    handlers,
-  } as unknown as McpServer & { handlers: Map<string, { config: unknown; handler: (...args: unknown[]) => unknown }> };
-}
-
-// Create mock LocalAIClient
-function createMockAIClient() {
-  return {
-    analyzeSensors: vi.fn(),
-  } as unknown as LocalAIClient;
-}
-
-// Mock extra with AI permission
-const mockExtra = {
-  sessionId: 'test-session',
-  http: { authInfo: { extra: { permissions: 0xff } } }, // All permissions including AI
-};
-
-// Mock extra without AI permission
-const noAiPermExtra = {
-  sessionId: 'test-session',
-  http: { authInfo: { extra: { permissions: 0x08 } } }, // QUERY only
-};
-
-// Parse JSON result from tool output
-function parseResult(result: { content: { text: string }[] }): unknown {
-  return JSON.parse(result.content[0].text);
-}
-
-describe('AI analyzeSensors Tool Handler', () => {
-  let server: ReturnType<typeof createMockServer>;
-
-  beforeEach(() => {
-    server = createMockServer();
-    vi.clearAllMocks();
-  });
-
-  describe('Registration', () => {
-    it('should register the tool', () => {
-      const aiClient = createMockAIClient();
-      registerAnalyzeSensorsTool(server, aiClient);
-
-      expect(server.registerTool).toHaveBeenCalledWith(
-        'analyzeSensors',
-        expect.objectContaining({
-          description: expect.any(String),
-        }),
-        expect.any(Function)
-      );
-    });
-
-    it('should register with optional AI client', () => {
-      registerAnalyzeSensorsTool(server, undefined);
-
-      expect(server.registerTool).toHaveBeenCalledWith(
-        'analyzeSensors',
-        expect.objectContaining({
-          description: expect.any(String),
-        }),
-        expect.any(Function)
-      );
-    });
-  });
-
-  describe('AI Client Not Configured', () => {
-    it('should return error when AI client is not provided', async () => {
-      registerAnalyzeSensorsTool(server, undefined);
-      const handler = server.handlers.get('analyzeSensors')!.handler;
-
-      const sensorData = {
-        'sensor.temperature': { state: '25', unit: '°C' },
-      };
-
-      const result = await handler({ sensors: sensorData }, mockExtra);
-      const parsed = parseResult(result) as { error: string; message: string };
-
-      expect(parsed.error).toBe('AI client not configured');
-      expect(parsed.message).toContain('AI_URL');
-    });
-  });
-
-  describe('Input Validation', () => {
-    it('should return error when sensors is undefined', async () => {
-      const aiClient = createMockAIClient();
-      registerAnalyzeSensorsTool(server, aiClient);
-      const handler = server.handlers.get('analyzeSensors')!.handler;
-
-      const result = await handler({ sensors: undefined }, mockExtra);
-      const parsed = parseResult(result) as { error: string };
-
-      expect(parsed.error).toBe('sensors object is required');
-      expect(aiClient.analyzeSensors).not.toHaveBeenCalled();
-    });
-
-    it('should return error when sensors is not an object', async () => {
-      const aiClient = createMockAIClient();
-      registerAnalyzeSensorsTool(server, aiClient);
-      const handler = server.handlers.get('analyzeSensors')!.handler;
-
-      const result = await handler({ sensors: 'invalid' }, mockExtra);
-      const parsed = parseResult(result) as { error: string };
-
-      expect(parsed.error).toBe('sensors object is required');
-      expect(aiClient.analyzeSensors).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('Successful Analysis', () => {
-    it('should analyze sensors and return result', async () => {
-      const aiClient = createMockAIClient();
-      const mockAnalysis = {
-        summary: 'All sensors are operating normally',
-        issues: [],
-        recommendations: ['Consider adding humidity sensors'],
-      };
-      (aiClient.analyzeSensors as ReturnType<typeof vi.fn>).mockResolvedValue(mockAnalysis);
-
-      registerAnalyzeSensorsTool(server, aiClient);
-      const handler = server.handlers.get('analyzeSensors')!.handler;
-
-      const sensorData = {
-        'sensor.temperature': { state: '25', unit: '°C', attributes: { friendly_name: 'Living Room' } },
-        'sensor.humidity': { state: '50', unit: '%', attributes: { friendly_name: 'Living Room Humidity' } },
-      };
-
-      const result = await handler({ sensors: sensorData }, mockExtra);
-      const parsed = parseResult(result);
-
-      expect(parsed).toEqual(mockAnalysis);
-      expect(aiClient.analyzeSensors).toHaveBeenCalledWith(sensorData);
-    });
-
-    it('should handle empty sensor object', async () => {
-      const aiClient = createMockAIClient();
-      const mockAnalysis = { summary: 'No sensors provided for analysis', issues: [], recommendations: [] };
-      (aiClient.analyzeSensors as ReturnType<typeof vi.fn>).mockResolvedValue(mockAnalysis);
-
-      registerAnalyzeSensorsTool(server, aiClient);
-      const handler = server.handlers.get('analyzeSensors')!.handler;
-
-      const result = await handler({ sensors: {} }, mockExtra);
-      const parsed = parseResult(result);
-
-      expect(parsed).toEqual(mockAnalysis);
-      expect(aiClient.analyzeSensors).toHaveBeenCalledWith({});
-    });
-  });
-
-  describe('AI Client Error Handling', () => {
-    it('should handle AI client errors gracefully', async () => {
-      const aiClient = createMockAIClient();
-      (aiClient.analyzeSensors as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('Ollama connection failed'));
-
-      registerAnalyzeSensorsTool(server, aiClient);
-      const handler = server.handlers.get('analyzeSensors')!.handler;
-
-      const sensorData = { 'sensor.test': { state: '10' } };
-      const result = await handler({ sensors: sensorData }, mockExtra);
-      const parsed = parseResult(result) as { error: string; message: string };
-
-      expect(parsed.error).toBe('Failed to execute analyzeSensors');
-      expect(parsed.message).toContain('Ollama connection failed');
-    });
-
-    it('should handle timeout errors', async () => {
-      const aiClient = createMockAIClient();
-      (aiClient.analyzeSensors as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('Request timeout'));
-
-      registerAnalyzeSensorsTool(server, aiClient);
-      const handler = server.handlers.get('analyzeSensors')!.handler;
-
-      const sensorData = { 'sensor.test': { state: '10' } };
-      const result = await handler({ sensors: sensorData }, mockExtra);
-      const parsed = parseResult(result) as { error: string; message: string };
-
-      expect(parsed.error).toBe('Failed to execute analyzeSensors');
-      expect(parsed.message).toContain('timeout');
-    });
-  });
-
-  describe('Permission Enforcement', () => {
-    it('should deny access without AI permission', async () => {
-      const aiClient = createMockAIClient();
-      registerAnalyzeSensorsTool(server, aiClient);
-      const handler = server.handlers.get('analyzeSensors')!.handler;
-
-      const sensorData = { 'sensor.test': { state: '10' } };
-      const result = await handler({ sensors: sensorData }, noAiPermExtra);
-      const parsed = parseResult(result) as { error: string; message: string };
-
-      expect(parsed.error).toBe('Permission denied');
-      expect(parsed.message).toContain('AI');
-      expect(aiClient.analyzeSensors).not.toHaveBeenCalled();
-    });
-
-    it('should allow access with AI permission', async () => {
-      const aiClient = createMockAIClient();
-      const mockAnalysis = { summary: 'Analysis complete', issues: [], recommendations: [] };
-      (aiClient.analyzeSensors as ReturnType<typeof vi.fn>).mockResolvedValue(mockAnalysis);
-
-      registerAnalyzeSensorsTool(server, aiClient);
-      const handler = server.handlers.get('analyzeSensors')!.handler;
-
-      const sensorData = { 'sensor.test': { state: '10' } };
-      const result = await handler({ sensors: sensorData }, mockExtra);
-      const parsed = parseResult(result);
-
-      expect(parsed).toEqual(mockAnalysis);
-      expect(aiClient.analyzeSensors).toHaveBeenCalled();
-    });
-  });
-});

package/tests/tools/common.test.ts

@@ -1,123 +0,0 @@
-/**
- * Common tool utilities tests
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import { wrapToolHandler, toToolResult, Permission } from '../../src/tools/common.js';
-import type { ToolExtra } from '../../src/tools/common.js';
-
-describe('toToolResult', () => {
-  it('should convert string to text content', () => {
-    const result = toToolResult('hello');
-    expect(result.content).toEqual([{ type: 'text', text: 'hello' }]);
-    expect(result.isError).toBe(false);
-  });
-
-  it('should convert object to JSON text content', () => {
-    const result = toToolResult({ foo: 'bar' });
-    expect(result.content[0].type).toBe('text');
-    expect(JSON.parse((result.content[0] as { text: string }).text)).toEqual({ foo: 'bar' });
-  });
-
-  it('should set isError when specified', () => {
-    const result = toToolResult('error', true);
-    expect(result.isError).toBe(true);
-  });
-});
-
-describe('wrapToolHandler permission checks', () => {
-  // Helper to create ToolExtra with permissions in http.authInfo.extra (MCP SDK v2 context
-  // shape). No permissions => no `http` at all, as on a request without auth info.
-  const createExtra = (permissions?: number): ToolExtra =>
-    ({
-      sessionId: 'test-session',
-      mcpReq: { id: 1, signal: new AbortController().signal },
-      ...(permissions !== undefined
-        ? { http: { authInfo: { token: 'test-token', clientId: 'test-client', scopes: [], extra: { permissions } } } }
-        : {}),
-    }) as unknown as ToolExtra;
-
-  it('should allow access when user has required permission', async () => {
-    const handler = vi.fn().mockResolvedValue(toToolResult('success'));
-    const wrapped = wrapToolHandler('testTool', handler, Permission.QUERY);
-
-    const extra = createExtra(Permission.QUERY);
-    const result = await wrapped({}, extra);
-
-    expect(handler).toHaveBeenCalled();
-    expect(result.isError).toBe(false);
-  });
-
-  it('should deny access when user lacks required permission', async () => {
-    const handler = vi.fn().mockResolvedValue(toToolResult('success'));
-    const wrapped = wrapToolHandler('testTool', handler, Permission.ADMIN);
-
-    const extra = createExtra(Permission.QUERY); // Only QUERY, not ADMIN
-    const result = await wrapped({}, extra);
-
-    expect(handler).not.toHaveBeenCalled();
-    expect(result.isError).toBe(true);
-    const text = (result.content[0] as { text: string }).text;
-    expect(text).toContain('Permission denied');
-    expect(text).toContain('ADMIN');
-  });
-
-  it('should allow access with combined permissions', async () => {
-    const handler = vi.fn().mockResolvedValue(toToolResult('success'));
-    const wrapped = wrapToolHandler('testTool', handler, Permission.CONTROL);
-
-    // User has QUERY | CONTROL | NOTIFY
-    const extra = createExtra(Permission.QUERY | Permission.CONTROL | Permission.NOTIFY);
-    const result = await wrapped({}, extra);
-
-    expect(handler).toHaveBeenCalled();
-    expect(result.isError).toBe(false);
-  });
-
-  it('should fail closed (deny) when authInfo is not set (L3)', async () => {
-    const handler = vi.fn().mockResolvedValue(toToolResult('success'));
-    const wrapped = wrapToolHandler('testTool', handler, Permission.ADMIN);
-
-    // A missing permission mask must DENY, not default-allow. The trusted-local
-    // stdio path opts into full trust separately (see insecureDesign.test.ts).
-    const extra = createExtra(undefined);
-    const result = await wrapped({}, extra);
-
-    expect(handler).not.toHaveBeenCalled();
-    expect(result.isError).toBe(true);
-  });
-
-  it('should allow access when no permission required', async () => {
-    const handler = vi.fn().mockResolvedValue(toToolResult('success'));
-    const wrapped = wrapToolHandler('testTool', handler); // No permission required
-
-    const extra = createExtra(0); // No permissions
-    const result = await wrapped({}, extra);
-
-    expect(handler).toHaveBeenCalled();
-    expect(result.isError).toBe(false);
-  });
-
-  it('should catch and handle errors from handler', async () => {
-    const handler = vi.fn().mockRejectedValue(new Error('Something went wrong'));
-    const wrapped = wrapToolHandler('testTool', handler, Permission.QUERY);
-
-    const extra = createExtra(Permission.QUERY);
-    const result = await wrapped({}, extra);
-
-    expect(result.isError).toBe(true);
-    const text = (result.content[0] as { text: string }).text;
-    expect(text).toContain('Something went wrong');
-  });
-});
-
-describe('Permission values', () => {
-  it('should have correct bit values sorted by criticality', () => {
-    expect(Permission.ADMIN).toBe(1);      // Highest criticality
-    expect(Permission.CONFIGURE).toBe(2);
-    expect(Permission.CONTROL).toBe(4);
-    expect(Permission.QUERY).toBe(8);
-    expect(Permission.NOTIFY).toBe(16);
-    expect(Permission.AI).toBe(32);
-  });
-});