open-mcp-app 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,36 @@
+# open-mcp-app
+
+A small Node.js SDK skeleton for working with open MCP apps.
+
+This package is intentionally lightweight: it includes a generic HTTP `request` primitive and a few convenience methods that demonstrate typical SDK call shapes against an "open apps" API surface.
+
+## Install
+
+```bash
+npm install open-mcp-app
+```
+
+## Usage
+
+```js
+const { createMcpAppsClient } = require('open-mcp-app');
+
+const client = createMcpAppsClient({
+  baseUrl: 'https://api.example.com',
+});
+
+async function main() {
+  const apps = await client.listApps({});
+  console.log(apps);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});
+```
+
+## License
+
+MIT
+

package/index.js

@@ -0,0 +1,363 @@
+'use strict';
+
+/**
+ * Ensures a value is a non-empty string so that the SDK fails fast with a
+ * consistent error message. This keeps downstream network errors from masking
+ * configuration mistakes and makes SDK usage easier to debug.
+ *
+ * @param {Object} args
+ * @param {unknown} args.value
+ * @param {string} args.name
+ * @returns {string}
+ */
+const assertNonEmptyString = ({ value, name } = {}) => {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new McpAppsSdkError({
+      message: `${name} must be a non-empty string.`,
+      code: 'MCP_APPS_INVALID_ARGUMENT',
+    });
+  }
+
+  return value;
+};
+
+/**
+ * Normalizes a base URL by removing trailing slashes so that URL construction is
+ * predictable. This avoids subtle double-slash URLs when callers pass a base
+ * URL like "https://api.example.com/".
+ *
+ * @param {Object} args
+ * @param {string} args.baseUrl
+ * @returns {string}
+ */
+const normalizeBaseUrl = ({ baseUrl } = {}) => {
+  const url = assertNonEmptyString({ value: baseUrl, name: 'baseUrl' });
+  return url.replace(/\/+$/, '');
+};
+
+/**
+ * Builds a request URL from a base URL, a path, and an optional query object.
+ * Centralizing URL construction ensures consistent encoding rules across the
+ * SDK and reduces the chance of introducing subtle request bugs.
+ *
+ * @param {Object} args
+ * @param {string} args.baseUrl
+ * @param {string} args.path
+ * @param {Object<string, string | number | boolean | null | undefined>} [args.query]
+ * @returns {string}
+ */
+const buildUrl = ({ baseUrl, path, query } = {}) => {
+  const normalizedBaseUrl = normalizeBaseUrl({ baseUrl });
+  const normalizedPath = assertNonEmptyString({ value: path, name: 'path' }).startsWith('/')
+    ? path
+    : `/${path}`;
+
+  const url = new URL(`${normalizedBaseUrl}${normalizedPath}`);
+
+  if (query && typeof query === 'object') {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null) continue;
+      url.searchParams.set(key, String(value));
+    }
+  }
+
+  return url.toString();
+};
+
+/**
+ * A base error type for the SDK so that callers can reliably distinguish
+ * expected SDK failures from other runtime errors.
+ */
+class McpAppsSdkError extends Error {
+  /**
+   * Creates a new SDK error instance.
+   *
+   * @param {Object} args
+   * @param {string} args.message
+   * @param {string} [args.code]
+   * @param {unknown} [args.cause]
+   */
+  constructor({ message, code, cause } = {}) {
+    super(message);
+    this.name = 'McpAppsSdkError';
+    this.code = code || 'MCP_APPS_SDK_ERROR';
+
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+}
+
+/**
+ * An error thrown when an HTTP request completes but returns an unsuccessful
+ * status code. Surfacing the URL, method, status, and response body makes it
+ * straightforward to debug API failures without requiring extra logging.
+ */
+class McpAppsRequestError extends McpAppsSdkError {
+  /**
+   * Creates a request error for a failed HTTP response.
+   *
+   * @param {Object} args
+   * @param {string} args.message
+   * @param {string} args.method
+   * @param {string} args.url
+   * @param {number} args.status
+   * @param {unknown} [args.body]
+   */
+  constructor({ message, method, url, status, body } = {}) {
+    super({ message, code: 'MCP_APPS_REQUEST_FAILED' });
+    this.name = 'McpAppsRequestError';
+    this.method = method;
+    this.url = url;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * Creates a new `McpAppsClient` instance.
+ *
+ * This factory exists so consumers can create clients without `new`, which is
+ * a common ergonomic pattern for SDKs and helps keep usage consistent across
+ * codebases.
+ *
+ * @param {Object} args
+ * @param {string} args.baseUrl
+ * @param {string} [args.apiKey]
+ * @param {(input: string, init?: Object) => Promise<Response>} [args.fetchFn]
+ * @param {string} [args.userAgent]
+ * @returns {McpAppsClient}
+ */
+const createMcpAppsClient = ({ baseUrl, apiKey, fetchFn, userAgent } = {}) =>
+  new McpAppsClient({ baseUrl, apiKey, fetchFn, userAgent });
+
+/**
+ * A small, opinionated client that demonstrates the shape of an open MCP Apps SDK.
+ *
+ * The class stays intentionally lightweight: it provides a generic `request`
+ * primitive plus a few convenience methods that map to typical discovery and
+ * invocation workflows. The goal is to provide stable call signatures and
+ * error shapes even while the backing API evolves.
+ */
+class McpAppsClient {
+  /**
+   * Creates a new client instance.
+   *
+   * @param {Object} args
+   * @param {string} args.baseUrl
+   * @param {string} [args.apiKey]
+   * @param {(input: string, init?: Object) => Promise<Response>} [args.fetchFn]
+   * @param {string} [args.userAgent]
+   */
+  constructor({ baseUrl, apiKey, fetchFn, userAgent } = {}) {
+    this._baseUrl = normalizeBaseUrl({ baseUrl });
+    this._apiKey = apiKey;
+    this._fetchFn = fetchFn;
+    this._userAgent = userAgent;
+  }
+
+  /**
+   * Updates client configuration at runtime.
+   *
+   * This exists so applications can construct a client early and later inject
+   * credentials or a custom fetch implementation without needing to pass the
+   * client instance through additional layers.
+   *
+   * @param {Object} args
+   * @param {string} [args.baseUrl]
+   * @param {string} [args.apiKey]
+   * @param {(input: string, init?: Object) => Promise<Response>} [args.fetchFn]
+   * @param {string} [args.userAgent]
+   * @returns {void}
+   */
+  configure = ({ baseUrl, apiKey, fetchFn, userAgent } = {}) => {
+    if (baseUrl !== undefined) this._baseUrl = normalizeBaseUrl({ baseUrl });
+    if (apiKey !== undefined) this._apiKey = apiKey;
+    if (fetchFn !== undefined) this._fetchFn = fetchFn;
+    if (userAgent !== undefined) this._userAgent = userAgent;
+  };
+
+  /**
+   * Issues an HTTP request and returns the parsed response body.
+   *
+   * The method is designed to be the lowest-level primitive in this SDK:
+   * higher-level helpers call into `request` so that retry, logging, custom
+   * headers, and transport behaviors can be added in one place.
+   *
+   * @param {Object} args
+   * @param {string} [args.method]
+   * @param {string} args.path
+   * @param {Object<string, string | number | boolean | null | undefined>} [args.query]
+   * @param {Object<string, string>} [args.headers]
+   * @param {unknown} [args.body]
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<unknown>}
+   */
+  request = async ({ method, path, query, headers, body, signal } = {}) => {
+    const url = buildUrl({ baseUrl: this._baseUrl, path, query });
+
+    const fetchFn = this._fetchFn || globalThis.fetch;
+    if (typeof fetchFn !== 'function') {
+      throw new McpAppsSdkError({
+        message:
+          'No fetch implementation is available. Provide fetchFn or use Node.js 18+ where fetch is built in.',
+        code: 'MCP_APPS_MISSING_FETCH',
+      });
+    }
+
+    const normalizedMethod = (method || 'GET').toUpperCase();
+
+    const requestHeaders = {
+      ...(headers || {}),
+    };
+
+    if (this._userAgent && !requestHeaders['user-agent'] && !requestHeaders['User-Agent']) {
+      requestHeaders['user-agent'] = this._userAgent;
+    }
+
+    if (this._apiKey && !requestHeaders.authorization && !requestHeaders.Authorization) {
+      requestHeaders.authorization = `Bearer ${this._apiKey}`;
+    }
+
+    /** @type {Object} */
+    const init = { method: normalizedMethod, headers: requestHeaders, signal };
+
+    if (body !== undefined) {
+      if (!requestHeaders['content-type'] && !requestHeaders['Content-Type']) {
+        requestHeaders['content-type'] = 'application/json';
+      }
+
+      init.body =
+        typeof body === 'string' || Buffer.isBuffer(body) ? body : JSON.stringify(body);
+    }
+
+    const response = await fetchFn(url, init);
+
+    const contentType = response.headers?.get?.('content-type') || '';
+    const isJson = contentType.toLowerCase().includes('application/json');
+
+    const responseBody = isJson
+      ? await response.json().catch(() => undefined)
+      : await response.text();
+
+    if (!response.ok) {
+      throw new McpAppsRequestError({
+        message: `Request failed with status ${response.status}.`,
+        method: normalizedMethod,
+        url,
+        status: response.status,
+        body: responseBody,
+      });
+    }
+
+    return responseBody;
+  };
+
+  /**
+   * Lists apps accessible to the current principal from the "open apps" surface.
+   *
+   * This method exists as a convenience helper for discovery flows. Routing
+   * through a dedicated open path keeps the intention clear for callers and
+   * allows backend policies to evolve independently from non-open app surfaces.
+   *
+   * @param {Object} args
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<unknown>}
+   */
+  listApps = async ({ signal } = {}) =>
+    this.request({ method: 'GET', path: '/open/apps', signal });
+
+  /**
+   * Fetches a single open app by id.
+   *
+   * Explicitly requiring `appId` keeps the call signature self-documenting and
+   * avoids ambiguous positional parameters.
+   *
+   * @param {Object} args
+   * @param {string} args.appId
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<unknown>}
+   */
+  getApp = async ({ appId, signal } = {}) => {
+    const id = assertNonEmptyString({ value: appId, name: 'appId' });
+    return this.request({ method: 'GET', path: `/open/apps/${encodeURIComponent(id)}`, signal });
+  };
+
+  /**
+   * Fetches an open app's manifest.
+   *
+   * Manifests are commonly used to describe capabilities (tools, input schema,
+   * output schema) without requiring execution. Exposing this as a separate
+   * call keeps discovery lightweight and avoids overloading `getApp`.
+   *
+   * @param {Object} args
+   * @param {string} args.appId
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<unknown>}
+   */
+  getAppManifest = async ({ appId, signal } = {}) => {
+    const id = assertNonEmptyString({ value: appId, name: 'appId' });
+    return this.request({
+      method: 'GET',
+      path: `/open/apps/${encodeURIComponent(id)}/manifest`,
+      signal,
+    });
+  };
+
+  /**
+   * Runs an open app with an input payload.
+   *
+   * Many MCP-style "apps" are orchestrations that accept structured input and
+   * return structured output. This method provides a stable entry point for
+   * that interaction while keeping transport details inside `request`.
+   *
+   * @param {Object} args
+   * @param {string} args.appId
+   * @param {unknown} [args.input]
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<unknown>}
+   */
+  runApp = async ({ appId, input, signal } = {}) => {
+    const id = assertNonEmptyString({ value: appId, name: 'appId' });
+    return this.request({
+      method: 'POST',
+      path: `/open/apps/${encodeURIComponent(id)}/run`,
+      body: { input },
+      signal,
+    });
+  };
+
+  /**
+   * Invokes a tool exposed by an open app.
+   *
+   * Tools are a core MCP primitive. This method intentionally accepts `args`
+   * as an object so that tool invocation stays forward-compatible when tool
+   * schemas evolve.
+   *
+   * @param {Object} args
+   * @param {string} args.appId
+   * @param {string} args.toolName
+   * @param {Object<string, unknown>} [args.args]
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<unknown>}
+   */
+  invokeTool = async ({ appId, toolName, args, signal } = {}) => {
+    const id = assertNonEmptyString({ value: appId, name: 'appId' });
+    const tool = assertNonEmptyString({ value: toolName, name: 'toolName' });
+
+    return this.request({
+      method: 'POST',
+      path: `/open/apps/${encodeURIComponent(id)}/tools/${encodeURIComponent(tool)}`,
+      body: { args: args || {} },
+      signal,
+    });
+  };
+}
+
+module.exports = {
+  McpAppsSdkError,
+  McpAppsRequestError,
+  McpAppsClient,
+  createMcpAppsClient,
+};
+

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "open-mcp-app",
+  "version": "0.1.0",
+  "description": "A small Node.js SDK skeleton for working with open MCP apps.",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node -e \"require('./index.js')\"",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sdk",
+    "apps",
+    "open"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}