skedyul 0.1.0

package/README.md

@@ -0,0 +1,219 @@
+# skedyul
+
+Reusable helpers for building Model Context Protocol (MCP) runtimes in Node.js. This package powers the dedicated and serverless starters by exposing registry typing, environment helpers, and a shared `server.create` factory that wires JSON-RPC tooling, request counting, and runtime-specific adapters.
+
+## What's inside
+
+- `ToolContext`, `ToolHandler`, and supporting typings so registries can stay strongly typed.
+- `server.create` accepts a config object (metadata, compute layer, rate limits, CORS) and a tool registry, then exposes a `listen()` API for HTTP servers and a Lambda-style `handler()` respectively.
+- Request counting, TTL, env merging (`MCP_ENV_JSON` + `MCP_ENV`), JSON-RPC transport, and health metadata so each runtime behaves consistently.
+
+## Billing contract
+
+Every `ToolHandler` must return both its result payload (`output`) and a `billing` object describing the credits consumed:
+
+```ts
+export const helloWorld: ToolHandler<HelloWorldInput, HelloWorldOutput> = async ({
+  input,
+  context,
+}) => {
+  // Do your work here...
+  const credits = calculateCredits(input, context) // e.g. characters × rate
+
+  return {
+    output: {
+      message: `Hello, ${input.name ?? 'world'}`,
+      environmentName: context.env.SKEDYUL_ENV ?? 'local',
+    },
+    billing: { credits },
+  }
+}
+```
+
+Servers attach that `billing` data to every MCP response, so callers always know the final credit cost. Since pricing may depend on runtime data (like message length), compute credits inside the registry or another secure helper that can read your pricing tables, rather than in the shared server logic.
+
+## Estimate endpoint
+
+Both transports expose a dedicated `POST /estimate` endpoint that reuses the same registry to calculate projected billing without executing charged work. Callers supply a tool name and inputs, and the server forwards the request to the registry with `context.mode === 'estimate'`. The response contains only the `billing` block:
+
+```json
+POST /estimate
+{
+  "name": "hello-world",
+  "inputs": { "name": "demo" }
+}
+
+200 OK
+{
+  "billing": { "credits": 4 }
+}
+```
+
+Treat `/estimate` as an authentication-protected route (if your runtime supports auth) because it exposes pricing metadata. Keep your pricing tables and cost calculations in a guarded part of your stack, and never return internal secrets through `estimate`.
+
+## Core API hooks
+
+For integration-specific RPCs that belong to your platform rather than a tool, provide a `coreApi` implementation when calling `server.create`. The property accepts:
+
+- `service`: an object implementing `createCommunicationChannel`, `updateCommunicationChannel`, `deleteCommunicationChannel`, `getCommunicationChannel`, `getCommunicationChannels`, and `sendMessage`.
+- `webhookHandler`: an optional `(request: WebhookRequest) => Promise<WebhookResponse>` callback that will receive forwarded HTTP webhooks.
+
+The MCP server exposes `POST /core` (with `{ method, params }`) and `POST /core/webhook` for these operations. They never appear under `tools/list` unlesstaken explicit MCP tooling—they are separate transport-level handlers and do not count against tool request limits. Make sure your service returns the structured channel/message data defined in `src/core/types.ts` so the responses stay consistent, and guard `/core`/`/core/webhook` with your platform’s preferred authentication if you surface them externally.
+
+## Higher-level helpers
+
+While `server.create` hosts the MCP surface, `skedyul.workplace` and `skedyul.communicationChannel` expose dedicated helpers that talk to `/core` for the same workplace and channel metadata. Each helper returns the typed objects defined in `src/core/types.ts` so integrations can look up a channel/workplace pair before acting on an incoming webhook without manually composing the RPC payload or dealing with authentication.
+
+The helpers currently provide:
+
+- `workplace.list(filter?: Record<string, unknown>)`
+- `workplace.get(id: string)`
+- `communicationChannel.list(filter?: Record<string, unknown>)`
+- `communicationChannel.get(id: string)`
+
+Example:
+
+```ts
+import { communicationChannel, workplace } from 'skedyul'
+
+const [channel] = await communicationChannel.list({
+  filter: { identifierValue: '+15551234567' },
+})
+
+const owner = await workplace.get(channel.workplaceId)
+```
+
+Use these helpers for internal wiring—like pulling the correct workplace for a webhook—without touching the MCP tooling surface directly.
+
+## Installation
+
+```bash
+npm install skedyul
+```
+
+## Usage
+
+### Define your registry
+
+Each tool should follow the shared handler signature:
+
+```ts
+import type { ToolContext, ToolHandler } from 'skedyul'
+
+export interface HelloWorldInput {
+  name?: string
+}
+
+export interface HelloWorldOutput {
+  message: string
+  environmentName: string
+}
+
+export const helloWorld: ToolHandler<HelloWorldInput, HelloWorldOutput> = async ({
+  input,
+  context,
+}) => {
+  const name = input.name?.trim() || 'world'
+  const environmentName = context.env.SKEDYUL_ENV ?? 'local'
+
+  return {
+    message: `Hello, ${name}!`,
+    environmentName,
+  }
+}
+
+export const registry = {
+  'hello-world': helloWorld,
+}
+```
+
+### Dedicated server
+
+```ts
+import { server } from 'skedyul'
+import { registry } from './registry'
+
+const mcpServer = server.create(
+  {
+    computeLayer: 'dedicated',
+    metadata: {
+      name: 'my-dedicated-server',
+      version: '1.0.0',
+    },
+    defaultPort: 3000,
+    maxRequests: 1000,
+    ttlExtendSeconds: 3600,
+  },
+  registry,
+)
+
+await mcpServer.listen()
+```
+
+### Serverless handler
+
+```ts
+import { server } from 'skedyul'
+import { registry } from './registry'
+
+const mcpServer = server.create(
+  {
+    computeLayer: 'serverless',
+    metadata: {
+      name: 'my-serverless-mcp',
+      version: '1.0.0',
+    },
+    cors: {
+      allowOrigin: '*',
+    },
+  },
+  registry,
+)
+
+export const handler = mcpServer.handler
+```
+
+## Configuration guide
+
+- **`computeLayer`**: Choose `dedicated` to expose an HTTP server (`listen`) or `serverless` to get a Lambda handler (`handler`).
+- **`metadata`**: Used for the MCP server versioning payload.
+- **`maxRequests` / `ttlExtendSeconds`**: Control request capping logic that triggers a graceful shutdown (dedicated) or throttles health stats.
+- **`cors`**: Serverless handlers automatically add the configured CORS headers to every response.
+- **Runtime env overrides**: `MCP_ENV_JSON` (build-time) and `MCP_ENV` (container runtime) merge into `process.env` before every request, while request-level `env` arguments temporarily override env vars per tool call.
+
+## Health metadata
+
+Both adapters expose `getHealthStatus()`, returning:
+
+- `status`: always `running` while the process is alive.
+- `requests`, `maxRequests`, `requestsRemaining`.
+- `lastRequestTime`, `ttlExtendSeconds`.
+- `runtime`: string label (`dedicated` or `serverless`).
+- `tools`: list of registered tool names.
+
+## Development
+
+- `npm run build` compiles the TypeScript sources into `dist/`.
+- `npm test` rebuilds the package and runs `tests/server.test.js` against the compiled output.
+- `npm run lint` (if added later) should validate formatting/typing.
+
+## Publishing
+
+Before publishing:
+
+1. Run `npm run build`.
+2. Verify `dist/index.js` and `.d.ts` exist.
+3. Ensure `package.json` metadata (name, version, description, repository, author, license) matches the npm listing.
+
+Use `npm publish --access public` once the package is ready; the `files` array already limits the tarball to `dist/`.
+
+## Contributing
+
+Contributions should:
+
+1. Follow the TypeScript style (strict types, async/await, try/catch).
+2. Keep MCP transports lean and share logic in `src/server.ts`.
+3. Add unit tests under `tests/` and run them via `npm test`.
+
+Open a PR with a clear summary so the release process can verify `dist/` artifacts before publishing.
+

