@maanster/dreamaan-mcp 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +79 -95
  3. package/dist/bin/dreamaan-mcp.js +4 -7
  4. package/dist/bin/dreamaan.js +4 -7
  5. package/dist/index.js +4 -7
  6. package/docs/client/conventions.md +8 -49
  7. package/docs/client/install.md +14 -30
  8. package/docs/client/pagination.md +5 -7
  9. package/docs/client/skill.md +10 -42
  10. package/docs/client/uploads.md +0 -8
  11. package/package.json +4 -7
  12. package/skills/dreamaan/SKILL.md +1 -1
  13. package/skills/dreamaan/references/generation.md +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.4.1] - 2026-10-09
4
+
5
+ - Standalone public installation, login, MCP connection and upload documentation.
6
+ - Remove private repository links and developer-only guidance from the package README and client guides.
7
+ - Correct skill guidance for browser OAuth and document proprietary licensing.
8
+
3
9
  ## [0.4.0] - 2026-10-08
4
10
 
5
11
  - 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 CHANGED
@@ -1,132 +1,116 @@
1
1
  # Dreamaan MCP
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- 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).
5
+ **One package: `@maanster/dreamaan-mcp`.** It includes `dreamaan-mcp`, the local MCP server, and `dreamaan`, the terminal command for login, diagnostics and uploads.
6
6
 
