@maanster/dreamaan-mcp 0.4.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.5.2] - 2026-10-09
+
+- Publish maintained skill files and ZIP through HTTP with version, compatibility, SHA-256 checksums and conditional downloads.
+- Expose the same manifest through workflow_get and the MCP production_manifest resource.
+- Derive skill metadata directly from SKILL.md to prevent version drift.
+
+## [0.5.1] - 2026-10-09
+
+- Skill 0.3.1 explains endpoint-specific asset-link roles, direction, pinned files, collections and frame/video examples.
+- Category metadata guidance avoids duplicating native prompts, generation costs, media/version facts and review/assignment state; preserves existing values on updates.
+- Clarify link and metadata tool descriptions and refresh the shared downloadable skill.
+
+## [0.5.0] - 2026-10-09
+
+- Dreamaan production skill 0.3.0: screenplay structure, reusable assets, frame-to-video continuity, assignments/reviews and budgets.
+- Free workflow_get tool, production_workflow prompt and nine workflow resources expose the same maintained skill to different MCP clients.
+- Reproducible skill bundle export for web downloads and client setup.
+
+## [0.4.1] - 2026-10-09
+
+- Standalone public installation, login, MCP connection and upload documentation.
+- Remove private repository links and developer-only guidance from the package README and client guides.
+- Correct skill guidance for browser OAuth and document proprietary licensing.
+
 ## [0.4.0] - 2026-10-08
 
 - Public browser OAuth with PKCE for the local CLI; private shared profiles refresh and revoke tokens, and stdio uses the same login.

package/README.md

@@ -1,132 +1,124 @@
 # Dreamaan MCP
 
-Stateless Model Context Protocol service for Dreamaan: MCP spec `2026-07-28` (SDK v2) and 2025-era clients on the same endpoint, over Streamable HTTP and stdio. The service exposes project, cinema, assets, generation, model, collaboration and administration tools with permission checks, bounded responses, resources and read-only workflow prompts.
+Connect your AI assistant to Dreamaan to work with projects, assets, generation models and collaboration workflows. Your Dreamaan account, project permissions and spending limits apply to every connection.
 