package/dist/core/client.d.ts

@@ -0,0 +1,13 @@
+import type { CommunicationChannel, Workplace } from './types';
+type ListArgs = {
+    filter?: Record<string, unknown>;
+};
+export declare const workplace: {
+    list(args?: ListArgs): Promise<Workplace[]>;
+    get(id: string): Promise<Workplace>;
+};
+export declare const communicationChannel: {
+    list(filter?: Record<string, unknown>): Promise<CommunicationChannel[]>;
+    get(id: string): Promise<CommunicationChannel>;
+};
+export {};

package/dist/core/client.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.communicationChannel = exports.workplace = void 0;
+const CORE_BASE = process.env.SKEDYUL_NODE_URL ?? '';
+async function callCore(method, params) {
+    const response = await fetch(`${CORE_BASE}/core`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ method, params }),
+    });
+    const payload = await response.json();
+    if (!response.ok) {
+        throw new Error(payload?.error?.message ?? `Core API error (${response.status})`);
+    }
+    return payload;
+}
+exports.workplace = {
+    async list(args) {
+        const payload = await callCore('workplace.list', args?.filter ? { filter: args.filter } : undefined);
+        return payload.workplaces;
+    },
+    async get(id) {
+        const payload = await callCore('workplace.get', { id });
+        return payload.workplace;
+    },
+};
+exports.communicationChannel = {
+    async list(filter) {
+        const payload = await callCore('communicationChannel.list', filter ? { filter } : undefined);
+        return payload.channels;
+    },
+    async get(id) {
+        const payload = await callCore('communicationChannel.get', { id });
+        return payload.channel;
+    },
+};

