@theia/ai-registry 1.73.0-next.10

package/src/common/mcp/mcp-registry-entry-resolver.spec.ts

@@ -0,0 +1,248 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { AIRegistryConfiguration } from '../ai-registry-configuration';
+import { MCPRegistryEntryResolver, MCPRegistryEntryResolverImpl } from './mcp-registry-entry-resolver';
+import { RegistryMCPServer } from './mcp-registry-types';
+
+function createResolver(toolName: string = 'theia-ide'): MCPRegistryEntryResolver {
+    const resolver = new MCPRegistryEntryResolverImpl();
+    const configuration: AIRegistryConfiguration = Object.assign(new AIRegistryConfiguration(), {
+        getToolName(): string {
+            return toolName;
+        }
+    });
+    Object.assign(resolver, { configuration });
+    return resolver;
+}
+
+describe('MCPRegistryEntryResolver.resolve', () => {
+
+    let resolver: MCPRegistryEntryResolver;
+
+    beforeEach(() => {
+        resolver = createResolver();
+    });
+
+    it('normalises a server with a single approval, install config and inner server, propagating configHash', () => {
+        const raw: RegistryMCPServer = {
+            serverId: 'io.github.example/example-mcp',
+            name: 'Example',
+            description: 'Example MCP server',
+            mcpRegistryVerified: true,
+            approvals: [{
+                organizationId: 'theia',
+                date: '2026-04-01',
+                version: '^1.0.0',
+                configHash: 'hash-v1',
+                installConfigs: [{
+                    tool: 'theia-ide',
+                    config: { servers: { example: { command: 'npx', args: ['-y', 'example-mcp'] } } }
+                }]
+            }]
+        };
+
+        expect(resolver.resolve(raw)).to.deep.equal({
+            serverId: 'io.github.example/example-mcp',
+            name: 'Example',
+            description: 'Example MCP server',
+            localName: 'example',
+            config: { command: 'npx', args: ['-y', 'example-mcp'] },
+            version: '^1.0.0',
+            configHash: 'hash-v1',
+            mcpRegistryVerified: true
+        });
+    });
+
+    it('omits configHash when the approval has none - supports payloads pre-dating the field', () => {
+        const raw: RegistryMCPServer = {
+            serverId: 'io.github.example/legacy-mcp',
+            name: 'Legacy',
+            description: 'Legacy MCP server with no configHash',
+            mcpRegistryVerified: true,
+            approvals: [{
+                organizationId: 'theia',
+                date: '2026-04-01',
+                version: '^1.0.0',
+                installConfigs: [{
+                    tool: 'theia-ide',
+                    config: { servers: { legacy: { command: 'npx', args: ['-y', 'legacy-mcp'] } } }
+                }]
+            }]
+        };
+
+        const resolved = resolver.resolve(raw);
+        expect(resolved).to.not.have.property('configHash');
+        expect(resolved?.version).to.equal('^1.0.0');
+    });
+
+    it('picks the most recent approval when multiple organisations approved the same server', () => {
+        const raw: RegistryMCPServer = {
+            serverId: 'io.github.example/example-mcp',
+            name: 'Example',
+            description: 'Example MCP server',
+            mcpRegistryVerified: true,
+            approvals: [
+                {
+                    organizationId: 'older-org',
+                    date: '2025-01-01',
+                    version: '^0.5.0',
+                    installConfigs: [{
+                        tool: 'theia-ide',
+                        config: { servers: { example: { command: 'old-cmd' } } }
+                    }]
+                },
+                {
+                    organizationId: 'newer-org',
+                    date: '2026-04-01',
+                    version: '^1.0.0',
+                    installConfigs: [{
+                        tool: 'theia-ide',
+                        config: { servers: { example: { command: 'new-cmd' } } }
+                    }]
+                }
+            ]
+        };
+
+        const resolved = resolver.resolve(raw);
+        expect(resolved?.version).to.equal('^1.0.0');
+        expect(resolved?.config).to.deep.equal({ command: 'new-cmd' });
+    });
+
+    it('returns undefined when the server has no approvals', () => {
+        const raw: RegistryMCPServer = {
+            serverId: 'io.github.example/orphan',
+            name: 'Orphan',
+            description: 'No approvals',
+            mcpRegistryVerified: false,
+            approvals: []
+        };
+        expect(resolver.resolve(raw)).to.be.undefined;
+    });
+
+    it('returns undefined when the picked approval has no usable install config', () => {
+        const raw: RegistryMCPServer = {
+            serverId: 'io.github.example/empty',
+            name: 'Empty',
+            description: 'Approval with no usable config',
+            mcpRegistryVerified: false,
+            approvals: [{
+                organizationId: 'theia',
+                date: '2026-04-01',
+                version: '^1.0.0',
+                installConfigs: [{ tool: 'theia-ide' }]
+            }]
+        };
+        expect(resolver.resolve(raw)).to.be.undefined;
+    });
+
+    it('picks the install config matching the configured tool name when multiple are present', () => {
+        const productResolver = createResolver('my-product');
+        const raw: RegistryMCPServer = {
+            serverId: 'io.github.example/multi-tool',
+            name: 'Multi Tool',
+            description: 'Approval carrying configs for several tools',
+            mcpRegistryVerified: true,
+            approvals: [{
+                organizationId: 'theia',
+                date: '2026-04-01',
+                version: '^1.0.0',
+                installConfigs: [
+                    { tool: 'theia-ide', config: { servers: { example: { command: 'theia-cmd' } } } },
+                    { tool: 'my-product', config: { servers: { example: { command: 'product-cmd' } } } }
+                ]
+            }]
+        };
+
+        expect(productResolver.resolve(raw)?.config).to.deep.equal({ command: 'product-cmd' });
+    });
+
+    it('accepts an untagged install config as a fallback when no tool-specific config matches', () => {
+        const productResolver = createResolver('my-product');
+        const raw: RegistryMCPServer = {
+            serverId: 'io.github.example/untagged',
+            name: 'Untagged',
+            description: 'Approval whose install config has no tool tag',
+            mcpRegistryVerified: true,
+            approvals: [{
+                organizationId: 'theia',
+                date: '2026-04-01',
+                version: '^1.0.0',
+                installConfigs: [
+                    { config: { servers: { example: { command: 'untagged-cmd' } } } }
+                ]
+            }]
+        };
+
+        expect(productResolver.resolve(raw)?.config).to.deep.equal({ command: 'untagged-cmd' });
+    });
+
+    it("accepts every install config when the configured tool name is 'all'", () => {
+        const allResolver = createResolver('all');
+        const raw: RegistryMCPServer = {
+            serverId: 'io.github.example/all',
+            name: 'Any tool',
+            description: 'Approval whose install config is tagged for a different tool',
+            mcpRegistryVerified: true,
+            approvals: [{
+                organizationId: 'theia',
+                date: '2026-04-01',
+                version: '^1.0.0',
+                installConfigs: [
+                    { tool: 'other-tool', config: { servers: { example: { command: 'other-cmd' } } } }
+                ]
+            }]
+        };
+
+        expect(allResolver.resolve(raw)?.config).to.deep.equal({ command: 'other-cmd' });
+    });
+
+    it('warns and picks the first key deterministically when the install config exposes multiple servers', () => {
+        const raw: RegistryMCPServer = {
+            serverId: 'io.github.example/multi-server',
+            name: 'Multi Server',
+            description: 'Approval whose install config exposes multiple servers',
+            mcpRegistryVerified: true,
+            approvals: [{
+                organizationId: 'theia',
+                date: '2026-04-01',
+                version: '^1.0.0',
+                installConfigs: [{
+                    tool: 'theia-ide',
+                    config: {
+                        servers: {
+                            primary: { command: 'first-cmd' },
+                            secondary: { command: 'second-cmd' }
+                        }
+                    }
+                }]
+            }]
+        };
+
+        const warnings: string[] = [];
+        const originalWarn = console.warn;
+        console.warn = (...args: unknown[]) => { warnings.push(args.map(String).join(' ')); };
+        try {
+            const resolved = resolver.resolve(raw);
+            expect(resolved?.localName).to.equal('primary');
+            expect(resolved?.config).to.deep.equal({ command: 'first-cmd' });
+            expect(warnings.some(w => w.includes('multiple servers'))).to.equal(true);
+        } finally {
+            console.warn = originalWarn;
+        }
+    });
+});