7
- This repository is included as the `dreamaan-mcp` submodule of [Dreamaan](https://github.com/copilot-rast/dreamaan). Development targets the `dev` branch.
7
+ ## Do I need this package?
8
8
 
9
- ## Client guides
9
+ - **Dreamaan web app:** no package required.
10
+ - **Hosted MCP connection:** no package required. Add the remote MCP URL provided by your Dreamaan environment to a client supporting Streamable HTTP and OAuth.
11
+ - **Local MCP connection or terminal uploads:** install this package.
10
12
 
11
- - [Installation and hosted/local connection](docs/client/install.md)
12
- - [Companion CLI](docs/client/cli.md): login, diagnostics and local uploads
13
- - [Asset upload workflow and host limitations](docs/client/uploads.md)
14
- - [Dreamaan workflow skill](docs/client/skill.md)
15
- - [Client OAuth and upload conventions](docs/client/conventions.md)
16
- - [Backend requirements and pagination migration](docs/client/pagination.md)
13
+ Hosted and local connections have separate sign-in sessions. Installing the package does not grant access to Dreamaan projects.
17
14
 
18
- - [راهنمای فارسی اتصال ChatGPT، Claude و Codex](docs/mcp/CLIENTS-FA.md) — OAuth, HTTP/stdio, access, spending and troubleshooting.
15
+ ## Requirements
19
16
 
20
- ## Develop
17
+ - Node.js 22 or later.
18
+ - Linux or macOS for local credential and upload-state storage. Windows is currently unsupported.
19
+ - A Dreamaan account and access to the projects you intend to use.
20
+ - Your environment's API URL, including `/api`. Use the URL provided by your Dreamaan administrator; do not substitute a web-app or MCP URL.
21
21
 
22
- Node 22, pnpm.
22
+ ## Install
23
23
 
24
- ```bash
25
- pnpm install
26
- cp .env.example .env # then export the variables, e.g. set -a; . ./.env; set +a
27
- pnpm dev # http transport on 127.0.0.1:3100, restarts on change
28
- pnpm lint && pnpm typecheck && pnpm test && pnpm build
24
+ ```sh
25
+ npm install --global @maanster/dreamaan-mcp@0.4.1
26
+ dreamaan-mcp --version
27
+ dreamaan --help
29
28
  ```
30
29
 
31
- ```bash
32
- node dist/bin/dreamaan-mcp.js --help
33
- node dist/bin/dreamaan-mcp.js --transport http # POST /mcp, GET /health, GET /ready
34
- node dist/bin/dreamaan-mcp.js --transport stdio # JSON-RPC on stdin/stdout, logs on stderr
35
- ```
30
+ The package is public: downloading it does not require an npm account. Accessing Dreamaan requires Dreamaan authentication.
31
+
32
+ ## Sign in
36
33
 
37
- ## Authentication
34
+ Replace `YOUR_API_HOST` with your environment's API host:
38
35
 
39
- 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.
36
+ ```sh
37
+ dreamaan login --api-url https://YOUR_API_HOST/api
38
+ ```
40
39
 
41
- - **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.
42
- - **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.
43
- - **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.
44
- - **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.
45
- - **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).
40
+ 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.
46
41
 
47
- ### Revocation latency
42
+ ```sh
43
+ dreamaan whoami --api-url https://YOUR_API_HOST/api
44
+ dreamaan doctor --api-url https://YOUR_API_HOST/api
45
+ ```
48
46
 
49
- 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:
47
+ ## Connect a local MCP client
50
48
 
51
- - the **grant cache** (`GET /auth/me`, at most 30 s): within it the process still serves the cached grant;
52
- - 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.
49
+ After signing in, configure your client's local MCP server entry:
53
50
 
54
- A process that has nothing cached (a restart) exchanges again and the backend refuses a revoked grant at once.
51
+ ```json
52
+ {
53
+ "mcpServers": {
54
+ "dreamaan": {
55
+ "command": "dreamaan-mcp",
56
+ "args": ["--transport", "stdio"],
57
+ "env": {
58
+ "DREAMAAN_API_URL": "https://YOUR_API_HOST/api"
59
+ }
60
+ }
61
+ }
62
+ }
63
+ ```
55
64
 
56
- `WEB_BASE_URL` (default `http://localhost:7070`) is the base of every `webUrl` (`<url>/go/<type>/<id>`).
65
+ 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.
57
66
 
58
- `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.
67
+ 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.
59
68
 
60
- ## Observability
69
+ 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.
61
70
 
62
- 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).
71
+ ## Upload an asset
63
72
 
64
- - **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`.
65
- - **Metrics** (OTel name, Prometheus form `mcp_tool_calls_total`, `mcp_tool_duration_seconds`, ...):
66
- `mcp.tool.calls` and `mcp.tool.duration` (`tool.name`, `outcome`: `ok` or the failure kind; a truncated success is `ok`),
67
- `mcp.http.auth_failures` (`status` 401/403, `reason`), `mcp.http.active_requests`,
68
- `mcp.token_exchanges` and `mcp.token_exchange.duration` (`outcome`: `ok`, `invalid` = revoked or unknown credential, `unavailable` = exchange/issuer failure),
69
- `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,
70
- `mcp.credits.started` (`grant.id`, `org.id`), `mcp.generation_wait.calls|degraded|duration`, `mcp.job.snapshot_states` (`state`), `mcp.job.replays`.
71
- - **Never in attributes:** credentials, tokens, prompts or user content. Only tool name, outcome, grant id/kind/key prefix, org id, route template and status.
73
+ Upload a local original file and register it as a new asset:
72
74
 
73
- ### Probes
75
+ ```sh
76
+ dreamaan upload --api-url https://YOUR_API_HOST/api \
77
+ --file ./reference.png --project PROJECT_ID \
78
+ --name 'Reference image' --code REF-01 \
79
+ --state ./reference-upload.json --json
80
+ ```
74
81
 
75
- - `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.
76
- - `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.
82
+ 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`.
77
83
 
78
- ## Layout
84
+ 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.
79
85
 
80
- ```
81
- src/bin/dreamaan-mcp.ts CLI entry
82
- src/cli.ts argument parsing, transport selection, shutdown
83
- src/config.ts zod-validated environment
84
- src/server.ts McpServer factory (one per request / connection)
85
- src/context.ts ToolContext: grant, org/project access, trace id
86
- src/auth/ HTTP gate, JWT/JWKS verification, token exchange, grant loading, stdio key
87
- src/tools/ tools built with defineTool() (_framework.ts); index.ts is the registry,
88
- _lint.ts the lint rules the tests apply to every tool
89
- src/shape/ entity/job shapers (webUrl, civil dates, job snapshots), size guard
90
- src/transport/ http.ts, stdio.ts, health.ts
91
- src/telemetry/ OpenTelemetry bootstrap (sdk.ts) and metric instruments (metrics.ts)
92
- test/{unit,contract,e2e}
93
- ```
86
+ ## Troubleshooting
94
87
 
95
- ## Manual round trip (the temporary `ping` tool)
88
+ | Problem | What to do |
89
+ | ---------------------------------- | --------------------------------------------------------------------------------------------------------- |
90
+ | Executable not found | Check Node.js version and your global npm executable path; use an absolute path in the MCP configuration. |
91
+ | Sign-in expired or revoked | Run `dreamaan login` again for the exact API URL. |
92
+ | Access denied | Check the selected projects, connection permissions and your Dreamaan membership. |
93
+ | API unreachable | Run `dreamaan doctor`; verify the API URL and network access. |
94
+ | Upload exceeds the streaming limit | Use `--transfer direct`; the environment still enforces file-size and quota limits. |
95
+ | Upload interrupted | Preserve its state file and retry with `--resume`. |
96
+ | A workflow is unavailable | Ask your Dreamaan administrator whether the environment supports it. |
96
97
 
97
- > **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.
98
+ 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.
98
99
 
99
- Claude Code over HTTP:
100
+ ## Update, logout and remove
100
101
 
101
- ```bash
102
- # needs the token exchange (see Authentication): the issuer, client id/key and public URL
103
- DREAMAAN_API_URL=http://localhost:3000/api DREAMAAN_ISSUER=http://localhost:3000 \
104
- MCP_OAUTH_CLIENT_ID=dreamaan-mcp MCP_OAUTH_PRIVATE_KEY="$(cat client-key.pem)" \
105
- MCP_PUBLIC_URL=http://127.0.0.1:3100/mcp pnpm dev
106
- claude mcp add --transport http dreamaan-local http://127.0.0.1:3100/mcp --header "Authorization: Bearer dmn_key_..."
107
- # in Claude Code: /mcp shows dreamaan-local; ask it to call the ping tool -> "pong"
102
+ ```sh
103
+ npm install --global @maanster/dreamaan-mcp@latest
104
+ dreamaan logout --api-url https://YOUR_API_HOST/api
105
+ npm uninstall --global @maanster/dreamaan-mcp
108
106
  ```
109
107
 
110
- Claude Desktop over stdio (`claude_desktop_config.json`):
108
+ 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.
111
109
 
112
- ```json
113
- {
114
- "mcpServers": {
115
- "dreamaan-local": {
116
- "command": "node",
117
- "args": ["/absolute/path/to/dreamaan-mcp/dist/bin/dreamaan-mcp.js", "--transport", "stdio"],
118
- "env": {
119
- "DREAMAAN_API_URL": "http://localhost:3000/api",
120
- "DREAMAAN_API_KEY": "dmn_key_..."
121
- }
122
- }
123
- }
124
- }
125
- ```
110
+ ## Additional guides
111
+
112
+ 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.
126
113
 
127
- See [output apps and client capabilities](docs/output-apps.md) for the optional
128
- read-only media player/contact sheet, trusted storage origin and text fallbacks.
114
+ ## License
129
115
 
130
- Package artifact review and public publication are documented in
131
- [docs/package-release.md](docs/package-release.md). Version `0.2.0` is Unreleased;
132
- no public npm distribution is authorized.
116
+ 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.
package/dist/bin/dreamaan-mcp.js CHANGED
@@ -815,8 +815,8 @@ import { randomBytes as randomBytes2 } from "crypto";
815
815
  // package.json
816
816
  var package_default = {
817
817
  name: "@maanster/dreamaan-mcp",
818
- version: "0.4.0",
819
- description: "Dreamaan MCP service: stateless Streamable HTTP and stdio",
818
+ version: "0.4.1",
819
+ description: "Connect AI clients to Dreamaan projects, assets and generation workflows with MCP and local OAuth.",
820
820
  private: false,
821
821
  type: "module",
822
822
  license: "UNLICENSED",
@@ -888,15 +888,12 @@ var package_default = {
888
888
  registry: "https://registry.npmjs.org/",
889
889
  access: "public"
890
890
  },
891
- repository: {
892
- type: "git",
893
- url: "git+https://github.com/copilot-rast/dreamaan-mcp.git"
894
- },
895
891
  exports: {
896
892
  ".": "./dist/index.js",
897
893
  "./skills/dreamaan/SKILL.md": "./skills/dreamaan/SKILL.md",
898
894
  "./package.json": "./package.json"
899
- }
895
+ },
896
+ homepage: "https://dreamaan.com"
900
897
  };
901
898
 
902
899
  // src/version.ts
package/dist/bin/dreamaan.js CHANGED
@@ -693,8 +693,8 @@ import { randomBytes } from "crypto";
693
693
  // package.json
694
694
  var package_default = {
695
695
  name: "@maanster/dreamaan-mcp",
696
- version: "0.4.0",
697
- description: "Dreamaan MCP service: stateless Streamable HTTP and stdio",
696
+ version: "0.4.1",
697
+ description: "Connect AI clients to Dreamaan projects, assets and generation workflows with MCP and local OAuth.",
698
698
  private: false,
699
699
  type: "module",
700
700
  license: "UNLICENSED",
@@ -766,15 +766,12 @@ var package_default = {
766
766
  registry: "https://registry.npmjs.org/",
767
767
  access: "public"
768
768
  },
769
- repository: {
770
- type: "git",
771
- url: "git+https://github.com/copilot-rast/dreamaan-mcp.git"
772
- },
773
769
  exports: {
774
770
  ".": "./dist/index.js",
775
771
  "./skills/dreamaan/SKILL.md": "./skills/dreamaan/SKILL.md",
776
772
  "./package.json": "./package.json"
777
- }
773
+ },
774
+ homepage: "https://dreamaan.com"
778
775
  };
779
776
 
780
777
  // src/version.ts
package/dist/index.js CHANGED
@@ -1165,8 +1165,8 @@ import {
1165
1165
  // package.json
1166
1166
  var package_default = {
1167
1167
  name: "@maanster/dreamaan-mcp",
1168
- version: "0.4.0",
1169
- description: "Dreamaan MCP service: stateless Streamable HTTP and stdio",
1168
+ version: "0.4.1",
1169
+ description: "Connect AI clients to Dreamaan projects, assets and generation workflows with MCP and local OAuth.",
1170
1170
  private: false,
1171
1171
  type: "module",
1172
1172
  license: "UNLICENSED",
@@ -1238,15 +1238,12 @@ var package_default = {
1238
1238
  registry: "https://registry.npmjs.org/",
1239
1239
  access: "public"
1240
1240
  },
1241
- repository: {
1242
- type: "git",
1243
- url: "git+https://github.com/copilot-rast/dreamaan-mcp.git"
1244
- },
1245
1241
  exports: {
1246
1242
  ".": "./dist/index.js",
1247
1243
  "./skills/dreamaan/SKILL.md": "./skills/dreamaan/SKILL.md",
1248
1244
  "./package.json": "./package.json"
1249
- }
1245
+ },
1246
+ homepage: "https://dreamaan.com"
1250
1247
  };
1251
1248
 
1252
1249
  // src/version.ts
package/docs/client/conventions.md CHANGED
@@ -1,56 +1,15 @@
1
- # Client workflow conventions
1
+ # Login, uploads and AI client capabilities
2
2
 
3
- Dreamaan separates OAuth grants, byte transfer and registered asset references.
4
- The CLI and local stdio MCP share a private credential profile. Remote HTTP MCP
5
- still uses the host's OAuth connection. No client package carries the service's
6
- confidential exchange key.
3
+ The CLI and local stdio MCP share the private profile for the selected API URL. Hosted MCP uses its AI client's separate OAuth connection. Local sign-in opens a browser, prints the complete URL and supports `--no-browser`. Sign in on the computer running the CLI so its local callback can complete.
7
4
 
8
- ## Public local OAuth
5
+ OAuth logout revokes the CLI connection. You can also revoke connections in Dreamaan settings. Package installation and removal do not change project access.
9
6
 
10
- The local CLI follows the native browser login pattern documented by
11
- [GitHub's MCP server](https://github.com/github/github-mcp-server/blob/main/docs/oauth-login.md):
12
- a random loopback port, PKCE S256 and a browser consent step. Dreamaan registers
13
- `dreamaan-cli` as a public client with no secret and API-audience tokens.
14
- The remote MCP token audience remains separate. The
15
- [MCP authorization specification](https://modelcontextprotocol.io/specification/draft/basic/authorization)
16
- explains the audience/resource checks behind this separation.
7
+ ## Upload workflow
17
8
 
18
- The CLI prints the complete URL on its own line and offers `--no-browser`.
19
- It never starts a browser inside a running stdio transport. Saved refresh tokens
20
- rotate under a file lock; logout revokes the connection. The same connection can
21
- be revoked in web settings under Connected Apps.
9
+ An upload creates an asset or a file version. The CLI performs transfer and registration together. AI hosts with access to original bytes can instead use `asset_upload_begin`, transfer the bytes, and inspect `asset_upload_status`. Direct transfers require `asset_upload_finalize`; API streaming finalizes automatically. Cancel using `asset_upload_abort` and its preview/confirmation flow.
22
10
 
23
- ## Upload and finalize
11
+ The `dreamaan://uploads/guide` resource and `examples_get` provide guidance to compatible hosts. Clients without resource or prompt support can use tool descriptions and examples.
24
12
 
25
- [Slack's file API](https://docs.slack.dev/messaging/working-with-files/)
26
- uses an upload-URL step followed by completion. Dreamaan likewise keeps direct
27
- storage PUT plus API finalization for large files. It additionally provides an
28
- API-hosted streaming capability URL that finalizes after the transfer.
13
+ Upload URLs and capability headers are temporary secrets. Do not share them in logs or substitute your API credentials into storage requests. The returned asset/file IDs identify the registered original. Preview and thumbnail URLs are for display.
29
14
 
30
- The server owns the session, exact expected bytes, target and caller. An upload
31
- capability gives access to only its own transfer/status, never to an API token.
32
- Before registration, the server rechecks the original user's live grant,
33
- project permissions, target visibility and quota. Status provides canonical
34
- asset/file IDs after a lost response. Idempotency is retained for the session's
35
- retention window; it is not an unlimited promise across deleted session records.
36
-
37
- Use `asset_upload_begin`, host PUT and `asset_upload_status`. For DIRECT, call
38
- `asset_upload_finalize` after PUT. `asset_upload_abort` previews the cancellation
39
- and requires its confirmation token. The `dreamaan://uploads/guide` resource
40
- and `examples_get` expose the same conventions to AI hosts. Hosts without
41
- resources use tool descriptions and examples directly.
42
-
43
- A chat attachment is usable only if its host actually exposes its original
44
- bytes for transfer. MCP cannot infer filesystem access from a displayed image.
45
- Comments and review comments keep referring to assets. This release adds no
46
- arbitrary file attachment destination or external URL importer.
47
-
48
- ## Rollout
49
-
50
- Deploy the companion backend OAuth and additive asset-upload-session migration
51
- before the MCP/CLI release, then the web onboarding and receipt forwarding.
52
- Local tests use mocks and loopback servers. They do not establish deployed
53
- browser consent, database migration safety, storage interoperability or
54
- proxy limits. Verify those in the target environment before announcing availability.
55
- The npm release remains gated by package scope ownership and licensing approval;
56
- the reviewed tarball can be installed before a registry release.
15
+ A visible chat attachment is usable only when its host exposes the actual original bytes. Comments and review comments reference assets; these tools do not add arbitrary file attachments or import arbitrary external URLs.
package/docs/client/install.md CHANGED
@@ -1,45 +1,29 @@
1
- # Install Dreamaan MCP
1
+ # Install and connect Dreamaan MCP
2
2
 
3
- The package contains two executables: `dreamaan-mcp` runs the MCP transport; `dreamaan` handles local login, diagnostics and image uploads. It also includes `skills/dreamaan/SKILL.md` and client documentation. Use Node 22 or later. These are installation instructions for the reviewed artifact and eventual registry release; no registry publication is claimed.
4
-
5
- ## Hosted clients
6
-
7
- Connect a client that supports remote Streamable HTTP and OAuth to your Dreamaan MCP endpoint. For the development environment, use `https://dev.mcp.dreamaan.com/mcp`. Select the intended environment and allowed projects during authentication. Hosted connections need no npm package and never receive the confidential MCP service key.
8
-
9
- ## Reviewed local artifact
10
-
11
- After building, generate a clean artifact with `node scripts/release/pack-smoke.mjs /tmp/dreamaan-package-review`. Install the resulting tarball in an empty directory:
3
+ Install the single public package on Linux or macOS with Node.js 22 or later:
12
4
 
13
5
  ```sh
14
- npm install --ignore-scripts /absolute/path/to/maanster-dreamaan-mcp-VERSION.tgz
15
- ./node_modules/.bin/dreamaan-mcp --version
16
- ./node_modules/.bin/dreamaan --help
6
+ npm install --global @maanster/dreamaan-mcp@0.4.1
17
7
  ```
18
8
 
19
- Replace `VERSION` with the actual reviewed package version. The pack smoke test installs the tarball into a fresh directory, checks both executables and connects the installed stdio server to a synthetic loopback API. It does not use a live account or prove registry availability.
20
-
21
- ## Public npm installation
22
-
23
- The single package `@maanster/dreamaan-mcp` contains both executables. After version 0.4.0 is published, install it with Node 22 or later:
9
+ It provides `dreamaan-mcp` and `dreamaan`. npm authentication is unnecessary for download. Dreamaan login is separate:
24
10
 
25
11
  ```sh
26
- npm install --global @maanster/dreamaan-mcp@0.4.0
27
- dreamaan --help
28
- dreamaan-mcp --version
12
+ dreamaan login --api-url https://YOUR_API_HOST/api
29
13
  ```
30
14
 
31
- Downloading the public package does not require an npm account. Dreamaan browser OAuth still authorizes access to your projects. For one-off MCP execution, use `npx --package=@maanster/dreamaan-mcp@0.4.0 dreamaan-mcp --transport stdio`.
32
-
33
- ## Local stdio
15
+ Use the API URL supplied for your environment. Configure your local MCP client to run `dreamaan-mcp --transport stdio` with `DREAMAAN_API_URL` set to that same URL. It uses the saved OAuth profile and refreshes tokens automatically. An explicit `DREAMAAN_API_KEY` takes precedence. Restart the connection after configuration changes.
34
16
 
35
- Set `DREAMAAN_API_URL` to the intended API base including `/api`. First run `dreamaan login --api-url URL`. The CLI and stdio MCP use the same saved profile and refresh rotating OAuth tokens. An explicit `DREAMAAN_API_KEY` remains supported and takes precedence over a saved profile.
17
+ Hosted MCP users instead add their environment's remote MCP URL in a client supporting Streamable HTTP and OAuth. They do not need this package. The development endpoint is `https://dev.mcp.dreamaan.com/mcp`; it is a development environment, not a production default.
36
18
 
37
- Configure your MCP client to launch `dreamaan-mcp --transport stdio` with `DREAMAAN_API_URL`. Logs use stderr and stdout carries JSON-RPC. No hosted service private key or public package secret is required.
19
+ For one-off local MCP execution:
38
20
 
39
- ## Updates and removal
21
+ ```sh
22
+ npx --package=@maanster/dreamaan-mcp@0.4.1 dreamaan-mcp --transport stdio
23
+ ```
40
24
 
41
- Pin a reviewed version and read its CHANGELOG before upgrading. Version 0.2.0 changed model/asset browsing to paged results: follow `nextCursor`, with `includeDetails` for rich metadata. Original generation URLs retain their meaning. Backends must support the new upload receipt/paging contract for the corresponding new client workflows.
25
+ Set `DREAMAAN_API_URL` in the process environment first and sign in separately.
42
26
 
43
- Upgrade with `npm install --ignore-scripts --save-exact @maanster/dreamaan-mcp@VERSION`; remove a local install with `npm uninstall @maanster/dreamaan-mcp`. Remove your MCP client's process/endpoint configuration separately and revoke the Dreamaan grant if retiring the connection. Companion OAuth logout revokes its own CLI connection and then removes the saved profile. API-key logout only removes the local copy; revoke that key in web settings. Other MCP connections and installed packages are separate.
27
+ Update with `npm install --global @maanster/dreamaan-mcp@latest`. Remove with `npm uninstall --global @maanster/dreamaan-mcp`. Remove its MCP client entry separately. Uninstallation does not revoke grants: log out or revoke the connection in Dreamaan settings.
44
28
 
45
- See [CLI](cli.md), [uploads](uploads.md), [skill](skill.md) and the repository's [release policy](https://github.com/copilot-rast/dreamaan-mcp/blob/dev/docs/package-release.md).
29
+ See the bundled [CLI](cli.md) and [upload](uploads.md) guides. All user guides ship inside the package and require no private repository access.
package/docs/client/pagination.md CHANGED
@@ -1,11 +1,9 @@
1
- # Backend paging requirements
1
+ # Browsing larger projects
2
2
 
3
- MCP 0.3.0 uses opt-in cursor paging for asset and collection shares, categories, entity links, and reverse asset collection membership. Deploy the matching backend changes before using the new scoped file and link lookups. Apply its storage-key index migration before relying on file lookup at scale.
3
+ Dreamaan MCP returns bounded pages for many browse tools. Use the response's `nextCursor` with the same filters and page size until no cursor remains. An empty page can still have a continuation cursor.
4
4
 
5
- The backend bounds shares, categories and compact reverse membership to `limit + 1` rows. Reverse membership with `includeDetails: true` retains rich collection hydration, which can read all memberships of the selected collections; keep the default compact mode for bounded work. Entity links scan at most 500 candidate rows while checking both endpoints for visibility. An empty page can still have `nextCursor`; continue until the cursor is absent. Sealed backend cursors expire after 24 hours. Permission checks run again on every request.
5
+ Cursors belong to the signed-in connection and selected filters. If a cursor expires or a connection changes, start a fresh browse. Use the default compact results when listing many records; request details for the records you need.
6
6
 
7
- Legacy array browse responses remain supported, but still require an unbounded upstream response. Existing collection member and asset listing endpoints keep their established page-based contracts. Model catalog discovery remains unpaged pending a project-aware search endpoint; this release does not claim bounded catalog discovery.
7
+ Pages reflect a changing project, not a frozen snapshot. If records move or change during browsing, restart for a fresh view. Keep actual asset and file IDs from selected results rather than guessing from names or thumbnails.
8
8
 
9
- MCP cursors bind the active user/grant, filters and page size. Restart browsing when upgrading from 0.2.0: old cursors cannot be reused. Destructive link operations use an exact permission-checked lookup rather than scanning other assets or collections.
10
-
11
- Pages describe a changing dataset, not a frozen snapshot. Editing sort keys can move a row across pages. If a response is cut to fit the MCP output budget, continuation refetches the same upstream page and skips the already-returned prefix; concurrent insertions/deletions within that page can shift the prefix. Restart browsing for a fresh view when this matters.
9
+ Some tools have different pagination inputs. Read the connected tool's description and examples before calling it. If your environment does not support a browse feature, contact its administrator.
package/docs/client/skill.md CHANGED
@@ -1,51 +1,19 @@
1
- # Dreamaan workflow skill
1
+ # Optional Dreamaan workflow skill
2
2
 
3
- `skills/dreamaan/` is a portable agent skill for the generation workflow: project discovery, reference assets, model constraints, quote, authorized start, wait and review. It complements the MCP tools and does not reimplement backend rules; schemas, limits and prices always come from the connected server.
3
+ The package includes `skills/dreamaan/`, a set of instructions for AI clients that support agent skills. It helps an assistant select projects and references, inspect model constraints, obtain a price quote, request approval before spending, and track generation results.
4
4
 
5
- ## Layout and what ships
5
+ The skill is optional. MCP tools work without it. Installing the npm package does not automatically install or enable the skill in an AI client.
6
6
 
7
- | Path | Purpose |
8
- | ------------------------------------ | ------------------------------------------------------------- |
9
- | `skills/dreamaan/SKILL.md` | Host-neutral core: workflow, hard rules, routing |
10
- | `skills/dreamaan/references/*.md` | Loaded on demand: assets and uploads, generation, conventions |
11
- | `skills/dreamaan/agents/openai.yaml` | Optional UI metadata for hosts that read it (Codex) |
7
+ ## Install
12
8
 
13
- Only Markdown and `agents/openai.yaml` are part of the skill. Tests and mock fixtures live under `test/` and are not shipped.
9
+ Run `npm root --global` to locate your global packages. Copy the complete `@maanster/dreamaan-mcp/skills/dreamaan` folder into the skills directory documented by your AI client. Keep its `references/` folder with `SKILL.md`; some clients also use `agents/openai.yaml`. Connect Dreamaan MCP in the same client, then reload the client if required.
14
10
 
15
- ## Versions
11
+ If your client has no skill loader, use the core instructions as project guidance and make the reference files available to it. Support for skills, prompts and resources varies by client.
16
12
 
17
- - Skill version: `metadata.version` in `SKILL.md` frontmatter (currently 0.2.0). Bump it when workflow rules change; keep changes reviewable as small Markdown diffs.
18
- - MCP compatibility: `metadata.mcp-compatibility` (currently `>=0.4.0 <0.5.0`). A minor MCP bump that renames, removes or changes a tool contract must re-run the skill checks and update the range (see `docs/mcp/VERSIONING.md`).
19
- - `test/unit/dreamaan-skill.test.ts` fails when a tool named in the skill disappears, a spending tool appears that the skill does not account for, or a referenced file is missing.
13
+ ## Update and remove
20
14
 
21
- ## Install (manual; nothing installs itself)
15
+ Replace the skill folder with the version from your updated npm package. Delete the copied folder to remove it. This does not remove or revoke the MCP connection.
22
16
 
23
- The skill needs the Dreamaan MCP server connected in the same host. Copy the folder; do not symlink into a shared account without the user's consent.
17
+ The skill's compatibility range is recorded in its metadata. The connected server's actual tools, model constraints, permissions and prices remain authoritative.
24
18
 
25
- | Host | Where | Notes |
26
- | ----------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
27
- | Claude Code | `~/.claude/skills/dreamaan/` (user) or `<project>/.claude/skills/dreamaan/` | `SKILL.md` frontmatter is used; `agents/openai.yaml` is ignored |
28
- | Codex | `${CODEX_HOME:-~/.codex}/skills/dreamaan/` | `agents/openai.yaml` supplies the display name and the MCP dependency hint |
29
- | Other hosts | Host-specific | If the host has no skill loader, paste `SKILL.md` into its rules or project instructions and make `references/` readable; behavior is untested |
30
-
31
- Update by replacing the folder with the one from the same or a newer package version, then restart or reload the host session if it caches skills. Remove by deleting the folder. Hosts differ in whether they list skills automatically, whether they follow relative links in `references/`, and whether they expose MCP prompts and resources; the skill is written to need none of the latter.
32
-
33
- ## Tested versions
34
-
35
- Recorded results, so nobody has to guess:
36
-
37
- | What | Result |
38
- | -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
39
- | skill-creator validator script (Codex) | Validated for 0.2.0 |
40
- | Unit tests (tool names, schemas, files, mock workflow) | Pass against MCP 0.4.0 sources in this repository |
41
- | Claude Code 2.1.294, Codex CLI 0.161.0 loading the skill | **Not tested.** Those versions were present on the author's machine; no load was run |
42
- | Live backend, paid generation, other hosts | **Not tested.** Paid benchmarks are opt-in and not part of this change |
43
-
44
- Add a row with host version and date after a manual run; never claim a host without one.
45
-
46
- ## Boundaries
47
-
48
- - No automatic installation into a user account and no public publication.
49
- - The skill never claims access to chat attachment bytes. No host chat-attachment import is supported or verified; the only known size limit is Dreamaan's 300 MiB per file, and the skill states no hosted-chat attachment limit because none is documented in this repository. Local files go through the companion `dreamaan` CLI (explicit `--api-url`, scoped API-key login from stdin or `DREAMAAN_API_KEY`, `doctor`, `upload` with a private `--state` journal); see `cli.md` and `uploads.md` in this folder. There is no browser OAuth login. The CLI is a separate component and may be absent; the skill tells the agent to check `--help`, and otherwise to use the web app.
50
- - Studio prompt assist (issue #84) is not in the verified tool set. The skill treats it as optional and tells the agent to detect it from the connected tool list.
51
- - Evaluation: `test/unit/dreamaan-skill.test.ts` replays hand-authored traces against synthetic read-only mocks and reports invalid calls, call count and response size. A failure there is a behavior regression in the scripted workflow or in the tool contract; it is not evidence of a benefit of the skill. The traces are not model output and there is no measured model baseline. A model comparison would need an opt-in paid run through the existing eval runner, which this change does not modify.
19
+ A skill cannot grant filesystem access or make chat attachment bytes available. Save an original file locally and use `dreamaan upload` if your host cannot transfer it. Paid generation still needs your explicit approval.
package/docs/client/uploads.md CHANGED
@@ -81,11 +81,3 @@ After the authorized client transfers bytes outside model context:
81
81
  }
82
82
  }
83
83
  ```
84
-
85
- The focused tests parse these documented examples against the actual tools'
86
- input schemas. Schema validity is separate from backend ownership validation.
87
-
88
- The session uploader keeps one file handle open, hashes it in 64 KiB chunks, then
89
- streams bounded chunks from that same handle. It verifies exact transferred bytes,
90
- digest and file metadata before returning or finalizing. A changing file stops the
91
- workflow. Legacy v1 recovery retains its older buffered implementation.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@maanster/dreamaan-mcp",
3
- "version": "0.4.0",
4
- "description": "Dreamaan MCP service: stateless Streamable HTTP and stdio",
3
+ "version": "0.4.1",
4
+ "description": "Connect AI clients to Dreamaan projects, assets and generation workflows with MCP and local OAuth.",
5
5
  "private": false,
6
6
  "type": "module",
7
7
  "license": "UNLICENSED",
@@ -73,13 +73,10 @@
73
73
  "registry": "https://registry.npmjs.org/",
74
74
  "access": "public"
75
75
  },
76
- "repository": {
77
- "type": "git",
78
- "url": "git+https://github.com/copilot-rast/dreamaan-mcp.git"
79
- },
80
76
  "exports": {
81
77
  ".": "./dist/index.js",
82
78
  "./skills/dreamaan/SKILL.md": "./skills/dreamaan/SKILL.md",
83
79
  "./package.json": "./package.json"
84
- }
80
+ },
81
+ "homepage": "https://dreamaan.com"
85
82
  }
package/skills/dreamaan/SKILL.md CHANGED
@@ -41,7 +41,7 @@ Read [references/conventions.md](references/conventions.md) before updating or d
41
41
 
42
42
  ## Optional and version-dependent tools
43
43
 
44
- Decide from the connected server's tool list, not from this file. Studio prompt assist (issue #84) is not part of the verified tool set: if a tool for rewriting prompts, negative prompts or suggestions is listed, read its description first (it may spend credits and never starts a generation or replaces the user's prompt by itself); if not, say it is unavailable and help with the prompt yourself. Server prompts such as `choose_generation_model` and `prepare_reference_assets` only assemble read-only context; hosts without prompt support lose nothing, use the tools directly.
44
+ Decide from the connected server's tool list, not from this file. Studio prompt assist is not part of the verified tool set: if a tool for rewriting prompts, negative prompts or suggestions is listed, read its description first (it may spend credits and never starts a generation or replaces the user's prompt by itself); if not, say it is unavailable and help with the prompt yourself. Server prompts such as `choose_generation_model` and `prepare_reference_assets` only assemble read-only context; hosts without prompt support lose nothing, use the tools directly.
45
45
 
46
46
  ## Scope
47
47
 
package/skills/dreamaan/references/generation.md CHANGED
@@ -39,6 +39,6 @@ On `done`, check `state`, `credits.actual` (and `refundState` when set) and `out
39
39
 
40
40
  Server prompts (`choose_generation_model`, `prepare_reference_assets`, `generate_shot`) load read-only context and ask for a recommendation. They are templates: they never quote, start or spend, and the host may not support prompts at all. After using one you still run the workflow above, and the spend still needs the user's approval.
41
41
 
42
- If a Studio prompt assist tool is connected (issue #84; absent in the verified tool set), treat each call as possibly paid: read its description, pass explicit project and reference bindings as it requires, show the user the proposed text, and never swap their prompt without approval. Prompt assist output is never a generation; it does not replace quote and start.
42
+ If a Studio prompt assist tool is connected (if available in the connected tool set), treat each call as possibly paid: read its description, pass explicit project and reference bindings as it requires, show the user the proposed text, and never swap their prompt without approval. Prompt assist output is never a generation; it does not replace quote and start.
43
43
 
44
44
  For valid argument shapes call `examples_get` with the tool name (for example `generation_quote`, `generation_start`); its IDs are illustrative, so use real ones from discovery.