-Design, architecture, tool catalog, and implementation issues are maintained in the [Dreamaan MCP design docs](https://github.com/copilot-rast/dreamaan/tree/dev/docs/mcp).
+**One package: `@maanster/dreamaan-mcp`.** It includes `dreamaan-mcp`, the local MCP server, and `dreamaan`, the terminal command for login, diagnostics and uploads.
 
-This repository is included as the `dreamaan-mcp` submodule of [Dreamaan](https://github.com/copilot-rast/dreamaan). Development targets the `dev` branch.
+## Do I need this package?
 
-## Client guides
+- **Dreamaan web app:** no package required.
+- **Hosted MCP connection:** no package required. Add the remote MCP URL provided by your Dreamaan environment to a client supporting Streamable HTTP and OAuth.
+- **Local MCP connection or terminal uploads:** install this package.
 
-- [Installation and hosted/local connection](docs/client/install.md)
-- [Companion CLI](docs/client/cli.md): login, diagnostics and local uploads
-- [Asset upload workflow and host limitations](docs/client/uploads.md)
-- [Dreamaan workflow skill](docs/client/skill.md)
-- [Client OAuth and upload conventions](docs/client/conventions.md)
-- [Backend requirements and pagination migration](docs/client/pagination.md)
+Hosted and local connections have separate sign-in sessions. Installing the package does not grant access to Dreamaan projects.
 
-- [راهنمای فارسی اتصال ChatGPT، Claude و Codex](docs/mcp/CLIENTS-FA.md) — OAuth, HTTP/stdio, access, spending and troubleshooting.
+## Requirements
 
-## Develop
+- Node.js 22 or later.
+- Linux or macOS for local credential and upload-state storage. Windows is currently unsupported.
+- A Dreamaan account and access to the projects you intend to use.
+- Your environment's API URL, including `/api`. Use the URL provided by your Dreamaan administrator; do not substitute a web-app or MCP URL.
 
-Node 22, pnpm.
+## Install
 
-```bash
-pnpm install
-cp .env.example .env      # then export the variables, e.g. set -a; . ./.env; set +a
-pnpm dev                  # http transport on 127.0.0.1:3100, restarts on change
-pnpm lint && pnpm typecheck && pnpm test && pnpm build
+```sh
+npm install --global @maanster/dreamaan-mcp@0.5.1
+dreamaan-mcp --version
+dreamaan --help
 ```
 
-```bash
-node dist/bin/dreamaan-mcp.js --help
-node dist/bin/dreamaan-mcp.js --transport http    # POST /mcp, GET /health, GET /ready
-node dist/bin/dreamaan-mcp.js --transport stdio   # JSON-RPC on stdin/stdout, logs on stderr
+The package is public: downloading it does not require an npm account. Accessing Dreamaan requires Dreamaan authentication.
+
+## Sign in
+
+Replace `YOUR_API_HOST` with your environment's API host:
+
+```sh
+dreamaan login --api-url https://YOUR_API_HOST/api
 ```
 
-## Authentication
+Approve access in your browser. The CLI saves a private local profile and refreshes OAuth tokens automatically. If the browser cannot open automatically, add `--no-browser` and open the printed link on the same computer.
 
-Every request to `/mcp` passes an HTTP gate (`src/auth/gate.ts`) before the SDK: Host/Origin, then the credential. A missing or invalid credential is a real HTTP 401 challenge; credentials are read only from the `Authorization` header.
+```sh
+dreamaan whoami --api-url https://YOUR_API_HOST/api
+dreamaan doctor --api-url https://YOUR_API_HOST/api
+```
 
-- **Credentials:** `dmn_key_…` API keys, and (when `DREAMAAN_ISSUER` is set) MCP-audience OAuth access tokens (`aud` = `MCP_PUBLIC_URL`, verified against the issuer's JWKS). Login JWTs and internal API tokens are rejected.
-- **HTTP: token exchange, always.** Every credential is exchanged (RFC 8693, `private_key_jwt`) for a 5-minute internal API token, cached until `exp - 30 s` and evicted on any API 401. Needs `DREAMAAN_ISSUER`, `MCP_OAUTH_CLIENT_ID`, `MCP_OAUTH_PRIVATE_KEY` and `MCP_PUBLIC_URL`. On HTTP there is no direct path and no flag: without the OAuth settings the http transport refuses to start, and no credential is ever forwarded as-is.
-- **Grant:** loaded from `GET /api/auth/me` and cached for `MCP_GRANT_CACHE_TTL_MS` (default and maximum 30 s, ARCHITECTURE §5.4). Grants are multi-organization: the context carries the organization and project access policy, and the organization for a call is the tool's explicit `orgId`, never a default.
-- **No capabilities:** API keys and OAuth connections have no read/generate/write/admin-style scopes, and every tool is listed for every grant. A grant's access is only its organizations and projects, an optional spend cap, expiry and revocation, and everything stays bounded by the user's own RBAC, organization policy, budgets and the preview/confirm step of risky tools. OAuth carries one fixed scope string, `dreamaan:access`, for protocol compatibility only; it grants nothing by itself.
-- **stdio: the user’s local login, sent to its API.** Run `dreamaan login --api-url https://YOUR_API_HOST/api` for public browser OAuth with PKCE, or use `DREAMAAN_API_KEY`. The local MCP server uses the saved private profile, refreshes rotating tokens and validates the live grant; it never launches a browser inside stdio. Configure `DREAMAAN_API_URL`; no confidential OAuth key is needed. Usage is direct API traffic. See [CLI setup](docs/client/cli.md).
+## Connect a local MCP client
+
+After signing in, configure your client's local MCP server entry:
+
+```json
+{
+  "mcpServers": {
+    "dreamaan": {
+      "command": "dreamaan-mcp",
+      "args": ["--transport", "stdio"],
+      "env": {
+        "DREAMAAN_API_URL": "https://YOUR_API_HOST/api"
+      }
+    }
+  }
+}
+```
 
-### Revocation latency
+This is a common JSON configuration shape; use your client's equivalent if it differs. The client must be able to find the globally installed executable. If necessary, use its absolute path. Restart the MCP connection after changing configuration.
 
-Revoking a grant (an API key or an OAuth consent) takes effect on a running MCP process after at most `MCP_GRANT_CACHE_TTL_MS` (30 s by default; it cannot be set higher). Two caches are involved:
+The local server uses the saved login for that API URL. Alternatively, provide a dedicated `DREAMAAN_API_KEY` in the client environment. An explicit API key takes precedence over the saved OAuth profile.
 
-- the **grant cache** (`GET /auth/me`, at most 30 s): within it the process still serves the cached grant;
-- the **internal token** (5 minutes, reused until `exp - 30 s`): it is not re-checked by the MCP, but the Dreamaan API refuses a token of a revoked grant, and any API 401 evicts both the token and the cached grant. So the internal token does not extend the 30 s bound for calls that reach the API; it only means the exchange is not repeated until the token nears expiry.
+Your assistant can discover projects, browse assets, inspect model constraints, prepare references, quote generation costs and track jobs. Ask it to show the quote before starting paid generation. Available actions remain limited by your permissions and the connected environment.
 
-A process that has nothing cached (a restart) exchanges again and the backend refuses a revoked grant at once.
+## Upload an asset
 
-`WEB_BASE_URL` (default `http://localhost:7070`) is the base of every `webUrl` (`<url>/go/<type>/<id>`).
+Upload a local original file and register it as a new asset:
 
-`DREAMAAN_API_URL` is required and includes the API prefix (for example `http://localhost:3000/api`); `/health` probes `${DREAMAAN_API_URL}/health`. See `--help` for every variable.
+```sh
+dreamaan upload --api-url https://YOUR_API_HOST/api \
+  --file ./reference.png --project PROJECT_ID \
+  --name 'Reference image' --code REF-01 \
+  --state ./reference-upload.json --json
+```
 
-## Observability
+Use real project IDs from Dreamaan. To add a file version to an existing asset, replace `--name` and `--code` with `--asset ASSET_ID`. Keep the state file until completion; repeat the same command with `--resume` after an interruption. For large files, add `--transfer direct`.
 
-Off by default. Set `OTEL_EXPORTER_OTLP_ENDPOINT` (OTLP/HTTP collector; the standard `OTEL_EXPORTER_OTLP_*` headers/per-signal overrides, `OTEL_SERVICE_NAME` and `OTEL_METRIC_EXPORT_INTERVAL` also apply) to start the OpenTelemetry Node SDK at process start (`src/telemetry/`). Without it every call is a no-op. The exporters never write to stdout (stdio keeps it for JSON-RPC); SDK diagnostics go to stderr. A graceful shutdown flushes telemetry after the 10 s request drain (flush bounded to 5 s more).
+A displayed chat image is not automatically uploadable: the AI client must expose the original bytes, or you must save the file locally and use the CLI. Uploads register assets; comments and reviews reference those assets.
 
-- **Traces:** a server span per HTTP request (continues an incoming `traceparent`), the `mcp.tool` span, and one client span per API attempt; the API call carries that span's `traceparent`.
-- **Metrics** (OTel name, Prometheus form `mcp_tool_calls_total`, `mcp_tool_duration_seconds`, ...):
-  `mcp.tool.calls` and `mcp.tool.duration` (`tool.name`, `outcome`: `ok` or the failure kind; a truncated success is `ok`),
-  `mcp.http.auth_failures` (`status` 401/403, `reason`), `mcp.http.active_requests`,
-  `mcp.token_exchanges` and `mcp.token_exchange.duration` (`outcome`: `ok`, `invalid` = revoked or unknown credential, `unavailable` = exchange/issuer failure),
-  `mcp.api.duration`, `mcp.api.errors` (`http.route`, `http.request.method`, `error.type`) and `mcp.api.rate_limited` (429s from the API); `http.route` is a template (`/projects/:id`), never a raw path,
-  `mcp.credits.started` (`grant.id`, `org.id`), `mcp.generation_wait.calls|degraded|duration`, `mcp.job.snapshot_states` (`state`), `mcp.job.replays`.
-- **Never in attributes:** credentials, tokens, prompts or user content. Only tool name, outcome, grant id/kind/key prefix, org id, route template and status.
+## Troubleshooting
 
-### Probes
+| Problem                            | What to do                                                                                                |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Executable not found               | Check Node.js version and your global npm executable path; use an absolute path in the MCP configuration. |
+| Sign-in expired or revoked         | Run `dreamaan login` again for the exact API URL.                                                         |
+| Access denied                      | Check the selected projects, connection permissions and your Dreamaan membership.                         |
+| API unreachable                    | Run `dreamaan doctor`; verify the API URL and network access.                                             |
+| Upload exceeds the streaming limit | Use `--transfer direct`; the environment still enforces file-size and quota limits.                       |
+| Upload interrupted                 | Preserve its state file and retry with `--resume`.                                                        |
+| A workflow is unavailable          | Ask your Dreamaan administrator whether the environment supports it.                                      |
 
-- `GET /health`: liveness. 200 whenever the process serves; the body carries `status` (`ok`/`degraded`) and `apiReachable` for humans. It never fails on a dependency, so an API outage does not restart the service. The Docker `HEALTHCHECK` uses it.
-- `GET /ready`: readiness. 503 when `${DREAMAAN_API_URL}/health` is unreachable (cached 5 s) or the required auth config is missing, 200 otherwise (`checks.api`, `checks.auth`). Use it as the load balancer / Traefik health check.
+For account or environment help, contact your Dreamaan administrator or your existing Dreamaan support channel. Include the package version, command or tool name, and a redacted error message. Do not include credentials or signed upload URLs.
 
-## Layout
+## Update, logout and remove
 
-```
-src/bin/dreamaan-mcp.ts   CLI entry
-src/cli.ts                argument parsing, transport selection, shutdown
-src/config.ts             zod-validated environment
-src/server.ts             McpServer factory (one per request / connection)
-src/context.ts            ToolContext: grant, org/project access, trace id
-src/auth/                 HTTP gate, JWT/JWKS verification, token exchange, grant loading, stdio key
-src/tools/                tools built with defineTool() (_framework.ts); index.ts is the registry,
-                          _lint.ts the lint rules the tests apply to every tool
-src/shape/                entity/job shapers (webUrl, civil dates, job snapshots), size guard
-src/transport/            http.ts, stdio.ts, health.ts
-src/telemetry/            OpenTelemetry bootstrap (sdk.ts) and metric instruments (metrics.ts)
-test/{unit,contract,e2e}
+```sh
+npm install --global @maanster/dreamaan-mcp@latest
+dreamaan logout --api-url https://YOUR_API_HOST/api
+npm uninstall --global @maanster/dreamaan-mcp
 ```
 
-## Manual round trip (the temporary `ping` tool)
+OAuth logout revokes the CLI connection and removes its local profile. Uninstalling the package alone does not revoke a connection. Manage other connected apps and API keys separately in Dreamaan settings.
 
-> **Warning: API keys sit in plaintext in client config files.** The `dmn_key_…` value you put in `claude_desktop_config.json`, `.mcp.json`, `config.toml` or a `--header` argument is stored unencrypted, readable by anything that can read that file, and can end up in shell history. Create a separate key per client, grant it only the scopes that client needs (not admin, billing or delete unless required) and set a short expiry. Never commit the file, and revoke the key at once if it leaks.
+## Production skill and workflows
 
-Claude Code over HTTP:
+The package includes the Dreamaan production skill (version 0.3.1): screenplay breakdown into sequences/plans/outputs, character/location/prop preparation and linking, version-pinned frames to videos, assignments/reviews and production budgeting.
 
-```bash
-# needs the token exchange (see Authentication): the issuer, client id/key and public URL
-DREAMAAN_API_URL=http://localhost:3000/api DREAMAAN_ISSUER=http://localhost:3000 \
-  MCP_OAUTH_CLIENT_ID=dreamaan-mcp MCP_OAUTH_PRIVATE_KEY="$(cat client-key.pem)" \
-  MCP_PUBLIC_URL=http://127.0.0.1:3100/mcp pnpm dev
-claude mcp add --transport http dreamaan-local http://127.0.0.1:3100/mcp --header "Authorization: Bearer dmn_key_..."
-# in Claude Code: /mcp shows dreamaan-local; ask it to call the ping tool -> "pong"
-```
+Run `npm root --global`, then copy the complete `@maanster/dreamaan-mcp/skills/dreamaan` folder to your client's skills directory. Keep its reference guides with it and connect Dreamaan MCP. A skill-capable client can then use it for requests such as “Break this screenplay into plans and propose an asset checklist and budget” or “Create a reviewed frame-to-video pilot for this plan.”
 
-Claude Desktop over stdio (`claude_desktop_config.json`):
+Dreamaan web settings also provide a downloadable skill bundle and client instructions. Clients without skill installation can call `workflow_get`, read `dreamaan://workflows/overview`, or use the `production_workflow` prompt if supported. These guides never perform writes or spending themselves.
 
-```json
-{
-  "mcpServers": {
-    "dreamaan-local": {
-      "command": "node",
-      "args": ["/absolute/path/to/dreamaan-mcp/dist/bin/dreamaan-mcp.js", "--transport", "stdio"],
-      "env": {
-        "DREAMAAN_API_URL": "http://localhost:3000/api",
-        "DREAMAAN_API_KEY": "dmn_key_..."
-      }
-    }
-  }
-}
-```
+## Additional guides
+
+The installed package includes `docs/client/` guides for login, uploads, paging and the optional `skills/dreamaan/` workflow skill. These files are bundled with the package; no source-repository access is required. To locate a global installation, run `npm root --global`, then open its `@maanster/dreamaan-mcp` folder.
 
-See [output apps and client capabilities](docs/output-apps.md) for the optional
-read-only media player/contact sheet, trusted storage origin and text fallbacks.
+## License
 
-Package artifact review and public publication are documented in
-[docs/package-release.md](docs/package-release.md). Version `0.2.0` is Unreleased;
-no public npm distribution is authorized.
+Dreamaan MCP is proprietary, closed-source software. This package is distributed with `UNLICENSED` metadata and does not grant an open-source license. Public npm availability does not make Dreamaan's source repositories public or grant rights to redistribute or modify the software. Contact Dreamaan for applicable licensing terms.