package/src/common/mcp/mcp-registry-entry-resolver.ts

@@ -0,0 +1,68 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { inject, injectable } from '@theia/core/shared/inversify';
+import { AIRegistryConfiguration } from '../ai-registry-configuration';
+import { RegistryMCPServer, ResolvedRegistryEntry } from './mcp-registry-types';
+
+export const MCPRegistryEntryResolver = Symbol('MCPRegistryEntryResolver');
+export interface MCPRegistryEntryResolver {
+    /** Normalises a raw registry server entry into the single (slug, config, version) tuple the install path uses. */
+    resolve(raw: RegistryMCPServer): ResolvedRegistryEntry | undefined;
+}
+
+@injectable()
+export class MCPRegistryEntryResolverImpl implements MCPRegistryEntryResolver {
+
+    @inject(AIRegistryConfiguration)
+    protected readonly configuration: AIRegistryConfiguration;
+
+    resolve(raw: RegistryMCPServer): ResolvedRegistryEntry | undefined {
+        const approval = [...raw.approvals].sort((a, b) => b.date.localeCompare(a.date))[0];
+        if (!approval) {
+            return undefined;
+        }
+        // Per-tool endpoints should already pre-filter install configs, but a registry
+        // may still emit several. Pick the one tagged for our configured tool name
+        // (or untagged, which we treat as "applies to all tools"); fall back to the
+        // first config so a registry that hasn't tagged its entries still works.
+        const toolName = this.configuration.getToolName();
+        const installConfig = approval.installConfigs.find(c => !c.tool || c.tool === toolName || toolName === 'all')
+            ?? approval.installConfigs[0];
+        const servers = installConfig?.config?.servers ?? {};
+        const serverKeys = Object.keys(servers);
+        if (serverKeys.length === 0) {
+            return undefined;
+        }
+        if (serverKeys.length > 1) {
+            // Multi-server install configs aren't a Theia concept - we install one server
+            // per registry entry. Warn so the registry maintainer is aware their payload
+            // exposed more than we use, and pick the first slug deterministically.
+            console.warn(`AI registry entry ${raw.serverId} has multiple servers in its install config; using ${serverKeys[0]}.`);
+        }
+        const localName = serverKeys[0];
+        return {
+            serverId: raw.serverId,
+            name: raw.name,
+            description: raw.description,
+            localName,
+            config: servers[localName],
+            version: approval.version,
+            ...(approval.configHash !== undefined && { configHash: approval.configHash }),
+            mcpRegistryVerified: raw.mcpRegistryVerified
+        };
+    }
+}

