feat: adding umaaas mcp server

.gitignore

@@ -1,6 +1,9 @@
 # Dependencies
 node_modules/
 
+# Build output
+dist/
+
 # Logs
 logs
 *.log

mcp-server/Dockerfile

@@ -0,0 +1,78 @@
+# Dockerfile for Umaaas MCP Server
+#
+# This Dockerfile builds a Docker image for the MCP Server.
+#
+# To build the image locally:
+#   docker build -f packages/mcp-server/Dockerfile -t umaaas_mcp:local .
+#
+# To run the image:
+#   docker run -i umaaas_mcp:local [OPTIONS]
+#
+# Common options:
+#   --tool=<name>              Include specific tools
+#   --resource=<name>          Include tools for specific resources
+#   --operation=read|write     Filter by operation type
+#   --client=<type>            Set client compatibility (e.g., claude, cursor)
+#   --transport=<type>         Set transport type (stdio or http)
+#
+# For a full list of options:
+#   docker run -i umaaas_mcp:local --help
+#
+# Note: The MCP server uses stdio transport by default. Docker's -i flag
+# enables interactive mode, allowing the container to communicate over stdin/stdout.
+
+# Build stage
+FROM node:24-alpine AS builder
+
+# Install bash for build script
+RUN apk add --no-cache bash openssl
+
+# Set working directory
+WORKDIR /build
+
+# Copy entire repository
+COPY . .
+
+# Install all dependencies and build everything
+RUN yarn install --frozen-lockfile && \
+    yarn build && \
+    # Remove the symlink to the SDK so it doesn't interfere with the explicit COPY below
+    rm -Rf packages/mcp-server/node_modules/umaaas
+
+FROM denoland/deno:alpine-2.7.1
+
+# Install node and npm
+RUN apk add --no-cache nodejs npm
+
+ENV LD_LIBRARY_PATH=/usr/lib:/usr/local/lib
+
+# Add non-root user
+RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
+
+# Set working directory
+WORKDIR /app
+
+# Copy the built mcp-server dist directory
+COPY --from=builder /build/packages/mcp-server/dist ./
+
+# Copy node_modules from mcp-server (includes all production deps)
+COPY --from=builder /build/packages/mcp-server/node_modules ./node_modules
+
+# Copy the built umaaas into node_modules
+COPY --from=builder /build/dist ./node_modules/umaaas
+
+# Change ownership to nodejs user
+RUN chown -R nodejs:nodejs /app
+RUN chown -R nodejs:nodejs /deno-dir
+
+# Switch to non-root user
+USER nodejs
+
+# The MCP server uses stdio transport by default
+# No exposed ports needed for stdio communication
+
+# Set the entrypoint to the MCP server
+ENTRYPOINT ["node", "index.js"]
+
+# Allow passing arguments to the MCP server
+CMD []

mcp-server/README.md

