feat(tools): add REST query tools (sage_query, sage_read, sage_search)

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-Claude)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
2026-03-10 17:11:41 +00:00
parent badd0e55b9
commit 2de89ad718
6 changed files with 703 additions and 0 deletions

View File

@@ -0,0 +1,199 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerQueryTool } from '../sage-query.js';
import type { RestClient } from '../../clients/rest-client.js';
import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
function createMockRestClient(overrides: Partial<RestClient> = {}): RestClient {
return {
query: vi.fn().mockResolvedValue({
records: [],
pagination: { returned: 0, hasMore: false },
}),
read: vi.fn(),
listEntities: vi.fn(),
healthCheck: vi.fn(),
...overrides,
} as unknown as RestClient;
}
describe('registerQueryTool', () => {
let server: McpServer;
let registerToolSpy: ReturnType<typeof vi.spyOn>;
beforeEach(() => {
server = new McpServer({ name: 'test-server', version: '1.0.0' });
registerToolSpy = vi.spyOn(server, 'registerTool');
});
it('registers sage_query tool with correct metadata', () => {
const restClient = createMockRestClient();
registerQueryTool(server, restClient);
expect(registerToolSpy).toHaveBeenCalledOnce();
const [name, config] = registerToolSpy.mock.calls[0];
expect(name).toBe('sage_query');
expect(config).toMatchObject({
description: expect.stringContaining('Query Sage X3'),
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: true,
},
});
});
it('has inputSchema with expected fields', () => {
const restClient = createMockRestClient();
registerQueryTool(server, restClient);
const config = registerToolSpy.mock.calls[0][1] as Record<string, unknown>;
const schema = config.inputSchema as Record<string, unknown>;
expect(schema).toHaveProperty('entity');
expect(schema).toHaveProperty('representation');
expect(schema).toHaveProperty('where');
expect(schema).toHaveProperty('orderBy');
expect(schema).toHaveProperty('count');
expect(schema).toHaveProperty('nextUrl');
expect(schema).toHaveProperty('select');
});
describe('handler', () => {
async function callHandler(
restClient: RestClient,
args: Record<string, unknown> = { entity: 'BPCUSTOMER' },
): Promise<CallToolResult> {
registerQueryTool(server, restClient);
const handler = registerToolSpy.mock.calls[0][2] as (
args: Record<string, unknown>,
) => Promise<CallToolResult>;
return handler(args);
}
it('returns paginated records on success', async () => {
const mockRecords = [
{ BPCNUM: 'C001', BPCNAM: 'Acme Corp' },
{ BPCNUM: 'C002', BPCNAM: 'Widget Inc' },
];
const restClient = createMockRestClient({
query: vi.fn().mockResolvedValue({
records: mockRecords,
pagination: { returned: 2, hasMore: true, nextUrl: 'https://x3.example.com/next' },
}),
});
const result = await callHandler(restClient);
expect(result.isError).toBeUndefined();
expect(result.content).toHaveLength(1);
const parsed = JSON.parse((result.content[0] as { text: string }).text);
expect(parsed.records).toEqual(mockRecords);
expect(parsed.pagination).toEqual({
returned: 2,
hasMore: true,
nextUrl: 'https://x3.example.com/next',
});
});
it('passes all query parameters to restClient.query', async () => {
const queryMock = vi.fn().mockResolvedValue({
records: [],
pagination: { returned: 0, hasMore: false },
});
const restClient = createMockRestClient({ query: queryMock });
await callHandler(restClient, {
entity: 'SINVOICE',
representation: 'SINV$query',
where: "BPCNUM eq 'C001'",
orderBy: 'ACCDAT desc',
count: 50,
select: 'NUM,BPCNUM',
});
expect(queryMock).toHaveBeenCalledWith({
entity: 'SINVOICE',
representation: 'SINV$query',
where: "BPCNUM eq 'C001'",
orderBy: 'ACCDAT desc',
count: 50,
nextUrl: undefined,
select: 'NUM,BPCNUM',
});
});
it('passes nextUrl for pagination continuation', async () => {
const queryMock = vi.fn().mockResolvedValue({
records: [],
pagination: { returned: 0, hasMore: false },
});
const restClient = createMockRestClient({ query: queryMock });
await callHandler(restClient, {
entity: 'BPCUSTOMER',
nextUrl: 'https://x3.example.com/api1/x3/erp/SEED/BPCUSTOMER?next=abc',
});
expect(queryMock).toHaveBeenCalledWith(
expect.objectContaining({
nextUrl: 'https://x3.example.com/api1/x3/erp/SEED/BPCUSTOMER?next=abc',
}),
);
});
it('returns empty records when no results found', async () => {
const restClient = createMockRestClient({
query: vi.fn().mockResolvedValue({
records: [],
pagination: { returned: 0, hasMore: false },
}),
});
const result = await callHandler(restClient);
const parsed = JSON.parse((result.content[0] as { text: string }).text);
expect(parsed.records).toEqual([]);
expect(parsed.pagination.returned).toBe(0);
expect(parsed.pagination.hasMore).toBe(false);
});
it('returns error with hint on authentication failure', async () => {
const restClient = createMockRestClient({
query: vi.fn().mockRejectedValue(new Error('HTTP 401: Unauthorized')),
});
const result = await callHandler(restClient);
expect(result.isError).toBe(true);
const text = (result.content[0] as { text: string }).text;
expect(text).toContain('401');
expect(text).toContain('Hint:');
});
it('returns error with hint on timeout', async () => {
const restClient = createMockRestClient({
query: vi.fn().mockRejectedValue(new Error('Request timeout')),
});
const result = await callHandler(restClient);
expect(result.isError).toBe(true);
const text = (result.content[0] as { text: string }).text;
expect(text).toContain('timeout');
});
it('returns error with hint on connection failure', async () => {
const restClient = createMockRestClient({
query: vi.fn().mockRejectedValue(new Error('ECONNREFUSED')),
});
const result = await callHandler(restClient);
expect(result.isError).toBe(true);
const text = (result.content[0] as { text: string }).text;
expect(text).toContain('ECONNREFUSED');
expect(text).toContain('Hint:');
});
});
});