package/src/common/mcp/mcp-registry-types.ts

@@ -0,0 +1,119 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { MCPInstallEntryConfig } from '@theia/ai-mcp/lib/common/mcp-server-manager';
+
+/**
+ * Shape of `installConfigs[].config` for Theia: a `servers` map keyed by the local
+ * MCP server key chosen by the registry maintainer. Server entries use the canonical
+ * {@link MCPInstallEntryConfig} type from `@theia/ai-mcp` so the registry and the
+ * install path can never drift in shape.
+ */
+export interface RegistryMCPInstallConfigBlob {
+    servers: Record<string, MCPInstallEntryConfig>;
+}
+
+/**
+ * A single install config inside an approval. Already filtered per-tool by the registry
+ * for the per-tool view (`<baseUrl>/<toolName>.json`).
+ */
+export interface RegistryInstallConfig {
+    tool?: string;
+    installUrl?: string;
+    openVsxUrl?: string;
+    config?: RegistryMCPInstallConfigBlob;
+    instructions?: string;
+}
+
+/**
+ * One organization's approval of an MCP server entry, with the install configs for the
+ * tools that organization approved.
+ */
+export interface RegistryApproval {
+    organizationId: string;
+    date: string;
+    /** Pinned server version (per the AI-registry approval schema). Omitted means "use the latest from the Anthropic MCP registry". */
+    version?: string;
+    /**
+     * Content hash of the approval produced by the registry's consolidation pipeline.
+     * Drives update detection on the client - when the hash differs from the locally
+     * stored `registryMetadata.configHash`, the registry has published a new approval
+     * and Theia offers an Update action. Optional for backwards compatibility with
+     * older payloads that pre-date the field.
+     */
+    configHash?: string;
+    installConfigs: RegistryInstallConfig[];
+}
+
+/**
+ * Top-level MCP server entry as returned by the registry's per-tool JSON endpoint.
+ */
+export interface RegistryMCPServer {
+    serverId: string;
+    name: string;
+    description: string;
+    mcpRegistryVerified: boolean;
+    approvals: RegistryApproval[];
+}
+
+/**
+ * A registry MCP entry after resolving the (potentially multiple) approvals and install configs
+ * down to the single (key, config, version) tuple the install service operates on.
+ *
+ * Resolution lives in the fetch layer; the install service expects this normalised shape.
+ */
+export interface ResolvedRegistryEntry {
+    serverId: string;
+    name: string;
+    description: string;
+    /** The local preference key the registry maintainer chose (inner config.servers key). */
+    localName: string;
+    /** The config blob to write into `ai-features.mcp.mcpServers[localName]`. */
+    config: MCPInstallEntryConfig;
+    /** Registry-published version. Stored alongside installed entries for display only - update detection uses {@link configHash}. */
+    version?: string;
+    /**
+     * Content hash of the chosen approval - compared against the local
+     * `registryMetadata.configHash` to decide whether an Update is available. Optional
+     * for backwards compatibility with older registry payloads - when absent the client
+     * does not offer Update, since "no hash" is not evidence of a new version.
+     */
+    configHash?: string;
+    /** True if the entry is verified against the Anthropic MCP registry - drives the "verified only" search filter. */
+    mcpRegistryVerified: boolean;
+}
+
+/**
+ * Outcome of classifying an entry against the opposite side (registry -> local prefs
+ * for search/list views, or local prefs -> registry for the Installed view).
+ *
+ * Not every state is producible in both directions:
+ *
+ * - `not-installed` is only produced by `classifyRegistryEntry`.
+ * - `installed-user-added` is only produced by `classifyLocalServer`.
+ * - `installed-link-stale` is produced by both classifiers - `classifyLocalServer`
+ *   when a linked local points to an unknown id, and `classifyRegistryEntry` when the
+ *   key-matching local does so. The Installed and Search views show the same Unlink
+ *   and Uninstall affordances in either case.
+ * - `installed-from-registry`, `installed-manually`, and `fix-config` are common.
+ */
+export type ClassificationResult =
+    | { kind: 'installed-from-registry'; updateAvailable: boolean }
+    | { kind: 'installed-manually' }
+    | { kind: 'fix-config' }
+    | { kind: 'not-installed' }
+    | { kind: 'installed-link-stale' }
+    | { kind: 'installed-user-added' };