package/dist/core/service.d.ts

@@ -0,0 +1,38 @@
+import type { CommunicationChannel, CommunicationService, Message, WebhookRequest, WebhookResponse } from './types';
+declare class CoreApiService {
+    private service?;
+    private webhookHandler?;
+    register(service: CommunicationService): void;
+    getService(): CommunicationService | undefined;
+    setWebhookHandler(handler: (request: WebhookRequest) => Promise<WebhookResponse>): void;
+    dispatchWebhook(request: WebhookRequest): Promise<WebhookResponse>;
+    callCreateChannel(channel: CommunicationChannel): Promise<{
+        channel: CommunicationChannel;
+    } | undefined>;
+    callUpdateChannel(channel: CommunicationChannel): Promise<{
+        channel: CommunicationChannel;
+    } | undefined>;
+    callDeleteChannel(id: string): Promise<{
+        success: boolean;
+    } | undefined>;
+    callGetChannel(id: string): Promise<{
+        channel: CommunicationChannel;
+    } | undefined>;
+    callListChannels(): Promise<{
+        channels: CommunicationChannel[];
+    } | undefined>;
+    callGetWorkplace(id: string): Promise<{
+        workplace: import("./types").Workplace;
+    } | undefined>;
+    callListWorkplaces(): Promise<{
+        workplaces: import("./types").Workplace[];
+    } | undefined>;
+    callSendMessage(args: {
+        message: Message;
+        communicationChannel: CommunicationChannel;
+    }): Promise<{
+        message: Message;
+    } | undefined>;
+}
+export declare const coreApiService: CoreApiService;
+export {};

package/dist/core/service.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coreApiService = void 0;
+class CoreApiService {
+    register(service) {
+        this.service = service;
+    }
+    getService() {
+        return this.service;
+    }
+    setWebhookHandler(handler) {
+        this.webhookHandler = handler;
+    }
+    async dispatchWebhook(request) {
+        if (!this.webhookHandler) {
+            return { status: 404 };
+        }
+        return this.webhookHandler(request);
+    }
+    async callCreateChannel(channel) {
+        return this.service?.createCommunicationChannel(channel);
+    }
+    async callUpdateChannel(channel) {
+        return this.service?.updateCommunicationChannel(channel);
+    }
+    async callDeleteChannel(id) {
+        return this.service?.deleteCommunicationChannel(id);
+    }
+    async callGetChannel(id) {
+        return this.service?.getCommunicationChannel(id);
+    }
+    async callListChannels() {
+        return this.service?.getCommunicationChannels();
+    }
+    async callGetWorkplace(id) {
+        return this.service?.getWorkplace(id);
+    }
+    async callListWorkplaces() {
+        return this.service?.listWorkplaces();
+    }
+    async callSendMessage(args) {
+        return this.service?.sendMessage(args);
+    }
+}
+exports.coreApiService = new CoreApiService();

package/dist/core/types.d.ts

