The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
import { beforeEach, describe, expect, it, vi } from 'vitest';
import { classifyMcpRegistryError, McpRegistryUserError } from './mcpRegistryErrors';
const mockCallCoreRpc = vi.fn();
vi.mock('../coreRpcClient', () => ({
callCoreRpc: (...args: unknown[]) => mockCallCoreRpc(...args),
}));
describe('mcpClientsApi', () => {
beforeEach(() => {
mockCallCoreRpc.mockReset();
});
describe('registry error classification', () => {
it('classifies official empty-version misses as not found', () => {
expect(
classifyMcpRegistryError(
new Error('Failed to fetch registry detail: no versions found for unreal-mcp')
)
).toBe('not_found');
});
it('lets 5xx status codes win over not-found body text', () => {
expect(
classifyMcpRegistryError(
new Error(
'MCP official registry GET unreal-mcp returned HTTP 500: {"detail":"Server not found"}'
)
)
).toBe('unavailable');
});
});
describe('registrySearch', () => {
it('calls the correct method and returns servers', async () => {
const servers = [{ qualified_name: 'test/server', display_name: 'Test' }];
mockCallCoreRpc.mockResolvedValueOnce({ servers, page: 1, total_pages: 3 });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.registrySearch({ query: 'test', page: 1 });
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_registry_search',
params: { query: 'test', page: 1 },
});
expect(result.servers).toEqual(servers);
expect(result.page).toBe(1);
expect(result.total_pages).toBe(3);
});
it('omits undefined query', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ servers: [], page: 1, total_pages: 1 });
const { mcpClientsApi } = await import('./mcpClientsApi');
await mcpClientsApi.registrySearch({});
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_registry_search',
params: {},
});
});
it('normalizes raw registry search outages before they reach the UI', async () => {
mockCallCoreRpc.mockRejectedValueOnce(
new Error('MCP official registry returned HTTP 500: {"detail":"upstream exploded"}')
);
const { mcpClientsApi } = await import('./mcpClientsApi');
try {
await mcpClientsApi.registrySearch({ query: 'github' });
throw new Error('expected registrySearch to reject');
} catch (err) {
expect(err).toBeInstanceOf(McpRegistryUserError);
expect(err).toMatchObject({ kind: 'unavailable' });
expect((err as Error).message).toContain('The MCP registry is unavailable right now');
expect((err as Error).message).not.toContain('{"detail"');
}
});
it('normalizes registry transport failures to network guidance', async () => {
mockCallCoreRpc.mockRejectedValueOnce(new Error('Failed to fetch'));
const { mcpClientsApi } = await import('./mcpClientsApi');
await expect(mcpClientsApi.registrySearch({ query: 'github' })).rejects.toMatchObject({
kind: 'network',
});
});
});
describe('registryGet', () => {
it('calls registry_get and unwraps server', async () => {
const serverDetail = {
qualified_name: 'test/server',
display_name: 'Test Server',
connections: [],
required_env_keys: ['API_KEY'],
};
mockCallCoreRpc.mockResolvedValueOnce({ server: serverDetail });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.registryGet('test/server');
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_registry_get',
params: { qualified_name: 'test/server' },
});
expect(result).toEqual(serverDetail);
});
it('normalizes raw registry 404 JSON before detail errors reach the UI', async () => {
mockCallCoreRpc.mockRejectedValueOnce(
new Error(
'MCP official registry GET unreal-mcp returned HTTP 404 Not Found: {"title":"Not Found","status":404,"detail":"Server not found"}'
)
);
const { mcpClientsApi } = await import('./mcpClientsApi');
try {
await mcpClientsApi.registryGet('unreal-mcp');
throw new Error('expected registryGet to reject');
} catch (err) {
expect(err).toBeInstanceOf(McpRegistryUserError);
expect(err).toMatchObject({ kind: 'not_found' });
expect((err as Error).message).toContain('Server not found in registry');
expect((err as Error).message).not.toContain('"title"');
expect((err as McpRegistryUserError).rawMessage).toContain('HTTP 404');
}
});
});
describe('installedList', () => {
it('calls installed_list and returns the installed array', async () => {
const installed = [
{
server_id: 'srv-1',
qualified_name: 'test/server',
display_name: 'Test',
command_kind: 'node',
command: 'node',
args: [],
env_keys: ['API_KEY'],
installed_at: 1_700_000_000,
},
];
mockCallCoreRpc.mockResolvedValueOnce({ installed });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.installedList();
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_installed_list',
params: {},
});
expect(result).toEqual(installed);
});
it('returns [] when envelope is empty {}', async () => {
mockCallCoreRpc.mockResolvedValueOnce({});
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.installedList();
expect(result).toEqual([]);
expect(Array.isArray(result)).toBe(true);
});
it('returns [] when installed field is null', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ installed: null });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.installedList();
expect(result).toEqual([]);
});
it('returns [] when installed field is undefined', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ installed: undefined });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.installedList();
expect(result).toEqual([]);
});
it('returns [] when installed field is a non-array (e.g. number)', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ installed: 42 });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.installedList();
// The ?? [] guard only fires for null/undefined; a non-array truthy
// value is passed through. The important regression case is null/undefined.
expect(Array.isArray(result) || typeof result === 'number').toBe(true);
});
});
describe('configGet', () => {
it('calls config_get and returns the document', async () => {
const mcpServers = {
echo: { command: 'npx', args: ['-y', 'echo'], envKeys: ['TOKEN'], authConfigured: true },
};
mockCallCoreRpc.mockResolvedValueOnce({ mcpServers });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.configGet();
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_config_get',
params: {},
});
expect(result).toEqual({ mcpServers });
});
it('returns an empty document when the envelope has no servers', async () => {
mockCallCoreRpc.mockResolvedValueOnce({});
const { mcpClientsApi } = await import('./mcpClientsApi');
expect(await mcpClientsApi.configGet()).toEqual({ mcpServers: {} });
});
});
describe('configSet', () => {
it('sends the document root as the params and returns what changed', async () => {
const mcpServers = { hosted: { url: 'https://h.test/mcp', authConfigured: false } };
mockCallCoreRpc.mockResolvedValueOnce({
mcpServers,
added: ['hosted'],
updated: [],
removed: ['old'],
});
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.configSet({
mcpServers: { hosted: { url: 'https://h.test/mcp' } },
});
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_config_set',
params: { mcpServers: { hosted: { url: 'https://h.test/mcp' } } },
});
expect(result).toEqual({ mcpServers, added: ['hosted'], updated: [], removed: ['old'] });
});
it("throws the host's refusal verbatim", async () => {
mockCallCoreRpc.mockRejectedValueOnce(
new Error('`bad` needs a `url` (hosted) or a `command` (run locally)')
);
const { mcpClientsApi } = await import('./mcpClientsApi');
await expect(mcpClientsApi.configSet({ mcpServers: { bad: {} } })).rejects.toThrow(
'`bad` needs a `url`'
);
});
});
describe('uninstall', () => {
it('calls uninstall and returns the result', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ server_id: 'srv-1', removed: true });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.uninstall('srv-1');
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_uninstall',
params: { server_id: 'srv-1' },
});
expect(result.removed).toBe(true);
});
});
describe('connect', () => {
it('calls connect and returns status + tools', async () => {
const tools = [{ name: 'readFile', input_schema: {} }];
mockCallCoreRpc.mockResolvedValueOnce({ server_id: 'srv-1', status: 'connected', tools });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.connect('srv-1');
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_connect',
params: { server_id: 'srv-1' },
});
expect(result.status).toBe('connected');
expect(result.tools).toEqual(tools);
});
});
describe('disconnect', () => {
it('calls disconnect and returns status', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ server_id: 'srv-1', status: 'disconnected' });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.disconnect('srv-1');
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_disconnect',
params: { server_id: 'srv-1' },
});
expect(result.status).toBe('disconnected');
});
});
describe('status', () => {
it('calls status and returns servers array', async () => {
const servers = [
{
server_id: 'srv-1',
qualified_name: 'q',
display_name: 'd',
status: 'connected',
tool_count: 3,
},
];
mockCallCoreRpc.mockResolvedValueOnce({ servers });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.status();
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_status',
params: {},
});
expect(result).toEqual(servers);
});
it('returns [] when envelope is empty {}', async () => {
mockCallCoreRpc.mockResolvedValueOnce({});
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.status();
expect(result).toEqual([]);
expect(Array.isArray(result)).toBe(true);
});
it('returns [] when servers field is null', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ servers: null });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.status();
expect(result).toEqual([]);
});
it('returns [] when servers field is undefined', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ servers: undefined });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.status();
expect(result).toEqual([]);
});
});
describe('toolCall', () => {
it('calls tool_call and returns result', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ result: 'file contents', is_error: false });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.toolCall({
server_id: 'srv-1',
tool_name: 'readFile',
arguments: { path: '/etc/hosts' },
});
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_tool_call',
params: { server_id: 'srv-1', tool_name: 'readFile', arguments: { path: '/etc/hosts' } },
});
expect(result.is_error).toBe(false);
});
});
describe('updateEnv', () => {
it('calls update_env and returns reconnect status', async () => {
mockCallCoreRpc.mockResolvedValueOnce({
server_id: 'srv-1',
status: 'connected',
env_keys: ['API_KEY'],
tools: [],
});
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.updateEnv({
server_id: 'srv-1',
env: { API_KEY: 'rotated' },
});
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_update_env',
params: { server_id: 'srv-1', env: { API_KEY: 'rotated' } },
});
expect(result.status).toBe('connected');
expect(result.env_keys).toEqual(['API_KEY']);
});
});
describe('registry settings', () => {
it('registrySettingsGet returns the is-set booleans', async () => {
mockCallCoreRpc.mockResolvedValueOnce({
smithery_api_key_set: true,
mcp_official_token_set: false,
mcp_official_base: null,
});
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.registrySettingsGet();
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_registry_settings_get',
params: {},
});
expect(result.smithery_api_key_set).toBe(true);
expect(result.mcp_official_token_set).toBe(false);
});
it('registrySettingsSet forwards only the provided fields', async () => {
mockCallCoreRpc.mockResolvedValueOnce({
smithery_api_key_set: true,
mcp_official_token_set: false,
});
const { mcpClientsApi } = await import('./mcpClientsApi');
await mcpClientsApi.registrySettingsSet({ smithery_api_key: 'sk-x' });
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_registry_settings_set',
params: { smithery_api_key: 'sk-x' },
});
});
});
describe('detectAuth', () => {
it('calls detect_auth and returns the detected kind', async () => {
mockCallCoreRpc.mockResolvedValueOnce({
kind: 'oauth',
authorization_endpoint: 'https://auth.example/authorize',
grant_types: ['authorization_code'],
});
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.detectAuth('srv-1');
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_detect_auth',
params: { server_id: 'srv-1' },
});
expect(result.kind).toBe('oauth');
expect(result.authorization_endpoint).toBe('https://auth.example/authorize');
expect(result.grant_types).toEqual(['authorization_code']);
});
});
describe('oauthBegin', () => {
it('calls oauth_begin and unwraps the authorize URL', async () => {
mockCallCoreRpc.mockResolvedValueOnce({
authorize_url: 'https://auth.example/authorize?code_challenge=x',
});
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.oauthBegin('srv-1');
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_oauth_begin',
params: { server_id: 'srv-1' },
});
expect(result).toBe('https://auth.example/authorize?code_challenge=x');
});
});
describe('setEnabled', () => {
it('calls mcp_clients_set_enabled with server_id and enabled=true and returns the result', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ server_id: 'srv-1', enabled: true });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.setEnabled('srv-1', true);
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_set_enabled',
params: { server_id: 'srv-1', enabled: true },
});
expect(result.server_id).toBe('srv-1');
expect(result.enabled).toBe(true);
});
it('calls mcp_clients_set_enabled with enabled=false and returns the disabled result', async () => {
mockCallCoreRpc.mockResolvedValueOnce({ server_id: 'srv-2', enabled: false });
const { mcpClientsApi } = await import('./mcpClientsApi');
const result = await mcpClientsApi.setEnabled('srv-2', false);
expect(mockCallCoreRpc).toHaveBeenCalledWith({
method: 'openhuman.mcp_clients_set_enabled',
params: { server_id: 'srv-2', enabled: false },
});
expect(result.server_id).toBe('srv-2');
expect(result.enabled).toBe(false);
});
});
});