package/src/common/registry-fetch-service.spec.ts

@@ -0,0 +1,136 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { Container } from '@theia/core/shared/inversify';
+import { RequestContext, RequestOptions, RequestService } from '@theia/core/shared/@theia/request';
+import { AIRegistryConfiguration } from './ai-registry-configuration';
+import { MCPRegistryEntryResolver, MCPRegistryEntryResolverImpl } from './mcp/mcp-registry-entry-resolver';
+import { RegistryFetchService, RegistryFetchServiceImpl } from './registry-fetch-service';
+
+class FakeRequestService implements RequestService {
+    public lastUrl: string | undefined;
+    public callCount = 0;
+    constructor(private readonly responseBody: string, private readonly statusCode = 200) { }
+    async configure(): Promise<void> { /* no-op */ }
+    async resolveProxy(): Promise<string | undefined> { return undefined; }
+    async request(options: RequestOptions): Promise<RequestContext> {
+        this.lastUrl = options.url;
+        this.callCount += 1;
+        return {
+            url: options.url,
+            res: { headers: {}, statusCode: this.statusCode },
+            buffer: new TextEncoder().encode(this.responseBody)
+        };
+    }
+}
+
+class FakeConfiguration extends AIRegistryConfiguration {
+    constructor(private readonly toolName: string, private readonly baseUrl: string) { super(); }
+    override getToolName(): string { return this.toolName; }
+    override getBaseUrl(): string { return this.baseUrl; }
+}
+
+function payload(): string {
+    return JSON.stringify({
+        organizations: [],
+        tools: [],
+        mcp: [{
+            serverId: 'io.github.example/example-mcp',
+            name: 'Example',
+            description: 'Example MCP server',
+            mcpRegistryVerified: true,
+            approvals: [{
+                organizationId: 'theia',
+                date: '2026-04-01',
+                version: '^1.0.0',
+                configHash: 'hash-v1',
+                installConfigs: [{
+                    tool: 'theia-ide',
+                    config: { servers: { example: { command: 'npx', args: ['-y', 'example-mcp'] } } }
+                }]
+            }]
+        }]
+    });
+}
+
+describe('RegistryFetchService', () => {
+
+    function buildContainer(requestService: RequestService, config: AIRegistryConfiguration): Container {
+        const container = new Container();
+        container.bind(RequestService).toConstantValue(requestService);
+        container.bind(AIRegistryConfiguration).toConstantValue(config);
+        container.bind(MCPRegistryEntryResolverImpl).toSelf().inSingletonScope();
+        container.bind(MCPRegistryEntryResolver).toService(MCPRegistryEntryResolverImpl);
+        container.bind(RegistryFetchServiceImpl).toSelf().inSingletonScope();
+        container.bind(RegistryFetchService).toService(RegistryFetchServiceImpl);
+        return container;
+    }
+
+    it('fetches the per-tool JSON from <baseUrl>/<toolName>.json and returns resolved entries', async () => {
+        const request = new FakeRequestService(payload());
+        const config = new FakeConfiguration('theia-ide', 'https://example.test/api/v1/');
+        const service = buildContainer(request, config).get<RegistryFetchService>(RegistryFetchService);
+
+        const entries = await service.getEntries();
+
+        expect(request.lastUrl).to.equal('https://example.test/api/v1/theia-ide.json');
+        expect(entries).to.have.length(1);
+        expect(entries[0]).to.deep.equal({
+            serverId: 'io.github.example/example-mcp',
+            name: 'Example',
+            description: 'Example MCP server',
+            localName: 'example',
+            config: { command: 'npx', args: ['-y', 'example-mcp'] },
+            version: '^1.0.0',
+            configHash: 'hash-v1',
+            mcpRegistryVerified: true
+        });
+    });
+
+    it('serves cached entries on a second call without issuing a new request', async () => {
+        const request = new FakeRequestService(payload());
+        const service = buildContainer(request, new FakeConfiguration('theia-ide', 'https://example.test/api/v1/')).get<RegistryFetchService>(RegistryFetchService);
+
+        await service.getEntries();
+        await service.getEntries();
+
+        expect(request.callCount).to.equal(1);
+    });
+
+    it('refetches when forceRefresh is true', async () => {
+        const request = new FakeRequestService(payload());
+        const service = buildContainer(request, new FakeConfiguration('theia-ide', 'https://example.test/api/v1/')).get<RegistryFetchService>(RegistryFetchService);
+
+        await service.getEntries();
+        await service.getEntries(true);
+
+        expect(request.callCount).to.equal(2);
+    });
+
+    it('throws a descriptive error when the server returns a non-success status', async () => {
+        const request = new FakeRequestService('', 404);
+        const service = buildContainer(request, new FakeConfiguration('theia-ide', 'https://example.test/api/v1/')).get<RegistryFetchService>(RegistryFetchService);
+
+        let caught: Error | undefined;
+        try {
+            await service.getEntries();
+        } catch (error) {
+            caught = error as Error;
+        }
+        expect(caught?.message).to.match(/HTTP 404/);
+    });
+});

