@aerostack/core 0.10.1 → 0.11.0

package/dist/__tests__/workspace-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/workspace-client.test.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const workspace_client_1 = require("../workspace-client");
+const mockFetch = vitest_1.vi.fn();
+global.fetch = mockFetch;
+vitest_1.vi.stubGlobal('crypto', { randomUUID: () => 'test-req-uuid' });
+function jsonResponse(body, status = 200, statusText = 'OK') {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText,
+        json: () => Promise.resolve(body),
+        headers: new Map(),
+    };
+}
+(0, vitest_1.describe)('WorkspaceClient', () => {
+    let client;
+    (0, vitest_1.beforeEach)(() => {
+        vitest_1.vi.clearAllMocks();
+        client = new workspace_client_1.WorkspaceClient({ slug: 'test-ws', token: 'mwt_abc123' });
+    });
+    // ── Constructor ────────────────────────────────────────────────
+    (0, vitest_1.it)('should build gateway URL from slug', () => {
+        const c = new workspace_client_1.WorkspaceClient({ slug: 'my-ws', token: 'mwt_x' });
+        // Verified via fetch call URL
+        (0, vitest_1.expect)(c).toBeInstanceOf(workspace_client_1.WorkspaceClient);
+    });
+    (0, vitest_1.it)('should use custom baseUrl', () => {
+        const c = new workspace_client_1.WorkspaceClient({ slug: 'x', token: 'mwt_x', baseUrl: 'https://custom.dev' });
+        (0, vitest_1.expect)(c).toBeInstanceOf(workspace_client_1.WorkspaceClient);
+    });
+    // ── initialize ─────────────────────────────────────────────────
+    (0, vitest_1.it)('should send initialize with MCP protocol params', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 0,
+            result: {
+                protocolVersion: '2024-11-05',
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: { name: 'gateway', version: '1.0.0' },
+            },
+        }));
+        const result = await client.initialize();
+        (0, vitest_1.expect)(result.protocolVersion).toBe('2024-11-05');
+        (0, vitest_1.expect)(result.serverInfo.name).toBe('gateway');
+        const [url, opts] = mockFetch.mock.calls[0];
+        (0, vitest_1.expect)(url).toBe('https://mcp.aerostack.dev/ws/test-ws');
+        const body = JSON.parse(opts.body);
+        (0, vitest_1.expect)(body.method).toBe('initialize');
+        (0, vitest_1.expect)(body.params.protocolVersion).toBe('2024-11-05');
+        (0, vitest_1.expect)(body.params.clientInfo.name).toBe('@aerostack/core');
+        (0, vitest_1.expect)(body.params.clientInfo.version).toBe('0.10.0');
+    });
+    // ── listTools ──────────────────────────────────────────────────
+    (0, vitest_1.it)('should list tools', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 1,
+            result: {
+                tools: [
+                    { name: 'github__create_issue', description: 'Create issue' },
+                    { name: 'linear__create_ticket', description: 'Create ticket' },
+                ],
+            },
+        }));
+        const tools = await client.listTools();
+        (0, vitest_1.expect)(tools).toHaveLength(2);
+        (0, vitest_1.expect)(tools[0].name).toBe('github__create_issue');
+    });
+    (0, vitest_1.it)('should return empty array when no tools', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 1, result: {},
+        }));
+        const tools = await client.listTools();
+        (0, vitest_1.expect)(tools).toEqual([]);
+    });
+    // ── callTool ───────────────────────────────────────────────────
+    (0, vitest_1.it)('should call a tool with arguments', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 2,
+            result: { content: [{ type: 'text', text: 'Issue created' }] },
+        }));
+        const result = await client.callTool('github__create_issue', { title: 'Bug' });
+        (0, vitest_1.expect)(result.content?.[0]?.text).toBe('Issue created');
+        const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+        (0, vitest_1.expect)(body.params.name).toBe('github__create_issue');
+        (0, vitest_1.expect)(body.params.arguments).toEqual({ title: 'Bug' });
+    });
+    // ── listResources ──────────────────────────────────────────────
+    (0, vitest_1.it)('should list resources', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 3,
+            result: { resources: [{ uri: 'github://repos', name: 'Repos' }] },
+        }));
+        const resources = await client.listResources();
+        (0, vitest_1.expect)(resources).toHaveLength(1);
+        (0, vitest_1.expect)(resources[0].uri).toBe('github://repos');
+    });
+    // ── readResource ───────────────────────────────────────────────
+    (0, vitest_1.it)('should read a resource', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 4,
+            result: { contents: [{ uri: 'github://repos/main', text: 'content' }] },
+        }));
+        const result = await client.readResource('github://repos/main');
+        (0, vitest_1.expect)(result.contents[0].text).toBe('content');
+    });
+    // ── ping ───────────────────────────────────────────────────────
+    (0, vitest_1.it)('should ping successfully', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({ jsonrpc: '2.0', id: 5, result: {} }));
+        await (0, vitest_1.expect)(client.ping()).resolves.toBeUndefined();
+    });
+    // ── Error handling ─────────────────────────────────────────────
+    (0, vitest_1.it)('should throw AerostackError on JSON-RPC error', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 1,
+            error: { code: -32602, message: 'Invalid params' },
+        }, 400));
+        try {
+            await client.listTools();
+            vitest_1.expect.unreachable('Should have thrown');
+        }
+        catch (e) {
+            (0, vitest_1.expect)(e).toBeInstanceOf(workspace_client_1.AerostackError);
+            const err = e;
+            (0, vitest_1.expect)(err.message).toBe('Invalid params');
+            (0, vitest_1.expect)(err.statusCode).toBe(400);
+            (0, vitest_1.expect)(err.rpcCode).toBe(-32602);
+            (0, vitest_1.expect)(err.requestId).toBe('test-req-uuid');
+        }
+    });
+    (0, vitest_1.it)('should throw AerostackError on non-JSON response', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false, status: 502, statusText: 'Bad Gateway',
+            json: () => Promise.reject(new SyntaxError('Unexpected token')),
+        });
+        try {
+            await client.listTools();
+            vitest_1.expect.unreachable('Should have thrown');
+        }
+        catch (e) {
+            (0, vitest_1.expect)(e).toBeInstanceOf(workspace_client_1.AerostackError);
+            const err = e;
+            (0, vitest_1.expect)(err.statusCode).toBe(502);
+            (0, vitest_1.expect)(err.rpcCode).toBe(-32700);
+            (0, vitest_1.expect)(err.message).toContain('Non-JSON');
+        }
+    });
+    (0, vitest_1.it)('should throw AerostackError on HTTP error without JSON-RPC error body', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({ message: 'rate limited' }, // valid JSON but no .error field
+        429, 'Too Many Requests'));
+        try {
+            await client.listTools();
+            vitest_1.expect.unreachable('Should have thrown');
+        }
+        catch (e) {
+            (0, vitest_1.expect)(e).toBeInstanceOf(workspace_client_1.AerostackError);
+            const err = e;
+            (0, vitest_1.expect)(err.statusCode).toBe(429);
+            (0, vitest_1.expect)(err.message).toContain('429');
+        }
+    });
+    // ── Auth header ────────────────────────────────────────────────
+    (0, vitest_1.it)('should send Bearer token in Authorization header', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({ jsonrpc: '2.0', id: 0, result: {} }));
+        await client.ping();
+        const headers = mockFetch.mock.calls[0][1].headers;
+        (0, vitest_1.expect)(headers['Authorization']).toBe('Bearer mwt_abc123');
+    });
+});

