@dpesch/mantisbt-mcp-server 1.0.3 → 1.2.0

package/tests/tools/files.test.ts

@@ -0,0 +1,274 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { MantisClient } from '../../src/client.js';
+import { registerFileTools } from '../../src/tools/files.js';
+import { MockMcpServer, makeResponse } from '../helpers/mock-server.js';
+
+vi.mock('node:fs/promises', () => ({
+  readFile: vi.fn(),
+}));
+
+// Import after mock so the mock is in place
+import { readFile } from 'node:fs/promises';
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+let mockServer: MockMcpServer;
+let client: MantisClient;
+
+beforeEach(() => {
+  mockServer = new MockMcpServer();
+  client = new MantisClient('https://mantis.example.com', 'test-token');
+  registerFileTools(mockServer as never, client);
+  vi.stubGlobal('fetch', vi.fn());
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.clearAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// list_issue_files
+// ---------------------------------------------------------------------------
+
+describe('list_issue_files', () => {
+  it('is registered', () => {
+    expect(mockServer.hasToolRegistered('list_issue_files')).toBe(true);
+  });
+
+  it('returns an attachment array', async () => {
+    const apiResponse = {
+      issues: [{
+        id: 42,
+        attachments: [
+          { id: 1, file_name: 'screenshot.png', size: 12345, content_type: 'image/png' },
+        ],
+      }],
+    };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(apiResponse)));
+
+    const result = await mockServer.callTool('list_issue_files', { issue_id: 42 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as Array<{ file_name: string }>;
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed[0]!.file_name).toBe('screenshot.png');
+  });
+
+  it('returns an empty array when there are no attachments', async () => {
+    const apiResponse = { issues: [{ id: 42 }] };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(apiResponse)));
+
+    const result = await mockServer.callTool('list_issue_files', { issue_id: 42 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as unknown[];
+    expect(parsed).toEqual([]);
+  });
+
+  it('calls the correct endpoint', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ issues: [{ id: 42 }] })));
+
+    await mockServer.callTool('list_issue_files', { issue_id: 42 });
+
+    const calledUrl = vi.mocked(fetch).mock.calls[0]![0] as string;
+    expect(calledUrl).toContain('issues/42');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// upload_file – file_path mode
+// ---------------------------------------------------------------------------
+
+describe('upload_file', () => {
+  it('is registered', () => {
+    expect(mockServer.hasToolRegistered('upload_file')).toBe(true);
+  });
+
+  it('reads the file and posts to the correct endpoint', async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('file content') as never);
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5, file_name: 'report.pdf' })));
+
+    await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/report.pdf' });
+
+    expect(readFile).toHaveBeenCalledWith('/tmp/report.pdf');
+    const calledUrl = vi.mocked(fetch).mock.calls[0]![0] as string;
+    expect(calledUrl).toContain('issues/42/files');
+  });
+
+  it('sends a POST request with FormData', async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5 })));
+
+    await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/test.txt' });
+
+    const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
+    expect(options.method).toBe('POST');
+    expect(options.body).toBeInstanceOf(FormData);
+  });
+
+  it('does not set Content-Type header (set automatically by fetch)', async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5 })));
+
+    await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/test.txt' });
+
+    const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
+    const headers = options.headers as Record<string, string>;
+    expect(headers['Content-Type']).toBeUndefined();
+  });
+
+  it('appends description when provided', async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5 })));
+
+    await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/test.txt', description: 'My attachment' });
+
+    const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
+    const formData = options.body as FormData;
+    expect(formData.get('description')).toBe('My attachment');
+  });
+
+  it('returns the API response', async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
+    const apiResponse = { id: 5, file_name: 'report.pdf', size: 7 };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(apiResponse)));
+
+    const result = await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/report.pdf' });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { file_name: string };
+    expect(parsed.file_name).toBe('report.pdf');
+  });
+
+  it('returns isError when the file is not found', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error("ENOENT: no such file or directory, open '/tmp/missing.txt'") as never);
+
+    const result = await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/missing.txt' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('Error:');
+  });
+
+  it('returns isError on API error', async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
+    vi.mocked(fetch).mockResolvedValue(makeResponse(403, JSON.stringify({ message: 'Forbidden' })));
+
+    const result = await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/test.txt' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('Error:');
+  });
+
+  it('overrides the filename when filename is provided', async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5 })));
+
+    await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/report.pdf', filename: 'custom-name.pdf' });
+
+    const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
+    const formData = options.body as FormData;
+    const fileEntry = formData.get('file') as File;
+    expect(fileEntry.name).toBe('custom-name.pdf');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// upload_file – Base64 mode
+// ---------------------------------------------------------------------------
+
+describe('upload_file (Base64)', () => {
+  it('decodes Base64 content and uploads it', async () => {
+    const originalContent = 'Hello, World!';
+    const base64Content = Buffer.from(originalContent).toString('base64');
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 7, file_name: 'hello.txt' })));
+
+    const result = await mockServer.callTool('upload_file', {
+      issue_id: 42,
+      content: base64Content,
+      filename: 'hello.txt',
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(readFile).not.toHaveBeenCalled();
+    const calledUrl = vi.mocked(fetch).mock.calls[0]![0] as string;
+    expect(calledUrl).toContain('issues/42/files');
+  });
+
+  it('uses the provided filename', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 7 })));
+
+    await mockServer.callTool('upload_file', {
+      issue_id: 42,
+      content: Buffer.from('data').toString('base64'),
+      filename: 'export.csv',
+    });
+
+    const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
+    const formData = options.body as FormData;
+    const fileEntry = formData.get('file') as File;
+    expect(fileEntry.name).toBe('export.csv');
+  });
+
+  it('sets the content_type when provided', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 7 })));
+
+    await mockServer.callTool('upload_file', {
+      issue_id: 42,
+      content: Buffer.from('data').toString('base64'),
+      filename: 'image.png',
+      content_type: 'image/png',
+    });
+
+    const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
+    const formData = options.body as FormData;
+    const fileEntry = formData.get('file') as File;
+    expect(fileEntry.type).toBe('image/png');
+  });
+
+  it('returns isError when neither file_path nor content is provided', async () => {
+    const result = await mockServer.callTool('upload_file', { issue_id: 42 });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('Either file_path or content');
+  });
+
+  it('returns isError when both file_path and content are provided', async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('x') as never);
+
+    const result = await mockServer.callTool('upload_file', {
+      issue_id: 42,
+      file_path: '/tmp/test.txt',
+      content: Buffer.from('x').toString('base64'),
+      filename: 'test.txt',
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('Only one of');
+  });
+
+  it('returns isError when content is provided without filename', async () => {
+    const result = await mockServer.callTool('upload_file', {
+      issue_id: 42,
+      content: Buffer.from('data').toString('base64'),
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('filename is required');
+  });
+
+  it('returns isError on API error', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(500, JSON.stringify({ message: 'Internal Server Error' })));
+
+    const result = await mockServer.callTool('upload_file', {
+      issue_id: 42,
+      content: Buffer.from('data').toString('base64'),
+      filename: 'test.txt',
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('Error:');
+  });
+});