package/src/common/registry-fetch-service.ts

@@ -0,0 +1,78 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { Emitter, Event } from '@theia/core';
+import { inject, injectable } from '@theia/core/shared/inversify';
+import { RequestContext, RequestService } from '@theia/core/shared/@theia/request';
+import { AIRegistryConfiguration } from './ai-registry-configuration';
+import { MCPRegistryEntryResolver } from './mcp/mcp-registry-entry-resolver';
+import { RegistryMCPServer, ResolvedRegistryEntry } from './mcp/mcp-registry-types';
+
+interface RegistryResponse {
+    mcp?: RegistryMCPServer[];
+}
+
+export const RegistryFetchService = Symbol('RegistryFetchService');
+export interface RegistryFetchService {
+    /** Fires whenever the cached set of resolved entries changes (initial load, manual refresh). */
+    readonly onDidChange: Event<void>;
+    /** Returns the resolved registry entries, fetching (and caching) them on first use or when `forceRefresh` is set. */
+    getEntries(forceRefresh?: boolean): Promise<ResolvedRegistryEntry[]>;
+}
+
+@injectable()
+export class RegistryFetchServiceImpl implements RegistryFetchService {
+
+    @inject(RequestService)
+    protected readonly requestService: RequestService;
+
+    @inject(AIRegistryConfiguration)
+    protected readonly configuration: AIRegistryConfiguration;
+
+    @inject(MCPRegistryEntryResolver)
+    protected readonly resolver: MCPRegistryEntryResolver;
+
+    protected cached: ResolvedRegistryEntry[] | undefined;
+
+    protected readonly onDidChangeEmitter = new Emitter<void>();
+    /** Fires whenever the cached set of resolved entries changes (initial load, manual refresh). */
+    readonly onDidChange: Event<void> = this.onDidChangeEmitter.event;
+
+    async getEntries(forceRefresh: boolean = false): Promise<ResolvedRegistryEntry[]> {
+        if (this.cached && !forceRefresh) {
+            return this.cached;
+        }
+        const url = this.buildEndpointUrl();
+        const context = await this.requestService.request({ url });
+        if (!RequestContext.isSuccess(context)) {
+            throw new Error(`Failed to fetch AI registry from ${url}: HTTP ${context.res.statusCode ?? 'unknown'}`);
+        }
+        const data = RequestContext.asJson<RegistryResponse>(context);
+        const entries = (data.mcp ?? [])
+            .map(server => this.resolver.resolve(server))
+            .filter((entry): entry is ResolvedRegistryEntry => entry !== undefined);
+        this.cached = entries;
+        this.onDidChangeEmitter.fire();
+        return entries;
+    }
+
+    protected buildEndpointUrl(): string {
+        const base = this.configuration.getBaseUrl();
+        const tool = this.configuration.getToolName();
+        const separator = base.endsWith('/') ? '' : '/';
+        return `${base}${separator}${tool}.json`;
+    }
+}

package/src/package.spec.ts

@@ -0,0 +1,28 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+/* note: this bogus test file is required so that
+   we are able to run mocha unit tests on this
+   package, without having any actual unit tests in it.
+   This way a coverage report will be generated,
+   showing 0% coverage, instead of no report.
+   This file can be removed once we have real unit
+   tests in place. */
+
+describe('ai-registry package', () => {
+
+    it('support code coverage statistics', () => true);
+});