@@ -0,0 +1,63 @@
+export interface CommunicationChannel {
+    id: string;
+    name: string;
+    type: 'sms' | 'whatsapp' | 'email';
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface Workplace {
+    id: string;
+    name: string;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface Message {
+    id: string;
+    channelId: string;
+    body: string;
+    sentAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface WebhookRequest {
+    method: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    query?: Record<string, string | undefined>;
+}
+export interface WebhookResponse {
+    status: number;
+    body?: unknown;
+}
+export interface CommunicationService {
+    createCommunicationChannel(channel: CommunicationChannel): Promise<{
+        channel: CommunicationChannel;
+    }>;
+    updateCommunicationChannel(channel: CommunicationChannel): Promise<{
+        channel: CommunicationChannel;
+    }>;
+    deleteCommunicationChannel(id: string): Promise<{
+        success: boolean;
+    }>;
+    getCommunicationChannel(id: string): Promise<{
+        channel: CommunicationChannel;
+    }>;
+    getCommunicationChannels(): Promise<{
+        channels: CommunicationChannel[];
+    }>;
+    sendMessage(args: {
+        message: Message;
+        communicationChannel: CommunicationChannel;
+    }): Promise<{
+        message: Message;
+    }>;
+    getWorkplace(id: string): Promise<{
+        workplace: Workplace;
+    }>;
+    listWorkplaces(): Promise<{
+        workplaces: Workplace[];
+    }>;
+}
+export interface CoreApiConfig {
+    service: CommunicationService;
+    webhookHandler?: (request: WebhookRequest) => Promise<WebhookResponse>;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export { server } from './server';
+export { workplace, communicationChannel } from './core/client';

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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.communicationChannel = exports.workplace = exports.server = void 0;
+__exportStar(require("./types"), exports);
+var server_1 = require("./server");
+Object.defineProperty(exports, "server", { enumerable: true, get: function () { return server_1.server; } });
+var client_1 = require("./core/client");
+Object.defineProperty(exports, "workplace", { enumerable: true, get: function () { return client_1.workplace; } });
+Object.defineProperty(exports, "communicationChannel", { enumerable: true, get: function () { return client_1.communicationChannel; } });

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import type { SkedyulServerConfig, SkedyulServerInstance, ToolRegistry } from './types';
+export declare function createSkedyulServer(config: SkedyulServerConfig, registry: ToolRegistry): SkedyulServerInstance;
+export declare const server: {
+    create: typeof createSkedyulServer;
+};

package/dist/server.js

@@ -0,0 +1,743 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.server = void 0;
+exports.createSkedyulServer = createSkedyulServer;
+const http_1 = __importDefault(require("http"));
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const service_1 = require("./core/service");
+function normalizeBilling(billing) {
+    if (!billing || typeof billing.credits !== 'number') {
+        return { credits: 0 };
+    }
+    return billing;
+}
+function parseJsonRecord(value) {
+    if (!value) {
+        return {};
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return {};
+    }
+}
+function parseNumberEnv(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+function mergeRuntimeEnv() {
+    const bakedEnv = parseJsonRecord(process.env.MCP_ENV_JSON);
+    const runtimeEnv = parseJsonRecord(process.env.MCP_ENV);
+    const merged = { ...bakedEnv, ...runtimeEnv };
+    Object.assign(process.env, merged);
+}
+async function handleCoreMethod(method, params) {
+    const service = service_1.coreApiService.getService();
+    if (!service) {
+        return {
+            status: 404,
+            payload: { error: 'Core API service not configured' },
+        };
+    }
+    if (method === 'createCommunicationChannel') {
+        if (!params?.channel) {
+            return { status: 400, payload: { error: 'channel is required' } };
+        }
+        const channel = params.channel;
+        const result = await service_1.coreApiService.callCreateChannel(channel);
+        if (!result) {
+            return {
+                status: 500,
+                payload: { error: 'Core API service did not respond' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    if (method === 'updateCommunicationChannel') {
+        if (!params?.channel) {
+            return { status: 400, payload: { error: 'channel is required' } };
+        }
+        const channel = params.channel;
+        const result = await service_1.coreApiService.callUpdateChannel(channel);
+        if (!result) {
+            return {
+                status: 500,
+                payload: { error: 'Core API service did not respond' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    if (method === 'deleteCommunicationChannel') {
+        if (!params?.id || typeof params.id !== 'string') {
+            return { status: 400, payload: { error: 'id is required' } };
+        }
+        const result = await service_1.coreApiService.callDeleteChannel(params.id);
+        if (!result) {
+            return {
+                status: 500,
+                payload: { error: 'Core API service did not respond' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    if (method === 'getCommunicationChannel') {
+        if (!params?.id || typeof params.id !== 'string') {
+            return { status: 400, payload: { error: 'id is required' } };
+        }
+        const result = await service_1.coreApiService.callGetChannel(params.id);
+        if (!result) {
+            return {
+                status: 404,
+                payload: { error: 'Channel not found' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    if (method === 'getCommunicationChannels') {
+        const result = await service_1.coreApiService.callListChannels();
+        if (!result) {
+            return {
+                status: 500,
+                payload: { error: 'Core API service did not respond' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    if (method === 'communicationChannel.list') {
+        const result = await service_1.coreApiService.callListChannels();
+        if (!result) {
+            return {
+                status: 500,
+                payload: { error: 'Core API service did not respond' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    if (method === 'communicationChannel.get') {
+        if (!params?.id || typeof params.id !== 'string') {
+            return { status: 400, payload: { error: 'id is required' } };
+        }
+        const result = await service_1.coreApiService.callGetChannel(params.id);
+        if (!result) {
+            return {
+                status: 404,
+                payload: { error: 'Channel not found' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    if (method === 'workplace.list') {
+        const result = await service_1.coreApiService.callListWorkplaces();
+        if (!result) {
+            return {
+                status: 500,
+                payload: { error: 'Core API service did not respond' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    if (method === 'workplace.get') {
+        if (!params?.id || typeof params.id !== 'string') {
+            return { status: 400, payload: { error: 'id is required' } };
+        }
+        const result = await service_1.coreApiService.callGetWorkplace(params.id);
+        if (!result) {
+            return {
+                status: 404,
+                payload: { error: 'Workplace not found' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    if (method === 'sendMessage') {
+        if (!params?.message || !params?.communicationChannel) {
+            return { status: 400, payload: { error: 'message and communicationChannel are required' } };
+        }
+        const msg = params.message;
+        const channel = params.communicationChannel;
+        const result = await service_1.coreApiService.callSendMessage({
+            message: msg,
+            communicationChannel: channel,
+        });
+        if (!result) {
+            return {
+                status: 500,
+                payload: { error: 'Core API service did not respond' },
+            };
+        }
+        return { status: 200, payload: result };
+    }
+    return {
+        status: 400,
+        payload: { error: 'Unknown core method' },
+    };
+}
+function buildToolMetadata(registry) {
+    return Object.keys(registry).map((name) => ({
+        name,
+        description: `Function: ${name}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                inputs: {
+                    type: 'object',
+                    description: 'Input parameters for the function',
+                },
+            },
+            required: ['inputs'],
+        },
+    }));
+}
+function createRequestState(maxRequests, ttlExtendSeconds, runtimeLabel, toolNames) {
+    let requestCount = 0;
+    let lastRequestTime = Date.now();
+    return {
+        incrementRequestCount() {
+            requestCount += 1;
+            lastRequestTime = Date.now();
+        },
+        shouldShutdown() {
+            return maxRequests !== null && requestCount >= maxRequests;
+        },
+        getHealthStatus() {
+            return {
+                status: 'running',
+                requests: requestCount,
+                maxRequests,
+                requestsRemaining: maxRequests !== null ? Math.max(0, maxRequests - requestCount) : null,
+                lastRequestTime,
+                ttlExtendSeconds,
+                runtime: runtimeLabel,
+                tools: [...toolNames],
+            };
+        },
+    };
+}
+function createCallToolHandler(registry, state, onMaxRequests) {
+    return async function callTool(nameRaw, argsRaw) {
+        const toolName = String(nameRaw);
+        const fn = registry[toolName];
+        if (!fn) {
+            throw new Error(`Tool "${toolName}" not found in registry`);
+        }
+        if (typeof fn !== 'function') {
+            throw new Error(`Registry entry "${toolName}" is not a function`);
+        }
+        const args = (argsRaw ?? {});
+        const estimateMode = args.estimate === true;
+        if (!estimateMode) {
+            state.incrementRequestCount();
+            if (state.shouldShutdown()) {
+                onMaxRequests?.();
+            }
+        }
+        const requestEnv = args.env ?? {};
+        const originalEnv = { ...process.env };
+        Object.assign(process.env, requestEnv);
+        try {
+            const inputs = args.inputs ?? {};
+            const functionResult = await fn({
+                input: inputs,
+                context: {
+                    env: process.env,
+                    mode: estimateMode ? 'estimate' : 'execute',
+                },
+            });
+            const billing = normalizeBilling(functionResult.billing);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(functionResult.output),
+                    },
+                ],
+                billing,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error ?? ''),
+                        }),
+                    },
+                ],
+                billing: { credits: 0 },
+                isError: true,
+            };
+        }
+        finally {
+            process.env = originalEnv;
+        }
+    };
+}
+function parseJSONBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.on('data', (chunk) => {
+            body += chunk.toString();
+        });
+        req.on('end', () => {
+            try {
+                resolve(body ? JSON.parse(body) : {});
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        req.on('error', reject);
+    });
+}
+function sendJSON(res, statusCode, data) {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data));
+}
+function getDefaultHeaders(options) {
+    return {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': options?.allowOrigin ?? '*',
+        'Access-Control-Allow-Methods': options?.allowMethods ?? 'GET, POST, OPTIONS',
+        'Access-Control-Allow-Headers': options?.allowHeaders ?? 'Content-Type',
+    };
+}
+function createResponse(statusCode, body, headers) {
+    return {
+        statusCode,
+        headers,
+        body: JSON.stringify(body),
+    };
+}
+function getListeningPort(config) {
+    const envPort = Number.parseInt(process.env.PORT ?? '', 10);
+    if (!Number.isNaN(envPort)) {
+        return envPort;
+    }
+    return config.defaultPort ?? 3000;
+}
+function createSkedyulServer(config, registry) {
+    mergeRuntimeEnv();
+    if (config.coreApi?.service) {
+        service_1.coreApiService.register(config.coreApi.service);
+        if (config.coreApi.webhookHandler) {
+            service_1.coreApiService.setWebhookHandler(config.coreApi.webhookHandler);
+        }
+    }
+    const tools = buildToolMetadata(registry);
+    const toolNames = tools.map((tool) => tool.name);
+    const runtimeLabel = config.computeLayer;
+    const maxRequests = config.maxRequests ??
+        parseNumberEnv(process.env.MCP_MAX_REQUESTS) ??
+        null;
+    const ttlExtendSeconds = config.ttlExtendSeconds ??
+        parseNumberEnv(process.env.MCP_TTL_EXTEND) ??
+        3600;
+    const state = createRequestState(maxRequests, ttlExtendSeconds, runtimeLabel, toolNames);
+    const server = new index_js_1.Server({
+        name: config.metadata.name,
+        version: config.metadata.version,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    const dedicatedShutdown = () => {
+        // eslint-disable-next-line no-console
+        console.log('Max requests reached, shutting down...');
+        setTimeout(() => process.exit(0), 1000);
+    };
+    const callTool = createCallToolHandler(registry, state, config.computeLayer === 'dedicated' ? dedicatedShutdown : undefined);
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+        tools,
+    }));
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => callTool(request.params.name, request.params.arguments));
+    if (config.computeLayer === 'dedicated') {
+        return createDedicatedServerInstance(config, tools, callTool, state);
+    }
+    return createServerlessInstance(config, tools, callTool, state);
+}
+function createDedicatedServerInstance(config, tools, callTool, state) {
+    const port = getListeningPort(config);
+    const httpServer = http_1.default.createServer(async (req, res) => {
+        function sendCoreResult(result) {
+            sendJSON(res, result.status, result.payload);
+        }
+        try {
+            const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+            const pathname = url.pathname;
+            if (pathname === '/health' && req.method === 'GET') {
+                sendJSON(res, 200, state.getHealthStatus());
+                return;
+            }
+            if (pathname === '/estimate' && req.method === 'POST') {
+                let estimateBody;
+                try {
+                    estimateBody = (await parseJSONBody(req));
+                }
+                catch {
+                    sendJSON(res, 400, {
+                        error: {
+                            code: -32700,
+                            message: 'Parse error',
+                        },
+                    });
+                    return;
+                }
+                try {
+                    const estimateResponse = await callTool(estimateBody.name, {
+                        inputs: estimateBody.inputs,
+                        estimate: true,
+                    });
+                    sendJSON(res, 200, {
+                        billing: estimateResponse.billing ?? { credits: 0 },
+                    });
+                }
+                catch (err) {
+                    sendJSON(res, 500, {
+                        error: {
+                            code: -32603,
+                            message: err instanceof Error ? err.message : String(err ?? ''),
+                        },
+                    });
+                }
+                return;
+            }
+            if (pathname === '/core' && req.method === 'POST') {
+                let coreBody;
+                try {
+                    coreBody = (await parseJSONBody(req));
+                }
+                catch {
+                    sendJSON(res, 400, {
+                        error: {
+                            code: -32700,
+                            message: 'Parse error',
+                        },
+                    });
+                    return;
+                }
+                if (!coreBody?.method) {
+                    sendJSON(res, 400, {
+                        error: {
+                            code: -32602,
+                            message: 'Missing method',
+                        },
+                    });
+                    return;
+                }
+                const method = coreBody.method;
+                const result = await handleCoreMethod(method, coreBody.params);
+                sendCoreResult(result);
+                return;
+            }
+            if (pathname === '/core/webhook' && req.method === 'POST') {
+                let webhookBody = undefined;
+                try {
+                    webhookBody = (await parseJSONBody(req));
+                }
+                catch {
+                    sendJSON(res, 400, { status: 'parse-error' });
+                    return;
+                }
+                const webhookRequest = {
+                    method: req.method,
+                    headers: Object.fromEntries(Object.entries(req.headers).map(([key, value]) => [
+                        key,
+                        typeof value === 'string' ? value : value?.[0] ?? '',
+                    ])),
+                    body: webhookBody,
+                    query: Object.fromEntries(url.searchParams.entries()),
+                };
+                const webhookResponse = await service_1.coreApiService.dispatchWebhook(webhookRequest);
+                res.writeHead(webhookResponse.status, {
+                    'Content-Type': 'application/json',
+                });
+                res.end(JSON.stringify(webhookResponse.body ?? {}));
+                return;
+            }
+            if (pathname === '/mcp' && req.method === 'POST') {
+                let body;
+                try {
+                    body = (await parseJSONBody(req));
+                }
+                catch {
+                    sendJSON(res, 400, {
+                        jsonrpc: '2.0',
+                        id: null,
+                        error: {
+                            code: -32700,
+                            message: 'Parse error',
+                        },
+                    });
+                    return;
+                }
+                try {
+                    const { jsonrpc, id, method, params } = body;
+                    if (jsonrpc !== '2.0') {
+                        sendJSON(res, 400, {
+                            jsonrpc: '2.0',
+                            id,
+                            error: {
+                                code: -32600,
+                                message: 'Invalid Request',
+                            },
+                        });
+                        return;
+                    }
+                    let result;
+                    if (method === 'tools/list') {
+                        result = { tools };
+                    }
+                    else if (method === 'tools/call') {
+                        result = await callTool(params?.name, params?.arguments);
+                    }
+                    else {
+                        sendJSON(res, 200, {
+                            jsonrpc: '2.0',
+                            id,
+                            error: {
+                                code: -32601,
+                                message: `Method not found: ${method}`,
+                            },
+                        });
+                        return;
+                    }
+                    sendJSON(res, 200, {
+                        jsonrpc: '2.0',
+                        id,
+                        result,
+                    });
+                }
+                catch (err) {
+                    sendJSON(res, 500, {
+                        jsonrpc: '2.0',
+                        id: body?.id ?? null,
+                        error: {
+                            code: -32603,
+                            message: err instanceof Error ? err.message : String(err ?? ''),
+                        },
+                    });
+                }
+                return;
+            }
+            sendJSON(res, 404, {
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32601,
+                    message: 'Not Found',
+                },
+            });
+        }
+        catch (err) {
+            sendJSON(res, 500, {
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32603,
+                    message: err instanceof Error ? err.message : String(err ?? ''),
+                },
+            });
+        }
+    });
+    return {
+        async listen(listenPort) {
+            const finalPort = listenPort ?? port;
+            return new Promise((resolve, reject) => {
+                httpServer.listen(finalPort, () => {
+                    // eslint-disable-next-line no-console
+                    console.log(`MCP Server running on port ${finalPort}`);
+                    // eslint-disable-next-line no-console
+                    console.log(`Registry loaded with ${tools.length} tools: ${tools
+                        .map((tool) => tool.name)
+                        .join(', ')}`);
+                    resolve();
+                });
+                httpServer.once('error', reject);
+            });
+        },
+        getHealthStatus: () => state.getHealthStatus(),
+    };
+}
+function createServerlessInstance(config, tools, callTool, state) {
+    const headers = getDefaultHeaders(config.cors);
+    return {
+        async handler(event) {
+            try {
+                const path = event.path;
+                const method = event.httpMethod;
+                if (method === 'OPTIONS') {
+                    return createResponse(200, { message: 'OK' }, headers);
+                }
+                if (path === '/core' && method === 'POST') {
+                    let coreBody;
+                    try {
+                        coreBody = event.body ? JSON.parse(event.body) : {};
+                    }
+                    catch {
+                        return createResponse(400, {
+                            error: {
+                                code: -32700,
+                                message: 'Parse error',
+                            },
+                        }, headers);
+                    }
+                    if (!coreBody?.method) {
+                        return createResponse(400, {
+                            error: {
+                                code: -32602,
+                                message: 'Missing method',
+                            },
+                        }, headers);
+                    }
+                    const method = coreBody.method;
+                    const result = await handleCoreMethod(method, coreBody.params);
+                    return createResponse(result.status, result.payload, headers);
+                }
+                if (path === '/core/webhook' && method === 'POST') {
+                    let webhookBody = undefined;
+                    try {
+                        webhookBody = event.body ? JSON.parse(event.body) : {};
+                    }
+                    catch {
+                        return createResponse(400, { status: 'parse-error' }, headers);
+                    }
+                    const webhookRequest = {
+                        method,
+                        headers: event.headers ?? {},
+                        body: webhookBody,
+                        query: event.queryStringParameters ?? {},
+                    };
+                    const webhookResponse = await service_1.coreApiService.dispatchWebhook(webhookRequest);
+                    return createResponse(webhookResponse.status, webhookResponse.body ?? {}, headers);
+                }
+                if (path === '/estimate' && method === 'POST') {
+                    let estimateBody;
+                    try {
+                        estimateBody = event.body ? JSON.parse(event.body) : {};
+                    }
+                    catch {
+                        return createResponse(400, {
+                            error: {
+                                code: -32700,
+                                message: 'Parse error',
+                            },
+                        }, headers);
+                    }
+                    try {
+                        const estimateResponse = await callTool(estimateBody.name, {
+                            inputs: estimateBody.inputs,
+                            estimate: true,
+                        });
+                        return createResponse(200, {
+                            billing: estimateResponse.billing ?? { credits: 0 },
+                        }, headers);
+                    }
+                    catch (err) {
+                        return createResponse(500, {
+                            error: {
+                                code: -32603,
+                                message: err instanceof Error ? err.message : String(err ?? ''),
+                            },
+                        }, headers);
+                    }
+                }
+                if (path === '/health' && method === 'GET') {
+                    return createResponse(200, state.getHealthStatus(), headers);
+                }
+                if (path === '/mcp' && method === 'POST') {
+                    let body;
+                    try {
+                        body = event.body ? JSON.parse(event.body) : {};
+                    }
+                    catch {
+                        return createResponse(400, {
+                            jsonrpc: '2.0',
+                            id: null,
+                            error: {
+                                code: -32700,
+                                message: 'Parse error',
+                            },
+                        }, headers);
+                    }
+                    try {
+                        const { jsonrpc, id, method: rpcMethod, params } = body;
+                        if (jsonrpc !== '2.0') {
+                            return createResponse(400, {
+                                jsonrpc: '2.0',
+                                id,
+                                error: {
+                                    code: -32600,
+                                    message: 'Invalid Request',
+                                },
+                            }, headers);
+                        }
+                        let result;
+                        if (rpcMethod === 'tools/list') {
+                            result = { tools };
+                        }
+                        else if (rpcMethod === 'tools/call') {
+                            result = await callTool(params?.name, params?.arguments);
+                        }
+                        else {
+                            return createResponse(200, {
+                                jsonrpc: '2.0',
+                                id,
+                                error: {
+                                    code: -32601,
+                                    message: `Method not found: ${rpcMethod}`,
+                                },
+                            }, headers);
+                        }
+                        return createResponse(200, {
+                            jsonrpc: '2.0',
+                            id,
+                            result,
+                        }, headers);
+                    }
+                    catch (err) {
+                        return createResponse(500, {
+                            jsonrpc: '2.0',
+                            id: body?.id ?? null,
+                            error: {
+                                code: -32603,
+                                message: err instanceof Error ? err.message : String(err ?? ''),
+                            },
+                        }, headers);
+                    }
+                }
+                return createResponse(404, {
+                    jsonrpc: '2.0',
+                    id: null,
+                    error: {
+                        code: -32601,
+                        message: 'Not Found',
+                    },
+                }, headers);
+            }
+            catch (err) {
+                return createResponse(500, {
+                    jsonrpc: '2.0',
+                    id: null,
+                    error: {
+                        code: -32603,
+                        message: err instanceof Error ? err.message : String(err ?? ''),
+                    },
+                }, headers);
+            }
+        },
+        getHealthStatus: () => state.getHealthStatus(),
+    };
+}
+exports.server = {
+    create: createSkedyulServer,
+};

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+import type { CoreApiConfig } from './core/types';
+export interface ToolContext {
+    env: Record<string, string | undefined>;
+    mode?: 'execute' | 'estimate';
+}
+export interface ToolParams<Input, Output> {
+    input: Input;
+    context: ToolContext;
+}
+export interface BillingInfo {
+    credits: number;
+}
+export interface ToolExecutionResult<Output = unknown> {
+    output: Output;
+    billing: BillingInfo;
+}
+export type ToolHandler<Input, Output> = (params: ToolParams<Input, Output>) => Promise<ToolExecutionResult<Output>> | ToolExecutionResult<Output>;
+export type ToolRegistry = Record<string, ToolHandler<unknown, unknown>>;
+export type ToolName<T extends ToolRegistry> = Extract<keyof T, string>;
+export interface ToolMetadata {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: {
+            inputs: {
+                type: 'object';
+                description: string;
+            };
+        };
+        required: ['inputs'];
+    };
+}
+export interface HealthStatus {
+    status: 'running';
+    requests: number;
+    maxRequests: number | null;
+    requestsRemaining: number | null;
+    lastRequestTime: number;
+    ttlExtendSeconds: number;
+    runtime: string;
+    tools: string[];
+}
+export type ComputeLayer = 'dedicated' | 'serverless';
+export interface ServerMetadata {
+    name: string;
+    version: string;
+}
+export interface CorsOptions {
+    allowOrigin?: string;
+    allowMethods?: string;
+    allowHeaders?: string;
+}
+export interface SkedyulServerConfig {
+    computeLayer: ComputeLayer;
+    metadata: ServerMetadata;
+    defaultPort?: number;
+    maxRequests?: number | null;
+    ttlExtendSeconds?: number;
+    cors?: CorsOptions;
+    coreApi?: CoreApiConfig;
+}
+export interface APIGatewayProxyEvent {
+    body: string | null;
+    headers: Record<string, string>;
+    httpMethod: string;
+    path: string;
+    queryStringParameters: Record<string, string> | null;
+    requestContext: {
+        requestId: string;
+    };
+}
+export interface APIGatewayProxyResult {
+    statusCode: number;
+    headers?: Record<string, string>;
+    body: string;
+}
+export interface ToolCallResponse {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    billing?: BillingInfo;
+    isError?: boolean;
+}
+export interface DedicatedServerInstance {
+    listen(port?: number): Promise<void>;
+    getHealthStatus(): HealthStatus;
+}
+export interface ServerlessServerInstance {
+    handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult>;
+    getHealthStatus(): HealthStatus;
+}
+export type SkedyulServerInstance = DedicatedServerInstance | ServerlessServerInstance;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "skedyul",
+  "version": "0.1.0",
+  "description": "The Skedyul SDK for Node.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc --build tsconfig.json",
+    "test": "npm run build && node --test tests/server.test.js"
+  },
+  "keywords": ["mcp", "skedyul", "serverless", "node", "typescript"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skedyul/skedyul-node"
+  },
+  "author": "Skedyul <support@skedyul.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.5.0"
+  }
+}
+