package/tests/tools/issues.test.ts

@@ -4,7 +4,8 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MantisClient } from '../../src/client.js';
 import { registerIssueTools } from '../../src/tools/issues.js';
-import { MockMcpServer } from '../helpers/mock-server.js';
+import { MockMcpServer, makeResponse } from '../helpers/mock-server.js';
+import { MANTIS_RESOLVED_STATUS_ID } from '../../src/constants.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -22,22 +23,13 @@ const getIssueFixture = existsSync(getIssueFixturePath)
   : { issues: [{ id: 42, summary: 'Test Issue' }] };
 
 const listIssuesFixture = existsSync(listIssuesFixturePath)
-  ? (JSON.parse(readFileSync(listIssuesFixturePath, 'utf-8')) as { issues: Array<{ id: number; summary: string }>; total_count: number })
-  : { issues: [{ id: 42, summary: 'Test Issue' }], total_count: 1 };
+  ? (JSON.parse(readFileSync(listIssuesFixturePath, 'utf-8')) as { issues: Array<{ id: number; summary: string; status: { id: number; name: string } }>; total_count: number })
+  : { issues: [{ id: 42, summary: 'Test Issue', status: { id: 80, name: 'resolved' } }], total_count: 1 };
 
-// ---------------------------------------------------------------------------
-// Helper: minimale Response nachbauen
-// ---------------------------------------------------------------------------
-
-function makeResponse(status: number, body: string): Response {
-  return {
-    ok: status >= 200 && status < 300,
-    status,
-    statusText: `Status ${status}`,
-    text: () => Promise.resolve(body),
-    headers: { get: (_key: string) => null },
-  } as unknown as Response;
-}
+const recordedListIssuesPath = join(fixturesDir, 'recorded', 'list_issues.json');
+const recordedListIssuesFixture = existsSync(recordedListIssuesPath)
+  ? (JSON.parse(readFileSync(recordedListIssuesPath, 'utf-8')) as { issues: Array<{ id: number; summary: string; status: { id: number; name: string } }> })
+  : null;
 
 // ---------------------------------------------------------------------------
 // Setup