View File

@@ -0,0 +1,160 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerReadTool } from '../sage-read.js';
import type { RestClient } from '../../clients/rest-client.js';
import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
function createMockRestClient(overrides: Partial<RestClient> = {}): RestClient {
return {
query: vi.fn(),
read: vi.fn().mockResolvedValue({ record: {} }),
listEntities: vi.fn(),
healthCheck: vi.fn(),
...overrides,
} as unknown as RestClient;
}
describe('registerReadTool', () => {
let server: McpServer;
let registerToolSpy: ReturnType<typeof vi.spyOn>;
beforeEach(() => {
server = new McpServer({ name: 'test-server', version: '1.0.0' });
registerToolSpy = vi.spyOn(server, 'registerTool');
});
it('registers sage_read tool with correct metadata', () => {
const restClient = createMockRestClient();
registerReadTool(server, restClient);
expect(registerToolSpy).toHaveBeenCalledOnce();
const [name, config] = registerToolSpy.mock.calls[0];
expect(name).toBe('sage_read');
expect(config).toMatchObject({
description: expect.stringContaining('Read a single Sage X3 record'),
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: true,
},
});
});
it('has inputSchema with entity, key, and representation fields', () => {
const restClient = createMockRestClient();
registerReadTool(server, restClient);
const config = registerToolSpy.mock.calls[0][1] as Record<string, unknown>;
const schema = config.inputSchema as Record<string, unknown>;
expect(schema).toHaveProperty('entity');
expect(schema).toHaveProperty('key');
expect(schema).toHaveProperty('representation');
});
describe('handler', () => {
async function callHandler(
restClient: RestClient,
args: Record<string, unknown> = { entity: 'BPCUSTOMER', key: 'C001' },
): Promise<CallToolResult> {
registerReadTool(server, restClient);
const handler = registerToolSpy.mock.calls[0][2] as (
args: Record<string, unknown>,
) => Promise<CallToolResult>;
return handler(args);
}
it('returns full record on success', async () => {
const mockRecord = {
BPCNUM: 'C001',
BPCNAM: 'Acme Corp',
BPCADD: '123 Main St',
CRY: 'US',
};
const restClient = createMockRestClient({
read: vi.fn().mockResolvedValue({ record: mockRecord }),
});
const result = await callHandler(restClient);
expect(result.isError).toBeUndefined();
expect(result.content).toHaveLength(1);
const parsed = JSON.parse((result.content[0] as { text: string }).text);
expect(parsed.record).toEqual(mockRecord);
});
it('passes entity, key, and representation to restClient.read', async () => {
const readMock = vi.fn().mockResolvedValue({ record: {} });
const restClient = createMockRestClient({ read: readMock });
await callHandler(restClient, {
entity: 'SINVOICE',
key: 'INV001',
representation: 'SINV$details',
});
expect(readMock).toHaveBeenCalledWith('SINVOICE', 'INV001', 'SINV$details');
});
it('passes undefined representation when not provided', async () => {
const readMock = vi.fn().mockResolvedValue({ record: {} });
const restClient = createMockRestClient({ read: readMock });
await callHandler(restClient, { entity: 'BPCUSTOMER', key: 'C001' });
expect(readMock).toHaveBeenCalledWith('BPCUSTOMER', 'C001', undefined);
});
it('returns error with not_found hint on 404', async () => {
const restClient = createMockRestClient({
read: vi.fn().mockRejectedValue(new Error('HTTP 404: Not Found')),
});
const result = await callHandler(restClient);
expect(result.isError).toBe(true);
const text = (result.content[0] as { text: string }).text;
expect(text).toContain('404');
expect(text).toContain('Hint:');
expect(text).toContain('not found');
});
it('returns error with auth hint on 401', async () => {
const restClient = createMockRestClient({
read: vi.fn().mockRejectedValue(new Error('HTTP 401: Unauthorized')),
});
const result = await callHandler(restClient);
expect(result.isError).toBe(true);
const text = (result.content[0] as { text: string }).text;
expect(text).toContain('401');
expect(text).toContain('Hint:');
});
it('handles key with special characters', async () => {
const readMock = vi.fn().mockResolvedValue({ record: { NUM: 'INV/2024/001' } });
const restClient = createMockRestClient({ read: readMock });
const result = await callHandler(restClient, {
entity: 'SINVOICE',
key: 'INV/2024/001',
});
expect(readMock).toHaveBeenCalledWith('SINVOICE', 'INV/2024/001', undefined);
expect(result.isError).toBeUndefined();
});
it('returns minified JSON response', async () => {
const restClient = createMockRestClient({
read: vi.fn().mockResolvedValue({ record: { A: 1 } }),
});
const result = await callHandler(restClient);
const text = (result.content[0] as { text: string }).text;
expect(text).not.toContain('\n');
expect(text).toBe('{"record":{"A":1}}');
});
});
});

