@ampless/mcp-server 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ampless contributors
+
+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,145 @@
+# @ampless/mcp-server
+
+MCP (Model Context Protocol) server for [ampless](https://github.com/heavymoons/ampless). Lets AI agents — Claude Desktop, Cursor, Claude Code, and anything else that speaks MCP — read and write posts and upload media on your CMS instance.
+
+> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_posts` | List posts with optional `status` filter and pagination |
+| `get_post` | Fetch a single post by `slug` or `postId` |
+| `create_post` | Create a new post (draft or published) |
+| `update_post` | Patch fields on an existing post |
+| `delete_post` | Delete a post and clean up its tag index |
+| `upload_media` | Upload base64-encoded bytes to S3 and create a `Media` record |
+| `get_schema` | Return the CMS content schema (Post / Page / Media field shapes) |
+
+The server signs in to your Cognito User Pool with the credentials you provide (env vars), so each tool runs with the role of that user (`ampless-admin` or `ampless-editor`). Drafts and editing surface only to authenticated users; the resolver-side `status === 'published'` filter still keeps unpublished content invisible to public reads.
+
+## Install
+
+The server is published as a Node CLI; you typically don't install it globally — point your MCP client at `npx -y @ampless/mcp-server@alpha` instead.
+
+## Configure
+
+You need:
+
+1. **`amplify_outputs.json`** — generated by `npx ampx sandbox` or `npx ampx pipeline-deploy`. The path is passed via `--outputs`.
+2. **A Cognito user account** — email + password from your User Pool. The first user created via the admin UI is automatically in `ampless-admin`.
+3. **AWS credentials** — only required if you intend to use `upload_media`. The default credential chain (`AWS_PROFILE`, env vars, instance role) is used. Read-only tools work without AWS credentials.
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent path on your platform:
+
+```json
+{
+  "mcpServers": {
+    "ampless": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@ampless/mcp-server",
+        "--outputs",
+        "/absolute/path/to/your-site/amplify_outputs.json"
+      ],
+      "env": {
+        "AMPLESS_MCP_EMAIL": "you@example.com",
+        "AMPLESS_MCP_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 7 tools should appear under `/mcp`.
+
+### Cursor
+
+Edit `~/.cursor/mcp.json` (or use **Cursor Settings → MCP**). The config shape is the same as Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "ampless": {
+      "command": "npx",
+      "args": ["-y", "@ampless/mcp-server", "--outputs", "/path/to/amplify_outputs.json"],
+      "env": {
+        "AMPLESS_MCP_EMAIL": "you@example.com",
+        "AMPLESS_MCP_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add a project-level MCP server:
+
+```bash
+claude mcp add ampless \
+  --env AMPLESS_MCP_EMAIL=you@example.com \
+  --env AMPLESS_MCP_PASSWORD=your-password \
+  -- npx -y @ampless/mcp-server --outputs /path/to/amplify_outputs.json
+```
+
+## Usage examples
+
+Once registered, prompt your AI agent:
+
+- "List the latest 5 posts."
+- "Show me the post with slug `welcome`."
+- "Create a draft titled 'My second post' with format markdown and body 'Hello world.'"
+- "Publish post `post-1234`."
+- "Delete the post with slug `bad-draft`."
+
+The agent will pick the right tool automatically.
+
+### `body` shape per `format`
+
+- `format: 'markdown'` → body is a markdown source string
+- `format: 'html'` → body is a raw HTML string (rendered verbatim — see editor trust model below)
+- `format: 'tiptap'` → body is the tiptap document JSON, e.g.
+
+  ```json
+  {
+    "type": "doc",
+    "content": [
+      { "type": "paragraph", "content": [{ "type": "text", "text": "Hello" }] }
+    ]
+  }
+  ```
+
+If you're letting the AI generate post bodies, asking for markdown is usually easiest.
+
+## Security notes
+
+- **Editor trust model.** ampless treats `editor` and `admin` as a single trust class — both can store arbitrary HTML/JS in post bodies (see `docs/architecture/04-access-layer-mcp.md`). Whatever the MCP server can write, that user account could already write through the admin UI.
+- **Credentials in the config file.** `AMPLESS_MCP_PASSWORD` lives in plaintext inside Claude Desktop / Cursor's config file. Treat that file like an SSH private key. v0.2 adds OS keychain integration.
+- **AWS credentials.** Only `upload_media` requires them. Use a dedicated IAM user / role with write access only to your site's S3 bucket.
+
+## CLI flags
+
+```
+ampless-mcp [options]
+
+  --outputs <path>        Path to amplify_outputs.json (also AMPLESS_MCP_OUTPUTS)
+  --site-id <id>          Default siteId for queries (also AMPLESS_MCP_SITE_ID; default "default")
+```
+
+Required env:
+
+```
+AMPLESS_MCP_EMAIL          Cognito user email
+AMPLESS_MCP_PASSWORD       Cognito user password
+```
+
+## Troubleshooting
+
+- **`NotAuthorizedException: Incorrect username or password.`** — Wrong creds, or the user hasn't confirmed their email. Sign in via the web `/login` once first.
+- **`InvalidPasswordException`** — The user is in `FORCE_CHANGE_PASSWORD` state. Sign in via the web UI to set a permanent password.
+- **`AppSync 401`** — id token may have been rejected; the server auto-refreshes on the next call. Repeated 401s usually mean the User Pool was redeployed and your creds need updating.
+- **`upload_media` fails with no AWS credentials** — set `AWS_PROFILE` or `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` in the MCP server's environment.

package/dist/chunk-27JGNXJE.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+// ../../node_modules/.pnpm/@smithy+core@3.23.17/node_modules/@smithy/core/dist-es/util-identity-and-auth/httpAuthSchemes/noAuth.js
+var NoAuthSigner = class {
+  async sign(httpRequest, identity, signingProperties) {
+    return httpRequest;
+  }
+};
+
+// ../../node_modules/.pnpm/@aws-sdk+nested-clients@3.997.5/node_modules/@aws-sdk/nested-clients/package.json
+var package_default = {
+  name: "@aws-sdk/nested-clients",
+  version: "3.997.5",
+  description: "Nested clients for AWS SDK packages.",
+  main: "./dist-cjs/index.js",
+  module: "./dist-es/index.js",
+  types: "./dist-types/index.d.ts",
+  scripts: {
+    build: "yarn lint && concurrently 'yarn:build:types' 'yarn:build:es' && yarn build:cjs",
+    "build:cjs": "node ../../scripts/compilation/inline nested-clients",
+    "build:es": "tsc -p tsconfig.es.json",
+    "build:include:deps": 'yarn g:turbo run build -F="$npm_package_name"',
+    "build:types": "tsc -p tsconfig.types.json",
+    "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
+    clean: "premove dist-cjs dist-es dist-types tsconfig.cjs.tsbuildinfo tsconfig.es.tsbuildinfo tsconfig.types.tsbuildinfo",
+    lint: "node ../../scripts/validation/submodules-linter.js --pkg nested-clients",
+    test: "yarn g:vitest run",
+    "test:watch": "yarn g:vitest watch"
+  },
+  engines: {
+    node: ">=20.0.0"
+  },
+  sideEffects: false,
+  author: {
+    name: "AWS SDK for JavaScript Team",
+    url: "https://aws.amazon.com/javascript/"
+  },
+  license: "Apache-2.0",
+  dependencies: {
+    "@aws-crypto/sha256-browser": "5.2.0",
+    "@aws-crypto/sha256-js": "5.2.0",
+    "@aws-sdk/core": "^3.974.7",
+    "@aws-sdk/middleware-host-header": "^3.972.10",
+    "@aws-sdk/middleware-logger": "^3.972.10",
+    "@aws-sdk/middleware-recursion-detection": "^3.972.11",
+    "@aws-sdk/middleware-user-agent": "^3.972.37",
+    "@aws-sdk/region-config-resolver": "^3.972.13",
+    "@aws-sdk/signature-v4-multi-region": "^3.996.24",
+    "@aws-sdk/types": "^3.973.8",
+    "@aws-sdk/util-endpoints": "^3.996.8",
+    "@aws-sdk/util-user-agent-browser": "^3.972.10",
+    "@aws-sdk/util-user-agent-node": "^3.973.23",
+    "@smithy/config-resolver": "^4.4.17",
+    "@smithy/core": "^3.23.17",
+    "@smithy/fetch-http-handler": "^5.3.17",
+    "@smithy/hash-node": "^4.2.14",
+    "@smithy/invalid-dependency": "^4.2.14",
+    "@smithy/middleware-content-length": "^4.2.14",
+    "@smithy/middleware-endpoint": "^4.4.32",
+    "@smithy/middleware-retry": "^4.5.7",
+    "@smithy/middleware-serde": "^4.2.20",
+    "@smithy/middleware-stack": "^4.2.14",
+    "@smithy/node-config-provider": "^4.3.14",
+    "@smithy/node-http-handler": "^4.6.1",
+    "@smithy/protocol-http": "^5.3.14",
+    "@smithy/smithy-client": "^4.12.13",
+    "@smithy/types": "^4.14.1",
+    "@smithy/url-parser": "^4.2.14",
+    "@smithy/util-base64": "^4.3.2",
+    "@smithy/util-body-length-browser": "^4.2.2",
+    "@smithy/util-body-length-node": "^4.2.3",
+    "@smithy/util-defaults-mode-browser": "^4.3.49",
+    "@smithy/util-defaults-mode-node": "^4.2.54",
+    "@smithy/util-endpoints": "^3.4.2",
+    "@smithy/util-middleware": "^4.2.14",
+    "@smithy/util-retry": "^4.3.6",
+    "@smithy/util-utf8": "^4.2.2",
+    tslib: "^2.6.2"
+  },
+  devDependencies: {
+    concurrently: "7.0.0",
+    "downlevel-dts": "0.10.1",
+    premove: "4.0.0",
+    typescript: "~5.8.3"
+  },
+  typesVersions: {
+    "<4.5": {
+      "dist-types/*": [
+        "dist-types/ts3.4/*"
+      ]
+    }
+  },
+  files: [
+    "./cognito-identity.d.ts",
+    "./cognito-identity.js",
+    "./signin.d.ts",
+    "./signin.js",
+    "./sso-oidc.d.ts",
+    "./sso-oidc.js",
+    "./sso.d.ts",
+    "./sso.js",
+    "./sts.d.ts",
+    "./sts.js",
+    "dist-*/**"
+  ],
+  browser: {
+    "./dist-es/submodules/cognito-identity/runtimeConfig": "./dist-es/submodules/cognito-identity/runtimeConfig.browser",
+    "./dist-es/submodules/signin/runtimeConfig": "./dist-es/submodules/signin/runtimeConfig.browser",
+    "./dist-es/submodules/sso-oidc/runtimeConfig": "./dist-es/submodules/sso-oidc/runtimeConfig.browser",
+    "./dist-es/submodules/sso/runtimeConfig": "./dist-es/submodules/sso/runtimeConfig.browser",
+    "./dist-es/submodules/sts/runtimeConfig": "./dist-es/submodules/sts/runtimeConfig.browser"
+  },
+  "react-native": {},
+  homepage: "https://github.com/aws/aws-sdk-js-v3/tree/main/packages/nested-clients",
+  repository: {
+    type: "git",
+    url: "https://github.com/aws/aws-sdk-js-v3.git",
+    directory: "packages/nested-clients"
+  },
+  exports: {
+    "./package.json": "./package.json",
+    "./sso-oidc": {
+      types: "./dist-types/submodules/sso-oidc/index.d.ts",
+      module: "./dist-es/submodules/sso-oidc/index.js",
+      node: "./dist-cjs/submodules/sso-oidc/index.js",
+      import: "./dist-es/submodules/sso-oidc/index.js",
+      require: "./dist-cjs/submodules/sso-oidc/index.js"
+    },
+    "./sts": {
+      types: "./dist-types/submodules/sts/index.d.ts",
+      module: "./dist-es/submodules/sts/index.js",
+      node: "./dist-cjs/submodules/sts/index.js",
+      import: "./dist-es/submodules/sts/index.js",
+      require: "./dist-cjs/submodules/sts/index.js"
+    },
+    "./signin": {
+      types: "./dist-types/submodules/signin/index.d.ts",
+      module: "./dist-es/submodules/signin/index.js",
+      node: "./dist-cjs/submodules/signin/index.js",
+      import: "./dist-es/submodules/signin/index.js",
+      require: "./dist-cjs/submodules/signin/index.js"
+    },
+    "./cognito-identity": {
+      types: "./dist-types/submodules/cognito-identity/index.d.ts",
+      module: "./dist-es/submodules/cognito-identity/index.js",
+      node: "./dist-cjs/submodules/cognito-identity/index.js",
+      import: "./dist-es/submodules/cognito-identity/index.js",
+      require: "./dist-cjs/submodules/cognito-identity/index.js"
+    },
+    "./sso": {
+      types: "./dist-types/submodules/sso/index.d.ts",
+      module: "./dist-es/submodules/sso/index.js",
+      node: "./dist-cjs/submodules/sso/index.js",
+      import: "./dist-es/submodules/sso/index.js",
+      require: "./dist-cjs/submodules/sso/index.js"
+    }
+  }
+};
+
+export {
+  NoAuthSigner,
+  package_default
+};

package/dist/chunk-44FZZOIP.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// ../../node_modules/.pnpm/@aws-sdk+core@3.974.7/node_modules/@aws-sdk/core/dist-es/submodules/client/setCredentialFeature.js
+function setCredentialFeature(credentials, feature, value) {
+  if (!credentials.$source) {
+    credentials.$source = {};
+  }
+  credentials.$source[feature] = value;
+  return credentials;
+}
+
+export {
+  setCredentialFeature
+};

package/dist/chunk-72G5HA35.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+// ../../node_modules/.pnpm/@smithy+protocol-http@5.3.14/node_modules/@smithy/protocol-http/dist-es/httpRequest.js
+var HttpRequest = class _HttpRequest {
+  method;
+  protocol;
+  hostname;
+  port;
+  path;
+  query;
+  headers;
+  username;
+  password;
+  fragment;
+  body;
+  constructor(options) {
+    this.method = options.method || "GET";
+    this.hostname = options.hostname || "localhost";
+    this.port = options.port;
+    this.query = options.query || {};
+    this.headers = options.headers || {};
+    this.body = options.body;
+    this.protocol = options.protocol ? options.protocol.slice(-1) !== ":" ? `${options.protocol}:` : options.protocol : "https:";
+    this.path = options.path ? options.path.charAt(0) !== "/" ? `/${options.path}` : options.path : "/";
+    this.username = options.username;
+    this.password = options.password;
+    this.fragment = options.fragment;
+  }
+  static clone(request) {
+    const cloned = new _HttpRequest({
+      ...request,
+      headers: { ...request.headers }
+    });
+    if (cloned.query) {
+      cloned.query = cloneQuery(cloned.query);
+    }
+    return cloned;
+  }
+  static isInstance(request) {
+    if (!request) {
+      return false;
+    }
+    const req = request;
+    return "method" in req && "protocol" in req && "hostname" in req && "path" in req && typeof req["query"] === "object" && typeof req["headers"] === "object";
+  }
+  clone() {
+    return _HttpRequest.clone(this);
+  }
+};
+function cloneQuery(query) {
+  return Object.keys(query).reduce((carry, paramName) => {
+    const param = query[paramName];
+    return {
+      ...carry,
+      [paramName]: Array.isArray(param) ? [...param] : param
+    };
+  }, {});
+}
+
+export {
+  HttpRequest
+};

package/dist/chunk-B57O737J.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// ../../node_modules/.pnpm/@smithy+smithy-client@4.12.13/node_modules/@smithy/smithy-client/dist-es/create-aggregated-client.js
+var createAggregatedClient = (commands, Client, options) => {
+  for (const [command, CommandCtor] of Object.entries(commands)) {
+    const methodImpl = async function(args, optionsOrCb, cb) {
+      const command2 = new CommandCtor(args);
+      if (typeof optionsOrCb === "function") {
+        this.send(command2, optionsOrCb);
+      } else if (typeof cb === "function") {
+        if (typeof optionsOrCb !== "object")
+          throw new Error(`Expected http options but got ${typeof optionsOrCb}`);
+        this.send(command2, optionsOrCb || {}, cb);
+      } else {
+        return this.send(command2, optionsOrCb);
+      }
+    };
+    const methodName = (command[0].toLowerCase() + command.slice(1)).replace(/Command$/, "");
+    Client.prototype[methodName] = methodImpl;
+  }
+  const { paginators = {}, waiters = {} } = options ?? {};
+  for (const [paginatorName, paginatorFn] of Object.entries(paginators)) {
+    if (Client.prototype[paginatorName] === void 0) {
+      Client.prototype[paginatorName] = function(commandInput = {}, paginationConfiguration, ...rest) {
+        return paginatorFn({
+          ...paginationConfiguration,
+          client: this
+        }, commandInput, ...rest);
+      };
+    }
+  }
+  for (const [waiterName, waiterFn] of Object.entries(waiters)) {
+    if (Client.prototype[waiterName] === void 0) {
+      Client.prototype[waiterName] = async function(commandInput = {}, waiterConfiguration, ...rest) {
+        let config = waiterConfiguration;
+        if (typeof waiterConfiguration === "number") {
+          config = {
+            maxWaitTime: waiterConfiguration
+          };
+        }
+        return waiterFn({
+          ...config,
+          client: this
+        }, commandInput, ...rest);
+      };
+    }
+  }
+};
+
+export {
+  createAggregatedClient
+};

package/dist/chunk-E6YHJFDU.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+// ../../node_modules/.pnpm/@smithy+is-array-buffer@4.2.2/node_modules/@smithy/is-array-buffer/dist-es/index.js
+var isArrayBuffer = (arg) => typeof ArrayBuffer === "function" && arg instanceof ArrayBuffer || Object.prototype.toString.call(arg) === "[object ArrayBuffer]";
+
+// ../../node_modules/.pnpm/@smithy+util-buffer-from@4.2.2/node_modules/@smithy/util-buffer-from/dist-es/index.js
+import { Buffer } from "buffer";
+var fromArrayBuffer = (input, offset = 0, length = input.byteLength - offset) => {
+  if (!isArrayBuffer(input)) {
+    throw new TypeError(`The "input" argument must be ArrayBuffer. Received type ${typeof input} (${input})`);
+  }
+  return Buffer.from(input, offset, length);
+};
+var fromString = (input, encoding) => {
+  if (typeof input !== "string") {
+    throw new TypeError(`The "input" argument must be of type string. Received type ${typeof input} (${input})`);
+  }
+  return encoding ? Buffer.from(input, encoding) : Buffer.from(input);
+};
+
+// ../../node_modules/.pnpm/@smithy+util-utf8@4.2.2/node_modules/@smithy/util-utf8/dist-es/fromUtf8.js
+var fromUtf8 = (input) => {
+  const buf = fromString(input, "utf8");
+  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength / Uint8Array.BYTES_PER_ELEMENT);
+};
+
+// ../../node_modules/.pnpm/@smithy+util-utf8@4.2.2/node_modules/@smithy/util-utf8/dist-es/toUtf8.js
+var toUtf8 = (input) => {
+  if (typeof input === "string") {
+    return input;
+  }
+  if (typeof input !== "object" || typeof input.byteOffset !== "number" || typeof input.byteLength !== "number") {
+    throw new Error("@smithy/util-utf8: toUtf8 encoder function only accepts string | Uint8Array.");
+  }
+  return fromArrayBuffer(input.buffer, input.byteOffset, input.byteLength).toString("utf8");
+};
+
+export {
+  isArrayBuffer,
+  fromArrayBuffer,
+  fromString,
+  fromUtf8,
+  toUtf8
+};