@@ -127,4 +119,93 @@ describe('list_issues', () => {
     const url = new URL(calledUrl);
     expect(url.searchParams.get('project_id')).toBe('7');
   });
+
+  it('passes select as query parameter', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    await mockServer.callTool('list_issues', { select: 'id,summary,status', page: 1, page_size: 10 });
+
+    const calledUrl = vi.mocked(fetch).mock.calls[0]![0] as string;
+    const url = new URL(calledUrl);
+    expect(url.searchParams.get('select')).toBe('id,summary,status');
+  });
+
+  it('status "open" filters to issues with status.id < 80', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'open', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: Array<{ status: { id: number } }> };
+    expect(parsed.issues.length).toBeGreaterThan(0);
+    parsed.issues.forEach(issue => {
+      expect(issue.status.id).toBeLessThan(MANTIS_RESOLVED_STATUS_ID);
+    });
+  });
+
+  it('status "resolved" filters to resolved issues only', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'resolved', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: Array<{ status: { name: string } }> };
+    expect(parsed.issues.length).toBeGreaterThan(0);
+    parsed.issues.forEach(issue => {
+      expect(issue.status.name).toBe('resolved');
+    });
+  });
+
+  it('status "new" filters to new issues only', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'new', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: Array<{ id: number; status: { name: string } }> };
+    expect(parsed.issues).toHaveLength(1);
+    expect(parsed.issues[0]!.id).toBe(7901);
+    expect(parsed.issues[0]!.status.name).toBe('new');
+  });
+
+  it('status filter is case-insensitive', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+    const resultUpper = await mockServer.callTool('list_issues', { status: 'OPEN', page: 1, page_size: 50 });
+
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+    const resultLower = await mockServer.callTool('list_issues', { status: 'open', page: 1, page_size: 50 });
+
+    const parsedUpper = JSON.parse(resultUpper.content[0]!.text) as { issues: unknown[] };
+    const parsedLower = JSON.parse(resultLower.content[0]!.text) as { issues: unknown[] };
+    expect(parsedUpper.issues.length).toBe(parsedLower.issues.length);
+    expect(parsedUpper.issues).toEqual(parsedLower.issues);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// list_issues – recorded fixtures
+// ---------------------------------------------------------------------------
+
+describe('list_issues – recorded fixtures', () => {
+  it.skipIf(!recordedListIssuesFixture)('status "open" filter matches open issues in recorded fixture', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(recordedListIssuesFixture!)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'open', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: unknown[] };
+    const openInFixture = recordedListIssuesFixture!.issues.filter(i => i.status.id < 80).length;
+    expect(parsed.issues).toHaveLength(openInFixture);
+  });
+
+  it.skipIf(!recordedListIssuesFixture)('status "resolved" filter matches resolved issues in recorded fixture', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(recordedListIssuesFixture!)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'resolved', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: unknown[] };
+    const resolvedInFixture = recordedListIssuesFixture!.issues.filter(i => i.status.id >= 80).length;
+    expect(parsed.issues).toHaveLength(resolvedInFixture);
+  });
 });

