@daghis/teamcity-mcp 0.1.2

package/tests/unit/tools/queue-maintenance.test.ts

@@ -0,0 +1,130 @@
+// Full mode for write tools
+jest.mock('@/config', () => ({
+  getTeamCityUrl: () => 'https://example.test',
+  getTeamCityToken: () => 'token',
+  getMCPMode: () => 'full',
+}));
+
+describe('tools: queue maintenance operations', () => {
+  afterEach(() => {
+    jest.resetModules();
+    jest.clearAllMocks();
+  });
+
+  it('move_queued_build_to_top calls setQueuedBuildsOrder and returns JSON', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const setQueuedBuildsOrder = jest.fn(async () => ({ data: {} }));
+          jest.doMock('@/api-client', () => ({
+            TeamCityAPI: { getInstance: () => ({ buildQueue: { setQueuedBuildsOrder } }) },
+          }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          const res = await getRequiredTool('move_queued_build_to_top').handler({ buildId: '123' });
+          const payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({
+            success: true,
+            action: 'move_queued_build_to_top',
+            buildId: '123',
+          });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+
+  it('reorder_queued_builds sets desired order and returns JSON with count', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const setQueuedBuildsOrder = jest.fn(async () => ({ data: {} }));
+          jest.doMock('@/api-client', () => ({
+            TeamCityAPI: { getInstance: () => ({ buildQueue: { setQueuedBuildsOrder } }) },
+          }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          const res = await getRequiredTool('reorder_queued_builds').handler({
+            buildIds: ['1', '2'],
+          });
+          const payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({
+            success: true,
+            action: 'reorder_queued_builds',
+            count: 2,
+          });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+
+  it('cancel_queued_builds_for_build_type cancels only matching builds', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const getAllQueuedBuilds = jest.fn(async () => ({
+            data: {
+              build: [
+                { id: 1, buildTypeId: 'bt1' },
+                { id: 2, buildTypeId: 'bt2' },
+                { id: 3, buildTypeId: 'bt1' },
+              ],
+              count: 3,
+            },
+          }));
+          const deleteQueuedBuild = jest.fn(async () => ({ data: {} }));
+          jest.doMock('@/api-client', () => ({
+            TeamCityAPI: {
+              getInstance: () => ({ buildQueue: { getAllQueuedBuilds, deleteQueuedBuild } }),
+            },
+          }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          const res = await getRequiredTool('cancel_queued_builds_for_build_type').handler({
+            buildTypeId: 'bt1',
+          });
+          const payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({
+            success: true,
+            action: 'cancel_queued_builds_for_build_type',
+            buildTypeId: 'bt1',
+            canceled: 2,
+          });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+
+  it('cancel_queued_builds_by_locator cancels all returned builds', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const getAllQueuedBuilds = jest.fn(async () => ({
+            data: { build: [{ id: 10 }, { id: 11 }], count: 2 },
+          }));
+          const deleteQueuedBuild = jest.fn(async () => ({ data: {} }));
+          jest.doMock('@/api-client', () => ({
+            TeamCityAPI: {
+              getInstance: () => ({ buildQueue: { getAllQueuedBuilds, deleteQueuedBuild } }),
+            },
+          }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          const res = await getRequiredTool('cancel_queued_builds_by_locator').handler({
+            locator: 'project:(id:P1)',
+          });
+          const payload = JSON.parse(res.content?.[0]?.text as string) ?? '{}';
+          expect(payload).toMatchObject({
+            success: true,
+            action: 'cancel_queued_builds_by_locator',
+            locator: 'project:(id:P1)',
+            canceled: 2,
+          });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+});

package/tests/unit/tools/server-health-and-metrics.test.ts

@@ -0,0 +1,134 @@
+// Force dev mode for read-only tools
+// Use required tool helper to avoid undefined checks
+
+jest.mock('@/config', () => ({
+  getTeamCityUrl: () => 'https://example.test',
+  getTeamCityToken: () => 'token',
+  // Metrics and health item tools are full-mode only
+  getMCPMode: () => 'full',
+}));
+
+describe('tools: server health & metrics', () => {
+  afterEach(() => {
+    jest.resetModules();
+    jest.clearAllMocks();
+  });
+
+  it('get_server_info returns server info JSON', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const server = {
+            getServerInfo: jest.fn(async () => ({
+              data: { version: '2024.1', buildNumber: '99999' },
+            })),
+          };
+          jest.doMock('@/api-client', () => ({ TeamCityAPI: { getInstance: () => ({ server }) } }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          const res = await getRequiredTool('get_server_info').handler({});
+          const payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({ version: '2024.1', buildNumber: '99999' });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+
+  it('get_server_metrics returns metrics JSON', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const server = {
+            getAllMetrics: jest.fn(async () => ({
+              data: { metrics: [{ name: 'cpu.load', value: 0.5 }] },
+            })),
+          };
+          jest.doMock('@/api-client', () => ({ TeamCityAPI: { getInstance: () => ({ server }) } }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          const res = await getRequiredTool('get_server_metrics').handler({});
+          const payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({ metrics: [{ name: 'cpu.load', value: 0.5 }] });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+
+  it('list_server_health_items returns health items and get_server_health_item returns one item', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const health = {
+            getHealthItems: jest.fn(async () => ({
+              data: {
+                healthItem: [
+                  { id: 'A', severity: 'INFO' },
+                  { id: 'B', severity: 'ERROR' },
+                ],
+              },
+            })),
+            getSingleHealthItem: jest.fn(async () => ({ data: { id: 'B', severity: 'ERROR' } })),
+          };
+          jest.doMock('@/api-client', () => ({ TeamCityAPI: { getInstance: () => ({ health }) } }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          let res = await getRequiredTool('list_server_health_items').handler({
+            locator: 'severity:ERROR',
+          });
+          let payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(Array.isArray(payload.healthItem)).toBe(true);
+
+          res = await getRequiredTool('get_server_health_item').handler({ locator: 'id:B' });
+          payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({ id: 'B', severity: 'ERROR' });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+
+  it('check_availability_guard returns ok=false on ERRORs and warnings when flagged', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const health = {
+            getHealthItems: jest.fn(async () => ({
+              data: {
+                healthItem: [
+                  { id: 'B', severity: 'ERROR' },
+                  { id: 'C', severity: 'WARNING' },
+                ],
+              },
+            })),
+          };
+          jest.doMock('@/api-client', () => ({ TeamCityAPI: { getInstance: () => ({ health }) } }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          let res = await getRequiredTool('check_availability_guard').handler({});
+          let payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload.ok).toBe(false); // has ERROR
+
+          // Re-mock to only warnings
+          jest.resetModules();
+          jest.isolateModules(() => {});
+          const healthWarn = {
+            getHealthItems: jest.fn(async () => ({
+              data: { healthItem: [{ id: 'W', severity: 'WARNING' }] },
+            })),
+          };
+          jest.doMock('@/api-client', () => ({
+            TeamCityAPI: { getInstance: () => ({ health: healthWarn }) },
+          }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool: loadRequired } = require('@/tools');
+          res = await loadRequired('check_availability_guard').handler({ failOnWarning: true });
+          payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload.ok).toBe(false); // fail on warnings
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+});

package/tests/unit/tools/simple-getters.test.ts

@@ -0,0 +1,88 @@
+// Dev mode ok for getters/ping
+// Use required tool helper to avoid undefined checks
+
+jest.mock('@/config', () => ({
+  getTeamCityUrl: () => 'https://example.test',
+  getTeamCityToken: () => 'token',
+  getMCPMode: () => 'dev',
+}));
+
+describe('tools: simple getters and utilities', () => {
+  afterEach(() => {
+    jest.resetModules();
+    jest.clearAllMocks();
+  });
+
+  it('get_project and get_build_config return JSON passthrough', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const getProject = jest.fn(async () => ({ id: 'P1', name: 'Proj' }));
+          const getBuildType = jest.fn(async () => ({ id: 'BT1', name: 'Build' }));
+          jest.doMock('@/api-client', () => ({
+            TeamCityAPI: { getInstance: () => ({ getProject, getBuildType }) },
+          }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          let res = await getRequiredTool('get_project').handler({ projectId: 'P1' });
+          let payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({ id: 'P1' });
+          res = await getRequiredTool('get_build_config').handler({ buildTypeId: 'BT1' });
+          payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({ id: 'BT1' });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+
+  it('get_test_details returns JSON occurrences', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const getAllTestOccurrences = jest.fn(async () => ({
+            data: { testOccurrence: [{ name: 't1' }] },
+          }));
+          jest.doMock('@/api-client', () => ({
+            TeamCityAPI: { getInstance: () => ({ tests: { getAllTestOccurrences } }) },
+          }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          const res = await getRequiredTool('get_test_details').handler({ buildId: 'b1' });
+          const payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({ testOccurrence: [{ name: 't1' }] });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+
+  it('check_teamcity_connection returns { ok }', async () => {
+    await new Promise<void>((resolve, reject) => {
+      jest.isolateModules(() => {
+        (async () => {
+          const testConnection = jest.fn(async () => true);
+          jest.doMock('@/api-client', () => ({
+            TeamCityAPI: { getInstance: () => ({ testConnection }) },
+          }));
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { getRequiredTool } = require('@/tools');
+          const res = await getRequiredTool('check_teamcity_connection').handler({});
+          const payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+          expect(payload).toMatchObject({ ok: true });
+          resolve();
+        })().catch(reject);
+      });
+    });
+  });
+
+  it('ping returns pong', async () => {
+    // no mocks needed
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { getRequiredTool } = require('@/tools');
+    const res = await getRequiredTool('ping').handler({ message: 'hi' });
+    const text = (res.content?.[0]?.text as string) ?? '';
+    expect(text).toContain('pong');
+    expect(text).toContain('hi');
+  });
+});

package/tests/unit/tools/update_project_settings.test.ts

@@ -0,0 +1,64 @@
+import { TeamCityAPI } from '@/api-client';
+import { getRequiredTool } from '@/tools';
+
+describe('tools: update_project_settings', () => {
+  const prevMode = process.env['MCP_MODE'];
+  let tool: ReturnType<typeof getRequiredTool>;
+  beforeAll(() => {
+    process.env['MCP_MODE'] = 'full';
+    tool = getRequiredTool('update_project_settings');
+  });
+  afterAll(() => {
+    if (typeof prevMode === 'undefined') delete process.env['MCP_MODE'];
+    else process.env['MCP_MODE'] = prevMode;
+  });
+
+  it('updates only provided name', async () => {
+    const setProjectField = jest.fn().mockResolvedValue({});
+    jest.spyOn(TeamCityAPI, 'getInstance').mockReturnValue({
+      projects: { setProjectField },
+    } as unknown as TeamCityAPI);
+
+    const args = { projectId: 'MyProj', name: 'TeamCity MCP' };
+    const result = await tool.handler(args);
+
+    const payload = JSON.parse((result.content?.[0]?.text as string) ?? '{}');
+    expect(payload).toMatchObject({
+      success: true,
+      action: 'update_project_settings',
+      id: 'MyProj',
+    });
+  });
+
+  it('updates description and archived with proper types', async () => {
+    const setProjectField = jest.fn().mockResolvedValue({});
+    jest.spyOn(TeamCityAPI, 'getInstance').mockReturnValue({
+      projects: { setProjectField },
+    } as unknown as TeamCityAPI);
+
+    const args = { projectId: 'MyProj', description: 'Correct casing', archived: true };
+    const result = await tool.handler(args);
+    const payload = JSON.parse((result.content?.[0]?.text as string) ?? '{}');
+    expect(payload).toMatchObject({
+      success: true,
+      action: 'update_project_settings',
+      id: 'MyProj',
+    });
+  });
+
+  it('does nothing when no fields provided', async () => {
+    const setProjectField = jest.fn().mockResolvedValue({});
+    jest.spyOn(TeamCityAPI, 'getInstance').mockReturnValue({
+      projects: { setProjectField },
+    } as unknown as TeamCityAPI);
+
+    const args = { projectId: 'OnlyId' };
+    const result = await tool.handler(args);
+    const payload = JSON.parse((result.content?.[0]?.text as string) ?? '{}');
+    expect(payload).toMatchObject({
+      success: true,
+      action: 'update_project_settings',
+      id: 'OnlyId',
+    });
+  });
+});

package/tests/unit/utils/lru-cache.test.ts

@@ -0,0 +1,77 @@
+import { LRUCache } from '@/utils/lru-cache';
+
+describe('LRUCache', () => {
+  const realNow = Date.now;
+
+  afterEach(() => {
+    // Restore Date.now after time-based tests
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    Date.now = realNow;
+  });
+
+  it('gets and sets values; has/delete/clear/size/keys work', () => {
+    const cache = new LRUCache<string>({ maxSize: 3, ttl: 60_000 });
+    expect(cache.size()).toBe(0);
+    expect(cache.get('a')).toBeNull();
+    expect(cache.has('a')).toBe(false);
+
+    cache.set('a', '1');
+    cache.set('b', '2');
+    cache.set('c', '3');
+    expect(cache.size()).toBe(3);
+    expect(cache.has('a')).toBe(true);
+    expect(cache.get('a')).toBe('1');
+
+    // keys() iteration
+    const keys = Array.from(cache.keys());
+    expect(keys.length).toBe(3);
+
+    // delete
+    expect(cache.delete('b')).toBe(true);
+    expect(cache.has('b')).toBe(false);
+    expect(cache.size()).toBe(2);
+
+    // clear
+    cache.clear();
+    expect(cache.size()).toBe(0);
+  });
+
+  it('evicts least recently used when exceeding maxSize', () => {
+    const cache = new LRUCache<string>({ maxSize: 2, ttl: 60_000 });
+    cache.set('a', '1');
+    cache.set('b', '2');
+    // Access 'a' to make it most recently used
+    expect(cache.get('a')).toBe('1');
+    // Add 'c' -> should evict least recently used (which is 'b')
+    cache.set('c', '3');
+    expect(cache.has('a')).toBe(true);
+    expect(cache.has('b')).toBe(false);
+    expect(cache.has('c')).toBe(true);
+  });
+
+  it('expires entries by ttl via get/has and evictExpired()', () => {
+    const start = 1_000_000_000_000; // arbitrary epoch
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    Date.now = jest.fn(() => start);
+
+    const cache = new LRUCache<string>({ maxSize: 5, ttl: 10_000 });
+    cache.set('x', 'val');
+
+    // Advance time within TTL
+    (Date.now as unknown as jest.Mock).mockReturnValue(start + 9_000);
+    expect(cache.has('x')).toBe(true);
+    expect(cache.get('x')).toBe('val');
+
+    // Advance beyond TTL
+    (Date.now as unknown as jest.Mock).mockReturnValue(start + 11_000);
+    expect(cache.has('x')).toBe(false);
+    expect(cache.get('x')).toBeNull();
+
+    // Re-add and then evictExpired
+    (Date.now as unknown as jest.Mock).mockReturnValue(start + 12_000);
+    cache.set('y', 'val2');
+    (Date.now as unknown as jest.Mock).mockReturnValue(start + 23_000);
+    cache.evictExpired();
+    expect(cache.has('y')).toBe(false);
+  });
+});

package/tests/unit/utils/mcp.test.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+
+import { globalErrorHandler } from '@/middleware/global-error-handler';
+import { type ToolResponse, runTool } from '@/utils/mcp';
+
+const sharedLogger = {
+  generateRequestId: jest.fn(() => '123-1'),
+  logToolExecution: jest.fn(),
+};
+jest.mock('@/utils/logger/index', () => ({
+  getLogger: () => sharedLogger,
+}));
+
+jest.mock('@/middleware/error', () => ({
+  formatError: jest.fn((err: unknown) => ({ kind: 'zod', message: String(err) })),
+}));
+
+jest.mock('@/middleware/global-error-handler', () => ({
+  globalErrorHandler: {
+    handleToolError: jest.fn((_err: unknown, _tool: string, _ctx?: unknown) => ({
+      kind: 'generic',
+      msg: 'handled',
+    })),
+  },
+}));
+
+describe('utils/mcp runTool', () => {
+  it('runs tool successfully and logs execution (masks secrets)', async () => {
+    const schema = z.object({ token: z.string(), n: z.number() });
+    const handler = jest.fn(
+      async (_args: { token: string; n: number }): Promise<ToolResponse> => ({
+        success: true,
+        content: [{ type: 'text', text: 'ok' }],
+      })
+    );
+
+    const res = await runTool(
+      'echo',
+      schema,
+      handler,
+      { token: 'secret', n: 2 },
+      {
+        requestId: 'req-1',
+      }
+    );
+
+    expect(res.success).toBe(true);
+    expect(handler).toHaveBeenCalledWith({ token: 'secret', n: 2 });
+
+    // Logger was called with masked token
+    expect(sharedLogger.logToolExecution).toHaveBeenCalledWith(
+      'echo',
+      expect.objectContaining({ token: '***', n: 2 }),
+      { success: true, error: undefined },
+      expect.any(Number),
+      expect.objectContaining({ requestId: 'req-1' })
+    );
+  });
+
+  it('returns formatted Zod error output when validation fails', async () => {
+    const schema = z.object({ n: z.number() });
+    const handler = jest.fn();
+
+    const out = await runTool('sum', schema, handler, { n: 'bad' });
+    expect(out.success).toBe(true); // json() wrapper marks success true
+    expect(out.content?.[0]?.text).toContain('zod');
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('routes generic errors through globalErrorHandler and returns json result', async () => {
+    const schema = z.object({ x: z.string() }).nullable();
+    const handler = jest.fn(async () => {
+      throw new Error('boom');
+    });
+
+    const out = await runTool('f', schema, handler, { x: '1' });
+    expect(out.success).toBe(true);
+    expect(out.content?.[0]?.text).toContain('handled');
+
+    expect(globalErrorHandler.handleToolError).toHaveBeenCalled();
+  });
+});

package/tests/unit/utils/runTool.test.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+import { runTool, text } from '@/utils/mcp';
+
+describe('runTool wrapper', () => {
+  it('validates input with schema and returns success content', async () => {
+    const schema = z.object({ n: z.number().int() });
+    const handler = async (_args: { n: number }) => text('ok');
+
+    const res = await runTool('test_tool', schema, handler, { n: 1 });
+
+    expect(res.content?.[0]?.text).toBe('ok');
+  });
+
+  it('formats validation errors via global error handler', async () => {
+    const schema = z.object({ n: z.number().int() });
+    const handler = async (_args: { n: number }) => text('ok');
+
+    const res = await runTool('test_tool', schema, handler, { n: 'oops' });
+
+    // Response content is JSON-encoded error from global handler
+    const payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+    expect(payload.success).toBe(false);
+    expect(payload.error?.code).toBe('VALIDATION_ERROR');
+  });
+
+  it('formats thrown errors via global error handler', async () => {
+    const schema = z.object({});
+    const handler = async () => {
+      throw new Error('boom');
+    };
+
+    const res = await runTool('test_tool', schema, handler, {});
+    const payload = JSON.parse((res.content?.[0]?.text as string) ?? '{}');
+    expect(payload.success).toBe(false);
+    expect(payload.error?.code).toBeDefined();
+  });
+});