@@ -0,0 +1,96 @@
+# Umaaas TypeScript MCP Server
+
+It is generated with [Stainless](https://www.stainless.com/).
+
+## Installation
+
+### Building
+
+Because it's not published yet, clone the repo and build it:
+
+```sh
+git clone git@github.com:stainless-sdks/umaaas-typescript.git
+cd umaaas-typescript
+./scripts/bootstrap
+./scripts/build
+```
+
+### Running
+
+```sh
+# set env vars as needed
+export UMAAAS_CLIENT_ID="My Username"
+export UMAAAS_CLIENT_SECRET="My Password"
+node ./packages/mcp-server/dist/index.js
+```
+
+> [!NOTE]
+> Once this package is [published to npm](https://www.stainless.com/docs/guides/publish), this will become: `npx -y umaaas_mcp`
+
+### Via MCP Client
+
+[Build the project](#building) as mentioned above.
+
+There is a partial list of existing clients at [modelcontextprotocol.io](https://modelcontextprotocol.io/clients). If you already
+have a client, consult their documentation to install the MCP server.
+
+For clients with a configuration JSON, it might look something like this:
+
+```json
+{
+  "mcpServers": {
+    "umaaas_api": {
+      "command": "node",
+      "args": ["/path/to/local/umaaas-typescript/packages/mcp-server"],
+      "env": {
+        "UMAAAS_CLIENT_ID": "My Username",
+        "UMAAAS_CLIENT_SECRET": "My Password"
+      }
+    }
+  }
+}
+```
+
+## Code Mode
+
+This MCP server is built on the "Code Mode" tool scheme. In this MCP Server,
+your agent will write code against the TypeScript SDK, which will then be executed in an
+isolated sandbox. To accomplish this, the server will expose two tools to your agent:
+
+- The first tool is a docs search tool, which can be used to generically query for
+  documentation about your API/SDK.
+
+- The second tool is a code tool, where the agent can write code against the TypeScript SDK.
+  The code will be executed in a sandbox environment without web or filesystem access. Then,
+  anything the code returns or prints will be returned to the agent as the result of the
+  tool call.
+
+Using this scheme, agents are capable of performing very complex tasks deterministically
+and repeatably.
+
+## Running remotely
+
+Launching the client with `--transport=http` launches the server as a remote server using Streamable HTTP transport. The `--port` setting can choose the port it will run on, and the `--socket` setting allows it to run on a Unix socket.
+
+Authorization can be provided via the `Authorization` header using the Basic scheme.
+
+Additionally, authorization can be provided via the following headers:
+| Header | Equivalent client option | Security scheme |
+| ------------------------ | ------------------------ | --------------- |
+| `x-umaaas-client-id` | `username` | BasicAuth |
+| `x-umaaas-client-secret` | `password` | BasicAuth |
+
+A configuration JSON for this server might look like this, assuming the server is hosted at `http://localhost:3000`:
+
+```json
+{
+  "mcpServers": {
+    "umaaas_api": {
+      "url": "http://localhost:3000",
+      "headers": {
+        "Authorization": "Basic <auth value>"
+      }
+    }
+  }
+}
+```

mcp-server/build

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -exuo pipefail
+
+rm -rf dist; mkdir dist
+
+# Copy src to dist/src and build from dist/src into dist, so that
+# the source map for index.js.map will refer to ./src/index.ts etc
+cp -rp src README.md dist
+
+for file in LICENSE; do
+  if [ -e "../../${file}" ]; then cp "../../${file}" dist; fi
+done
+
+for file in CHANGELOG.md; do
+  if [ -e "${file}" ]; then cp "${file}" dist; fi
+done
+
+# this converts the export map paths for the dist directory
+# and does a few other minor things
+PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist/package.json
+
+# updates the `umaaas` dependency to point to NPM
+node scripts/postprocess-dist-package-json.cjs
+
+# build to .js/.mjs/.d.ts files
+./node_modules/.bin/tsc-multi
+
+cp tsconfig.dist-src.json dist/src/tsconfig.json
+
+chmod +x dist/index.js
+
+DIST_PATH=./dist PKG_IMPORT_PATH=umaaas_mcp/ node ../../scripts/utils/postprocess-files.cjs
+
+# mcp bundle
+rm -rf dist-bundle umaaas_api.mcpb; mkdir dist-bundle
+
+# copy package.json
+PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist-bundle/package.json
+
+# copy files
+node scripts/copy-bundle-files.cjs
+
+# install runtime deps
+cd dist-bundle
+npm install
+cd ..
+
+# pack bundle
+cp manifest.json dist-bundle
+
+npx mcpb pack dist-bundle umaaas_api.mcpb
+
+npx mcpb sign umaaas_api.mcpb --self-signed
+
+# clean up
+rm -rf dist-bundle

mcp-server/jest.config.ts

@@ -0,0 +1,17 @@
+import type { JestConfigWithTsJest } from 'ts-jest';
+
+const config: JestConfigWithTsJest = {
+  preset: 'ts-jest/presets/default-esm',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.(t|j)sx?$': ['@swc/jest', { sourceMaps: 'inline' }],
+  },
+  moduleNameMapper: {
+    '^umaaas_mcp$': '<rootDir>/src/index.ts',
+    '^umaaas_mcp/(.*)$': '<rootDir>/src/$1',
+  },
+  modulePathIgnorePatterns: ['<rootDir>/dist/'],
+  testPathIgnorePatterns: ['scripts'],
+};
+
+export default config;

mcp-server/manifest.json

@@ -0,0 +1,54 @@
+{
+  "dxt_version": "0.2",
+  "name": "umaaas_mcp",
+  "version": "0.0.1-alpha.0",
+  "description": "The official MCP Server for the Umaaas API",
+  "author": {
+    "name": "Umaaas",
+    "email": "support@lightspark.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stainless-sdks/umaaas-typescript.git"
+  },
+  "homepage": "https://github.com/stainless-sdks/umaaas-typescript/tree/main/packages/mcp-server#readme",
+  "documentation": "https://lightsparkdev.github.io/umaaas-api/",
+  "server": {
+    "type": "node",
+    "entry_point": "index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/index.js"
+      ],
+      "env": {
+        "UMAAAS_CLIENT_ID": "${user_config.UMAAAS_CLIENT_ID}",
+        "UMAAAS_CLIENT_SECRET": "${user_config.UMAAAS_CLIENT_SECRET}"
+      }
+    }
+  },
+  "user_config": {
+    "UMAAAS_CLIENT_ID": {
+      "title": "username",
+      "description": "API token authentication using format `<api token id>:<api client secret>`",
+      "required": true,
+      "type": "string"
+    },
+    "UMAAAS_CLIENT_SECRET": {
+      "title": "password",
+      "description": "API token authentication using format `<api token id>:<api client secret>`",
+      "required": true,
+      "type": "string"
+    }
+  },
+  "tools": [],
+  "tools_generated": true,
+  "compatibility": {
+    "runtimes": {
+      "node": ">=18.0.0"
+    }
+  },
+  "keywords": [
+    "api"
+  ]
+}