package/tests/tools/metadata.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// vi.mock must be at module top level — vitest hoists it automatically
+vi.mock('node:fs/promises');
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { MantisClient } from '../../src/client.js';
+import { MetadataCache, type CachedMetadata } from '../../src/cache.js';
+import { registerMetadataTools } from '../../src/tools/metadata.js';
+import { MockMcpServer, makeResponse } from '../helpers/mock-server.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const recordedFixturesDir = join(__dirname, '..', 'fixtures', 'recorded');
+
+// Recorded fixture: single issue returned by issues?page=1&page_size=1
+const sampleFixturePath = join(recordedFixturesDir, 'get_issue_fields_sample.json');
+const recordedSampleFixture = existsSync(sampleFixturePath)
+  ? (JSON.parse(readFileSync(sampleFixturePath, 'utf-8')) as { issues: Array<Record<string, unknown>> })
+  : null;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const CACHE_DIR = '/tmp/test-cache-metadata';
+const TTL = 3600;
+
+function makeServer(): MockMcpServer {
+  return new MockMcpServer();
+}
+
+function makeClient(): MantisClient {
+  return new MantisClient('https://mantis.example.com', 'test-token');
+}
+
+function makeCache(): MetadataCache {
+  return new MetadataCache(CACHE_DIR, TTL);
+}
+
+function makeSampleMetadata(): CachedMetadata {
+  return {
+    timestamp: Date.now(),
+    projects: [{ id: 1, name: 'Test Project' }],
+    byProject: {},
+  };
+}
+
+function makeValidMetadataCacheFile(data: CachedMetadata): string {
+  return JSON.stringify({ timestamp: Date.now(), data });
+}
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+let mockServer: MockMcpServer;
+let client: MantisClient;
+let cache: MetadataCache;
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  mockServer = makeServer();
+  client = makeClient();
+  cache = makeCache();
+  registerMetadataTools(mockServer as never, client, cache);
+  vi.stubGlobal('fetch', vi.fn());
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// ---------------------------------------------------------------------------
+// get_metadata
+// ---------------------------------------------------------------------------
+
+describe('get_metadata', () => {
+  it('is registered', () => {
+    expect(mockServer.hasToolRegistered('get_metadata')).toBe(true);
+  });
+
+  it('loads from cache when valid (single file read — no re-fetch)', async () => {
+    const metadata = makeSampleMetadata();
+    vi.mocked(readFile).mockResolvedValue(makeValidMetadataCacheFile(metadata) as any);
+
+    const result = await mockServer.callTool('get_metadata', {});
+
+    expect(result.isError).toBeUndefined();
+    // fetch must NOT have been called — data came from cache
+    expect(fetch).not.toHaveBeenCalled();
+    const parsed = JSON.parse(result.content[0]!.text) as CachedMetadata;
+    expect(parsed.projects).toEqual(metadata.projects);
+  });
+
+  it('fetches and caches when cache is missing', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const projectsResponse = { projects: [{ id: 1, name: 'Test Project' }] };
+    const emptyResponse = { users: [], versions: [], categories: [] };
+    vi.mocked(fetch)
+      .mockResolvedValueOnce(makeResponse(200, JSON.stringify(projectsResponse)))
+      .mockResolvedValue(makeResponse(200, JSON.stringify(emptyResponse)));
+
+    const result = await mockServer.callTool('get_metadata', {});
+
+    expect(result.isError).toBeUndefined();
+    expect(fetch).toHaveBeenCalled();
+    expect(writeFile).toHaveBeenCalled();
+    const writtenPath = vi.mocked(writeFile).mock.calls[0]![0] as string;
+    expect(writtenPath).toContain('metadata.json');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// get_issue_fields
+// ---------------------------------------------------------------------------
+
+describe('get_issue_fields', () => {
+  it('is registered', () => {
+    expect(mockServer.hasToolRegistered('get_issue_fields')).toBe(true);
+  });
+
+  it('returns cached fields when cache is valid', async () => {
+    const cachedFields = ['id', 'summary', 'status', 'priority', 'attachments'];
+    const cacheFile = JSON.stringify({ timestamp: Date.now(), fields: cachedFields });
+
+    // loadIssueFields reads from issue_fields.json
+    vi.mocked(readFile).mockImplementation(async (path) => {
+      if (String(path).includes('issue_fields.json')) {
+        return cacheFile as any;
+      }
+      throw new Error('ENOENT');
+    });
+
+    const result = await mockServer.callTool('get_issue_fields', {});
+
+    expect(result.isError).toBeUndefined();
+    // fetch must NOT have been called — data came from cache
+    expect(fetch).not.toHaveBeenCalled();
+    const parsed = JSON.parse(result.content[0]!.text) as { fields: string[]; source: string };
+    expect(parsed.source).toBe('cache');
+    expect(parsed.fields).toEqual(cachedFields);
+  });
+
+  it('fetches sample issue and discovers fields', async () => {
+    // Cache miss
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const sampleIssue = {
+      id: 42,
+      summary: 'Sample',
+      status: { id: 10, name: 'new' },
+      priority: { id: 30, name: 'normal' },
+      reporter: { id: 1, name: 'user' },
+    };
+    const issuesResponse = { issues: [sampleIssue] };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(issuesResponse)));
+
+    const result = await mockServer.callTool('get_issue_fields', {});
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { fields: string[]; source: string };
+    expect(parsed.source).toBe('live');
+    // Fields from sample issue
+    expect(parsed.fields).toContain('id');
+    expect(parsed.fields).toContain('summary');
+    expect(parsed.fields).toContain('status');
+    // Fields from EMPTY_STRIPPED_FIELDS that are always merged in
+    expect(parsed.fields).toContain('attachments');
+    expect(parsed.fields).toContain('notes');
+    expect(parsed.fields).toContain('relationships');
+  });
+
+  it('falls back to static list when no issues available', async () => {
+    // Cache miss
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const emptyIssuesResponse = { issues: [] };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(emptyIssuesResponse)));
+
+    const result = await mockServer.callTool('get_issue_fields', {});
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { fields: string[]; source: string };
+    expect(parsed.source).toBe('static');
+    // Static list must contain common fields
+    expect(parsed.fields).toContain('id');
+    expect(parsed.fields).toContain('summary');
+    expect(parsed.fields).toContain('status');
+    expect(parsed.fields).toContain('attachments');
+    expect(parsed.fields).toContain('notes');
+  });
+
+  it('caches discovered fields after fetching', async () => {
+    // Cache miss
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const sampleIssue = { id: 1, summary: 'Test', status: { id: 10, name: 'new' } };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ issues: [sampleIssue] })));
+
+    await mockServer.callTool('get_issue_fields', {});
+
+    // writeFile must have been called with issue_fields.json path
+    expect(writeFile).toHaveBeenCalled();
+    const writtenPath = vi.mocked(writeFile).mock.calls.find(
+      call => String(call[0]).includes('issue_fields.json')
+    );
+    expect(writtenPath).toBeDefined();
+
+    // Written content must be valid JSON with a fields array
+    const writtenContent = writtenPath![1] as string;
+    const parsed = JSON.parse(writtenContent) as { timestamp: number; fields: string[] };
+    expect(Array.isArray(parsed.fields)).toBe(true);
+    expect(parsed.fields.length).toBeGreaterThan(0);
+    expect(typeof parsed.timestamp).toBe('number');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// get_issue_fields – recorded fixtures
+// ---------------------------------------------------------------------------
+
+describe('get_issue_fields – recorded fixtures', () => {
+  it.skipIf(!recordedSampleFixture)('discovers fields from recorded sample issue', async () => {
+    // Cache miss — force live discovery
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(recordedSampleFixture!)));
+
+    const result = await mockServer.callTool('get_issue_fields', {});
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { fields: string[]; source: string };
+    expect(parsed.source).toBe('live');
+
+    // Every top-level key of the recorded sample issue must be in the discovered fields
+    const sampleKeys = Object.keys(recordedSampleFixture!.issues[0]!);
+    for (const key of sampleKeys) {
+      expect(parsed.fields).toContain(key);
+    }
+
+    // EMPTY_STRIPPED_FIELDS must always be present even if absent from the sample
+    expect(parsed.fields).toContain('attachments');
+    expect(parsed.fields).toContain('notes');
+    expect(parsed.fields).toContain('relationships');
+  });
+});