package/dist/client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AerostackClient = exports.AerocallClient = void 0;
+const workspace_client_1 = require("./workspace-client");
 /** @deprecated Use AerostackClient instead. */
 class AerocallClient {
     constructor(config) {
@@ -23,14 +24,18 @@ class AerocallClient {
         return headers;
     }
     async request(path, method, body, isMultipart = false) {
+        const headers = this.getHeaders(isMultipart);
+        const requestId = headers['X-Request-ID'] ?? '';
         const response = await fetch(`${this.baseUrl}${path}`, {
             method,
-            headers: this.getHeaders(isMultipart),
+            headers,
             body: isMultipart ? body : (body ? JSON.stringify(body) : undefined)
         });
         if (!response.ok) {
             const err = await response.json().catch(() => ({ error: { message: response.statusText } }));
-            throw new Error(err.error?.message || 'Unknown error');
+            const message = err.error?.message || 'Unknown error';
+            const code = err.error?.code;
+            throw new workspace_client_1.AerostackError(message, response.status, code ?? response.status, requestId);
         }
         return response.json();
     }

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { AerocallClient, AerocallConfig, AerostackClient, AerostackConfig } from './client';
+export { WorkspaceClient, AerostackError } from './workspace-client';
+export type { WorkspaceClientConfig, McpTool, McpResource, McpToolResult, McpResourceContent } from './workspace-client';
 export * from './types';
 export * from './types/gateway';

package/dist/index.js

@@ -14,9 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AerostackClient = exports.AerocallClient = void 0;
+exports.AerostackError = exports.WorkspaceClient = exports.AerostackClient = exports.AerocallClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "AerocallClient", { enumerable: true, get: function () { return client_1.AerocallClient; } });
 Object.defineProperty(exports, "AerostackClient", { enumerable: true, get: function () { return client_1.AerostackClient; } });
+var workspace_client_1 = require("./workspace-client");
+Object.defineProperty(exports, "WorkspaceClient", { enumerable: true, get: function () { return workspace_client_1.WorkspaceClient; } });
+Object.defineProperty(exports, "AerostackError", { enumerable: true, get: function () { return workspace_client_1.AerostackError; } });
 __exportStar(require("./types"), exports);
 __exportStar(require("./types/gateway"), exports);

package/dist/workspace-client.d.ts

@@ -0,0 +1,95 @@
+/**
+ * WorkspaceClient — typed client for Aerostack MCP Workspace Gateway.
+ *
+ * Wraps the JSON-RPC 2.0 protocol for MCP workspace tool discovery and invocation.
+ * Uses workspace tokens (mwt_) for auth, separate from project API keys.
+ *
+ * @example
+ * ```ts
+ * const ws = new WorkspaceClient({
+ *     slug: 'my-workspace',
+ *     token: 'mwt_...',
+ * });
+ *
+ * const tools = await ws.listTools();
+ * const result = await ws.callTool('github__create_issue', { title: 'Bug fix' });
+ * ```
+ */
+export interface WorkspaceClientConfig {
+    /** Workspace slug (used in gateway URL) */
+    slug: string;
+    /** Workspace token (mwt_...) */
+    token: string;
+    /** Override gateway base URL (default: https://mcp.aerostack.dev) */
+    baseUrl?: string;
+}
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+export interface McpResource {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface McpToolResult {
+    content?: Array<{
+        type: string;
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+export interface McpResourceContent {
+    contents: Array<{
+        uri: string;
+        text?: string;
+        blob?: string;
+        mimeType?: string;
+    }>;
+}
+export declare class AerostackError extends Error {
+    readonly statusCode: number;
+    readonly rpcCode: number;
+    readonly requestId: string;
+    constructor(message: string, statusCode: number, rpcCode: number, requestId: string);
+}
+export declare class WorkspaceClient {
+    private readonly gatewayUrl;
+    private readonly token;
+    private rpcId;
+    constructor(config: WorkspaceClientConfig);
+    /** Send a JSON-RPC 2.0 request to the workspace gateway. */
+    private rpc;
+    /** Initialize the MCP session. Sends required protocol fields per MCP spec. */
+    initialize(): Promise<{
+        protocolVersion: string;
+        capabilities: Record<string, unknown>;
+        serverInfo: {
+            name: string;
+            version: string;
+        };
+        instructions?: string;
+    }>;
+    /** List all tools available in this workspace (namespaced as server__tool). */
+    listTools(): Promise<McpTool[]>;
+    /**
+     * Call a tool by its namespaced name.
+     * @param name - Tool name in "server__tool" format (e.g. "github__create_issue")
+     * @param args - Tool arguments matching the tool's inputSchema
+     */
+    callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+    /** List all resources available across workspace servers. */
+    listResources(): Promise<McpResource[]>;
+    /**
+     * Read a specific resource by its namespaced URI.
+     * @param uri - Resource URI in "serverSlug://originalUri" format
+     */
+    readResource(uri: string): Promise<McpResourceContent>;
+    /** Ping the workspace gateway (health check). */
+    ping(): Promise<void>;
+}

package/dist/workspace-client.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * WorkspaceClient — typed client for Aerostack MCP Workspace Gateway.
+ *
+ * Wraps the JSON-RPC 2.0 protocol for MCP workspace tool discovery and invocation.
+ * Uses workspace tokens (mwt_) for auth, separate from project API keys.
+ *
+ * @example
+ * ```ts
+ * const ws = new WorkspaceClient({
+ *     slug: 'my-workspace',
+ *     token: 'mwt_...',
+ * });
+ *
+ * const tools = await ws.listTools();
+ * const result = await ws.callTool('github__create_issue', { title: 'Bug fix' });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkspaceClient = exports.AerostackError = void 0;
+class AerostackError extends Error {
+    constructor(message, statusCode, rpcCode, requestId) {
+        super(message);
+        this.name = 'AerostackError';
+        this.statusCode = statusCode;
+        this.rpcCode = rpcCode;
+        this.requestId = requestId;
+    }
+}
+exports.AerostackError = AerostackError;
+class WorkspaceClient {
+    constructor(config) {
+        this.rpcId = 0;
+        const base = (config.baseUrl ?? 'https://mcp.aerostack.dev').replace(/\/$/, '');
+        this.gatewayUrl = `${base}/ws/${config.slug}`;
+        this.token = config.token;
+    }
+    /** Send a JSON-RPC 2.0 request to the workspace gateway. */
+    async rpc(method, params = {}) {
+        const id = this.rpcId++;
+        const requestId = typeof crypto !== 'undefined' && crypto.randomUUID
+            ? crypto.randomUUID()
+            : `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const res = await fetch(this.gatewayUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.token}`,
+                'X-Request-ID': requestId,
+            },
+            body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+        });
+        // Guard against non-JSON responses (502, 503, rate-limit HTML, etc.)
+        let data;
+        try {
+            data = await res.json();
+        }
+        catch {
+            throw new AerostackError(`Non-JSON response from gateway (HTTP ${res.status})`, res.status, -32700, requestId);
+        }
+        // Handle HTTP errors that don't include a JSON-RPC error body
+        if (!res.ok && !data.error) {
+            throw new AerostackError(`HTTP ${res.status}: ${res.statusText}`, res.status, -32603, requestId);
+        }
+        if (data.error) {
+            throw new AerostackError(data.error.message, res.status, data.error.code, requestId);
+        }
+        return data.result;
+    }
+    /** Initialize the MCP session. Sends required protocol fields per MCP spec. */
+    async initialize() {
+        return this.rpc('initialize', {
+            protocolVersion: '2024-11-05',
+            clientInfo: { name: '@aerostack/core', version: '0.10.0' },
+            capabilities: {},
+        });
+    }
+    /** List all tools available in this workspace (namespaced as server__tool). */
+    async listTools() {
+        const result = await this.rpc('tools/list');
+        return result.tools ?? [];
+    }
+    /**
+     * Call a tool by its namespaced name.
+     * @param name - Tool name in "server__tool" format (e.g. "github__create_issue")
+     * @param args - Tool arguments matching the tool's inputSchema
+     */
+    async callTool(name, args = {}) {
+        return this.rpc('tools/call', { name, arguments: args });
+    }
+    /** List all resources available across workspace servers. */
+    async listResources() {
+        const result = await this.rpc('resources/list');
+        return result.resources ?? [];
+    }
+    /**
+     * Read a specific resource by its namespaced URI.
+     * @param uri - Resource URI in "serverSlug://originalUri" format
+     */
+    async readResource(uri) {
+        return this.rpc('resources/read', { uri });
+    }
+    /** Ping the workspace gateway (health check). */
+    async ping() {
+        await this.rpc('ping');
+    }
+}
+exports.WorkspaceClient = WorkspaceClient;

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@aerostack/core",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Shared types and RPC client for Aerostack SDKs",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "files": [

package/src/__tests__/workspace-client.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { WorkspaceClient, AerostackError } from '../workspace-client';
+
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+vi.stubGlobal('crypto', { randomUUID: () => 'test-req-uuid' });
+
+function jsonResponse(body: unknown, status = 200, statusText = 'OK') {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText,
+        json: () => Promise.resolve(body),
+        headers: new Map(),
+    };
+}
+
+describe('WorkspaceClient', () => {
+    let client: WorkspaceClient;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        client = new WorkspaceClient({ slug: 'test-ws', token: 'mwt_abc123' });
+    });
+
+    // ── Constructor ────────────────────────────────────────────────
+
+    it('should build gateway URL from slug', () => {
+        const c = new WorkspaceClient({ slug: 'my-ws', token: 'mwt_x' });
+        // Verified via fetch call URL
+        expect(c).toBeInstanceOf(WorkspaceClient);
+    });
+
+    it('should use custom baseUrl', () => {
+        const c = new WorkspaceClient({ slug: 'x', token: 'mwt_x', baseUrl: 'https://custom.dev' });
+        expect(c).toBeInstanceOf(WorkspaceClient);
+    });
+
+    // ── initialize ─────────────────────────────────────────────────
+
+    it('should send initialize with MCP protocol params', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 0,
+            result: {
+                protocolVersion: '2024-11-05',
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: { name: 'gateway', version: '1.0.0' },
+            },
+        }));
+
+        const result = await client.initialize();
+        expect(result.protocolVersion).toBe('2024-11-05');
+        expect(result.serverInfo.name).toBe('gateway');
+
+        const [url, opts] = mockFetch.mock.calls[0];
+        expect(url).toBe('https://mcp.aerostack.dev/ws/test-ws');
+        const body = JSON.parse(opts.body);
+        expect(body.method).toBe('initialize');
+        expect(body.params.protocolVersion).toBe('2024-11-05');
+        expect(body.params.clientInfo.name).toBe('@aerostack/core');
+        expect(body.params.clientInfo.version).toBe('0.10.0');
+    });
+
+    // ── listTools ──────────────────────────────────────────────────
+
+    it('should list tools', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 1,
+            result: {
+                tools: [
+                    { name: 'github__create_issue', description: 'Create issue' },
+                    { name: 'linear__create_ticket', description: 'Create ticket' },
+                ],
+            },
+        }));
+
+        const tools = await client.listTools();
+        expect(tools).toHaveLength(2);
+        expect(tools[0].name).toBe('github__create_issue');
+    });
+
+    it('should return empty array when no tools', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 1, result: {},
+        }));
+        const tools = await client.listTools();
+        expect(tools).toEqual([]);
+    });
+
+    // ── callTool ───────────────────────────────────────────────────
+
+    it('should call a tool with arguments', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 2,
+            result: { content: [{ type: 'text', text: 'Issue created' }] },
+        }));
+
+        const result = await client.callTool('github__create_issue', { title: 'Bug' });
+        expect(result.content?.[0]?.text).toBe('Issue created');
+
+        const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+        expect(body.params.name).toBe('github__create_issue');
+        expect(body.params.arguments).toEqual({ title: 'Bug' });
+    });
+
+    // ── listResources ──────────────────────────────────────────────
+
+    it('should list resources', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 3,
+            result: { resources: [{ uri: 'github://repos', name: 'Repos' }] },
+        }));
+
+        const resources = await client.listResources();
+        expect(resources).toHaveLength(1);
+        expect(resources[0].uri).toBe('github://repos');
+    });
+
+    // ── readResource ───────────────────────────────────────────────
+
+    it('should read a resource', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 4,
+            result: { contents: [{ uri: 'github://repos/main', text: 'content' }] },
+        }));
+
+        const result = await client.readResource('github://repos/main');
+        expect(result.contents[0].text).toBe('content');
+    });
+
+    // ── ping ───────────────────────────────────────────────────────
+
+    it('should ping successfully', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({ jsonrpc: '2.0', id: 5, result: {} }));
+        await expect(client.ping()).resolves.toBeUndefined();
+    });
+
+    // ── Error handling ─────────────────────────────────────────────
+
+    it('should throw AerostackError on JSON-RPC error', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({
+            jsonrpc: '2.0', id: 1,
+            error: { code: -32602, message: 'Invalid params' },
+        }, 400));
+
+        try {
+            await client.listTools();
+            expect.unreachable('Should have thrown');
+        } catch (e) {
+            expect(e).toBeInstanceOf(AerostackError);
+            const err = e as AerostackError;
+            expect(err.message).toBe('Invalid params');
+            expect(err.statusCode).toBe(400);
+            expect(err.rpcCode).toBe(-32602);
+            expect(err.requestId).toBe('test-req-uuid');
+        }
+    });
+
+    it('should throw AerostackError on non-JSON response', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false, status: 502, statusText: 'Bad Gateway',
+            json: () => Promise.reject(new SyntaxError('Unexpected token')),
+        });
+
+        try {
+            await client.listTools();
+            expect.unreachable('Should have thrown');
+        } catch (e) {
+            expect(e).toBeInstanceOf(AerostackError);
+            const err = e as AerostackError;
+            expect(err.statusCode).toBe(502);
+            expect(err.rpcCode).toBe(-32700);
+            expect(err.message).toContain('Non-JSON');
+        }
+    });
+
+    it('should throw AerostackError on HTTP error without JSON-RPC error body', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse(
+            { message: 'rate limited' }, // valid JSON but no .error field
+            429, 'Too Many Requests',
+        ));
+
+        try {
+            await client.listTools();
+            expect.unreachable('Should have thrown');
+        } catch (e) {
+            expect(e).toBeInstanceOf(AerostackError);
+            const err = e as AerostackError;
+            expect(err.statusCode).toBe(429);
+            expect(err.message).toContain('429');
+        }
+    });
+
+    // ── Auth header ────────────────────────────────────────────────
+
+    it('should send Bearer token in Authorization header', async () => {
+        mockFetch.mockResolvedValueOnce(jsonResponse({ jsonrpc: '2.0', id: 0, result: {} }));
+        await client.ping();
+
+        const headers = mockFetch.mock.calls[0][1].headers;
+        expect(headers['Authorization']).toBe('Bearer mwt_abc123');
+    });
+});

package/src/client.ts

@@ -1,4 +1,5 @@
 import { AerostackRPC, CollectionItem, CacheListResult, CacheSetEntry, StorageListResult, JobRecord } from './types';
+import { AerostackError } from './workspace-client';
 
 /** @deprecated Use AerostackConfig instead. */
 export interface AerocallConfig {
@@ -35,15 +36,19 @@ export class AerocallClient implements AerostackRPC {
     }
 
     private async request<T>(path: string, method: string, body?: any, isMultipart = false): Promise<T> {
+        const headers = this.getHeaders(isMultipart);
+        const requestId = headers['X-Request-ID'] ?? '';
         const response = await fetch(`${this.baseUrl}${path}`, {
             method,
-            headers: this.getHeaders(isMultipart),
+            headers,
             body: isMultipart ? body : (body ? JSON.stringify(body) : undefined)
         });
 
         if (!response.ok) {
             const err = await response.json().catch(() => ({ error: { message: response.statusText } }));
-            throw new Error((err as any).error?.message || 'Unknown error');
+            const message = (err as any).error?.message || 'Unknown error';
+            const code = (err as any).error?.code;
+            throw new AerostackError(message, response.status, code ?? response.status, requestId);
         }
         return response.json() as Promise<T>;
     }

package/src/index.ts

@@ -1,3 +1,5 @@
 export { AerocallClient, AerocallConfig, AerostackClient, AerostackConfig } from './client';
+export { WorkspaceClient, AerostackError } from './workspace-client';
+export type { WorkspaceClientConfig, McpTool, McpResource, McpToolResult, McpResourceContent } from './workspace-client';
 export * from './types';
 export * from './types/gateway';

package/src/workspace-client.ts

@@ -0,0 +1,175 @@
+/**
+ * WorkspaceClient — typed client for Aerostack MCP Workspace Gateway.
+ *
+ * Wraps the JSON-RPC 2.0 protocol for MCP workspace tool discovery and invocation.
+ * Uses workspace tokens (mwt_) for auth, separate from project API keys.
+ *
+ * @example
+ * ```ts
+ * const ws = new WorkspaceClient({
+ *     slug: 'my-workspace',
+ *     token: 'mwt_...',
+ * });
+ *
+ * const tools = await ws.listTools();
+ * const result = await ws.callTool('github__create_issue', { title: 'Bug fix' });
+ * ```
+ */
+
+export interface WorkspaceClientConfig {
+    /** Workspace slug (used in gateway URL) */
+    slug: string;
+    /** Workspace token (mwt_...) */
+    token: string;
+    /** Override gateway base URL (default: https://mcp.aerostack.dev) */
+    baseUrl?: string;
+}
+
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+
+export interface McpResource {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+
+export interface McpToolResult {
+    content?: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+
+export interface McpResourceContent {
+    contents: Array<{ uri: string; text?: string; blob?: string; mimeType?: string }>;
+}
+
+export class AerostackError extends Error {
+    public readonly statusCode: number;
+    public readonly rpcCode: number;
+    public readonly requestId: string;
+
+    constructor(message: string, statusCode: number, rpcCode: number, requestId: string) {
+        super(message);
+        this.name = 'AerostackError';
+        this.statusCode = statusCode;
+        this.rpcCode = rpcCode;
+        this.requestId = requestId;
+    }
+}
+
+export class WorkspaceClient {
+    private readonly gatewayUrl: string;
+    private readonly token: string;
+    private rpcId = 0;
+
+    constructor(config: WorkspaceClientConfig) {
+        const base = (config.baseUrl ?? 'https://mcp.aerostack.dev').replace(/\/$/, '');
+        this.gatewayUrl = `${base}/ws/${config.slug}`;
+        this.token = config.token;
+    }
+
+    /** Send a JSON-RPC 2.0 request to the workspace gateway. */
+    private async rpc<T = unknown>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+        const id = this.rpcId++;
+        const requestId = typeof crypto !== 'undefined' && crypto.randomUUID
+            ? crypto.randomUUID()
+            : `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+        const res = await fetch(this.gatewayUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.token}`,
+                'X-Request-ID': requestId,
+            },
+            body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+        });
+
+        // Guard against non-JSON responses (502, 503, rate-limit HTML, etc.)
+        let data: { jsonrpc: string; id: number; result?: T; error?: { code: number; message: string } };
+        try {
+            data = await res.json() as typeof data;
+        } catch {
+            throw new AerostackError(
+                `Non-JSON response from gateway (HTTP ${res.status})`,
+                res.status,
+                -32700,
+                requestId,
+            );
+        }
+
+        // Handle HTTP errors that don't include a JSON-RPC error body
+        if (!res.ok && !data.error) {
+            throw new AerostackError(
+                `HTTP ${res.status}: ${res.statusText}`,
+                res.status,
+                -32603,
+                requestId,
+            );
+        }
+
+        if (data.error) {
+            throw new AerostackError(
+                data.error.message,
+                res.status,
+                data.error.code,
+                requestId,
+            );
+        }
+
+        return data.result as T;
+    }
+
+    /** Initialize the MCP session. Sends required protocol fields per MCP spec. */
+    async initialize(): Promise<{
+        protocolVersion: string;
+        capabilities: Record<string, unknown>;
+        serverInfo: { name: string; version: string };
+        instructions?: string;
+    }> {
+        return this.rpc('initialize', {
+            protocolVersion: '2024-11-05',
+            clientInfo: { name: '@aerostack/core', version: '0.10.0' },
+            capabilities: {},
+        });
+    }
+
+    /** List all tools available in this workspace (namespaced as server__tool). */
+    async listTools(): Promise<McpTool[]> {
+        const result = await this.rpc<{ tools: McpTool[] }>('tools/list');
+        return result.tools ?? [];
+    }
+
+    /**
+     * Call a tool by its namespaced name.
+     * @param name - Tool name in "server__tool" format (e.g. "github__create_issue")
+     * @param args - Tool arguments matching the tool's inputSchema
+     */
+    async callTool(name: string, args: Record<string, unknown> = {}): Promise<McpToolResult> {
+        return this.rpc<McpToolResult>('tools/call', { name, arguments: args });
+    }
+
+    /** List all resources available across workspace servers. */
+    async listResources(): Promise<McpResource[]> {
+        const result = await this.rpc<{ resources: McpResource[] }>('resources/list');
+        return result.resources ?? [];
+    }
+
+    /**
+     * Read a specific resource by its namespaced URI.
+     * @param uri - Resource URI in "serverSlug://originalUri" format
+     */
+    async readResource(uri: string): Promise<McpResourceContent> {
+        return this.rpc<McpResourceContent>('resources/read', { uri });
+    }
+
+    /** Ping the workspace gateway (health check). */
+    async ping(): Promise<void> {
+        await this.rpc('ping');
+    }
+}