View File

@@ -0,0 +1,211 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerSearchTool, buildWhereClause } from '../sage-search.js';
import type { RestClient } from '../../clients/rest-client.js';
import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
function createMockRestClient(overrides: Partial<RestClient> = {}): RestClient {
return {
query: vi.fn().mockResolvedValue({
records: [],
pagination: { returned: 0, hasMore: false },
}),
read: vi.fn(),
listEntities: vi.fn(),
healthCheck: vi.fn(),
...overrides,
} as unknown as RestClient;
}
describe('buildWhereClause', () => {
it('builds clause with default fields based on entity name', () => {
const result = buildWhereClause('BPCUSTOMER', 'acme');
expect(result).toBe("(contains(BPCUSTOMERNUM,'acme') or contains(BPCUSTOMERNAM,'acme'))");
});
it('builds clause with custom searchFields', () => {
const result = buildWhereClause('BPCUSTOMER', 'acme', ['BPCNAM', 'BPCNUM']);
expect(result).toBe("(contains(BPCNAM,'acme') or contains(BPCNUM,'acme'))");
});
it('builds clause with single custom field (no parens wrapping)', () => {
const result = buildWhereClause('BPCUSTOMER', 'acme', ['BPCNAM']);
expect(result).toBe("contains(BPCNAM,'acme')");
});
it('uses default fields when searchFields is empty array', () => {
const result = buildWhereClause('SINVOICE', 'INV001', []);
expect(result).toBe("(contains(SINVOICENUM,'INV001') or contains(SINVOICENAM,'INV001'))");
});
it('handles search term with spaces', () => {
const result = buildWhereClause('BPCUSTOMER', 'Acme Corp', ['BPCNAM']);
expect(result).toBe("contains(BPCNAM,'Acme Corp')");
});
it('builds clause with three fields', () => {
const result = buildWhereClause('ITMMASTER', 'widget', ['ITMREF', 'ITMDES', 'ITMDES2']);
expect(result).toBe(
"(contains(ITMREF,'widget') or contains(ITMDES,'widget') or contains(ITMDES2,'widget'))",
);
});
});
describe('registerSearchTool', () => {
let server: McpServer;
let registerToolSpy: ReturnType<typeof vi.spyOn>;
beforeEach(() => {
server = new McpServer({ name: 'test-server', version: '1.0.0' });
registerToolSpy = vi.spyOn(server, 'registerTool');
});
it('registers sage_search tool with correct metadata', () => {
const restClient = createMockRestClient();
registerSearchTool(server, restClient);
expect(registerToolSpy).toHaveBeenCalledOnce();
const [name, config] = registerToolSpy.mock.calls[0];
expect(name).toBe('sage_search');
expect(config).toMatchObject({
description: expect.stringContaining('Search Sage X3'),
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: true,
},
});
});
it('has inputSchema with expected fields', () => {
const restClient = createMockRestClient();
registerSearchTool(server, restClient);
const config = registerToolSpy.mock.calls[0][1] as Record<string, unknown>;
const schema = config.inputSchema as Record<string, unknown>;
expect(schema).toHaveProperty('entity');
expect(schema).toHaveProperty('searchTerm');
expect(schema).toHaveProperty('searchFields');
expect(schema).toHaveProperty('count');
});
describe('handler', () => {
async function callHandler(
restClient: RestClient,
args: Record<string, unknown> = { entity: 'BPCUSTOMER', searchTerm: 'acme' },
): Promise<CallToolResult> {
registerSearchTool(server, restClient);
const handler = registerToolSpy.mock.calls[0][2] as (
args: Record<string, unknown>,
) => Promise<CallToolResult>;
return handler(args);
}
it('calls restClient.query with built where clause using default fields', async () => {
const queryMock = vi.fn().mockResolvedValue({
records: [],
pagination: { returned: 0, hasMore: false },
});
const restClient = createMockRestClient({ query: queryMock });
await callHandler(restClient, { entity: 'BPCUSTOMER', searchTerm: 'acme' });
expect(queryMock).toHaveBeenCalledWith({
entity: 'BPCUSTOMER',
where: "(contains(BPCUSTOMERNUM,'acme') or contains(BPCUSTOMERNAM,'acme'))",
count: undefined,
});
});
it('calls restClient.query with custom searchFields', async () => {
const queryMock = vi.fn().mockResolvedValue({
records: [],
pagination: { returned: 0, hasMore: false },
});
const restClient = createMockRestClient({ query: queryMock });
await callHandler(restClient, {
entity: 'BPCUSTOMER',
searchTerm: 'acme',
searchFields: ['BPCNAM', 'BPCNUM'],
});
expect(queryMock).toHaveBeenCalledWith({
entity: 'BPCUSTOMER',
where: "(contains(BPCNAM,'acme') or contains(BPCNUM,'acme'))",
count: undefined,
});
});
it('passes count to restClient.query', async () => {
const queryMock = vi.fn().mockResolvedValue({
records: [],
pagination: { returned: 0, hasMore: false },
});
const restClient = createMockRestClient({ query: queryMock });
await callHandler(restClient, {
entity: 'BPCUSTOMER',
searchTerm: 'acme',
count: 50,
});
expect(queryMock).toHaveBeenCalledWith(
expect.objectContaining({ count: 50 }),
);
});
it('returns matching records on success', async () => {
const mockRecords = [{ BPCNUM: 'C001', BPCNAM: 'Acme Corp' }];
const restClient = createMockRestClient({
query: vi.fn().mockResolvedValue({
records: mockRecords,
pagination: { returned: 1, hasMore: false },
}),
});
const result = await callHandler(restClient);
expect(result.isError).toBeUndefined();
const parsed = JSON.parse((result.content[0] as { text: string }).text);
expect(parsed.records).toEqual(mockRecords);
expect(parsed.pagination.returned).toBe(1);
});
it('returns empty results when no matches found', async () => {
const restClient = createMockRestClient();
const result = await callHandler(restClient);
const parsed = JSON.parse((result.content[0] as { text: string }).text);
expect(parsed.records).toEqual([]);
expect(parsed.pagination.returned).toBe(0);
});
it('returns error with hint on failure', async () => {
const restClient = createMockRestClient({
query: vi.fn().mockRejectedValue(new Error('HTTP 401: Unauthorized')),
});
const result = await callHandler(restClient);
expect(result.isError).toBe(true);
const text = (result.content[0] as { text: string }).text;
expect(text).toContain('401');
expect(text).toContain('Hint:');
});
it('returns error with hint on connection failure', async () => {
const restClient = createMockRestClient({
query: vi.fn().mockRejectedValue(new Error('ECONNREFUSED')),
});
const result = await callHandler(restClient);
expect(result.isError).toBe(true);
const text = (result.content[0] as { text: string }).text;
expect(text).toContain('ECONNREFUSED');
});
});
});